diff --git a/.gitignore b/.gitignore
index 2bccf19997..2cef1b0a5a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,7 @@
 _trial_temp/
 _trial_temp*/
 /out
+.DS_Store
 
 # stuff that is likely to exist when you run a server locally
 /*.db
diff --git a/INSTALL.md b/INSTALL.md
index 656833637c..d405d9fe55 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -190,7 +190,8 @@ via brew and inform `pip` about it so that `psycopg2` builds:
 
 ```sh
 brew install openssl@1.1
-export LDFLAGS=-L/usr/local/Cellar/openssl\@1.1/1.1.1d/lib/
+export LDFLAGS="-L/usr/local/opt/openssl/lib"
+export CPPFLAGS="-I/usr/local/opt/openssl/include"
 ```
 
 ##### OpenSUSE
diff --git a/README.rst b/README.rst
index 9ff375708b..af914d71a8 100644
--- a/README.rst
+++ b/README.rst
@@ -280,6 +280,27 @@ differ)::
 
     PASSED (skips=15, successes=1322)
 
+We recommend using the demo which starts 3 federated instances running on ports `8080` - `8082`
+
+    ./demo/start.sh
+
+(to stop, you can use `./demo/stop.sh`)
+
+If you just want to start a single instance of the app and run it directly:
+
+    # Create the homeserver.yaml config once
+    python -m synapse.app.homeserver \
+      --server-name my.domain.name \
+      --config-path homeserver.yaml \
+      --generate-config \
+      --report-stats=[yes|no]
+
+    # Start the app
+    python -m synapse.app.homeserver --config-path homeserver.yaml
+
+
+
+
 Running the Integration Tests
 =============================
 
diff --git a/changelog.d/8997.doc b/changelog.d/8997.doc
new file mode 100644
index 0000000000..dd1a882301
--- /dev/null
+++ b/changelog.d/8997.doc
@@ -0,0 +1 @@
+Add some extra docs for getting Synapse running on macOS.