diff --git a/changelog.d/5973.doc b/changelog.d/5973.doc
new file mode 100644
index 0000000000..cd3b31dd21
--- /dev/null
+++ b/changelog.d/5973.doc
@@ -0,0 +1 @@
+Note public_baseurl requirement in integration tests documentation.
diff --git a/docs/integration_tests.md b/docs/integration_tests.md
index 0fa1998499..e79f966d1f 100644
--- a/docs/integration_tests.md
+++ b/docs/integration_tests.md
@@ -43,14 +43,17 @@ virtualenv -p python3 env
 source env/bin/activate
 pip install -e .
 demo/start.sh --no-rate-limit
+
 ```
 
-Alternatively, to install the latest Synapse release package (and not a cloned branch) you can run the following instead of `pip install -e .`:
+Alternatively, to install the latest Synapse release package (and not a cloned branch) you can run the following instead of `git clone` and `pip install -e .`:
 
 ```bash
 pip install matrix-synapse
 ```
 
+On your first run, you will want to stop the demo and edit the config to correct the `public_baseurl` to http://10.0.2.2:8080 and restart the server.
+
 You should now have 3 running federated Synapse instances 🎉, at http://127.0.0.1:8080/, http://127.0.0.1:8081/ and  http://127.0.0.1:8082/, which should display a "It Works! Synapse is running" message.
 
 ## Run the test
@@ -87,6 +90,18 @@ You'll need python3 to be able to run synapse
 
 Try on the Emulator browser to open "http://10.0.2.2:8080". You should see the "Synapse is running" message.
 
+### Tests partially run but some fail with "Unable to contact localhost:8080"
+
+This is because the `public_baseurl` of synapse is not consistent with the endpoint that the tests are connecting to.
+
+Ensure you have the following configuration in `demo/etc/8080.config`.
+
+```
+public_baseurl: http://10.0.2.2:8080/
+```
+
+After changing this you will need to restart synapse using `demo/stop.sh` and `demo/start.sh` to load the new configuration.
+
 ### virtualenv command fails
 
 You can try using