From 9b7aa543d9fc90d3a754ab129a619cfff6a71355 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Thu, 7 Feb 2019 18:46:02 +0000
Subject: [PATCH 1/2] clarify option 1

---
 docs/MSC1711_certificates_FAQ.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md
index eee37d9457..414af96ef3 100644
--- a/docs/MSC1711_certificates_FAQ.md
+++ b/docs/MSC1711_certificates_FAQ.md
@@ -112,7 +112,7 @@ _matrix._tcp.example.com. IN SRV 10 5 443 customer.example.net.
 
 In this situation, you have two choices for how to proceed:
 
-#### Option 1: give Synapse a certificate for your matrix domain
+#### Option 1: give Synapse (or a reverse-proxy) a certificate for your matrix domain
 
 Synapse 1.0 will expect your server to present a TLS certificate for your
 `server_name` (`example.com` in the above example). You can achieve this by

From c17b128b837f58cb59ba75803e32c8a720cf8501 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Thu, 7 Feb 2019 19:18:08 +0000
Subject: [PATCH 2/2] Update ACME docs to include port instructions (#4578)

---
 changelog.d/4578.misc |  1 +
 docs/ACME.md          | 26 +++++++++++++++-----------
 2 files changed, 16 insertions(+), 11 deletions(-)
 create mode 100644 changelog.d/4578.misc

diff --git a/changelog.d/4578.misc b/changelog.d/4578.misc
new file mode 100644
index 0000000000..d1c006bb6b
--- /dev/null
+++ b/changelog.d/4578.misc
@@ -0,0 +1 @@
+Add port configuration information to ACME instructions.
\ No newline at end of file
diff --git a/docs/ACME.md b/docs/ACME.md
index 8fb2bd66a9..e555c7c939 100644
--- a/docs/ACME.md
+++ b/docs/ACME.md
@@ -41,10 +41,10 @@ placed in Synapse's config directory without the need for any ACME setup.
 
 The main steps for enabling ACME support in short summary are:
 
-1. Allow Synapse to listen on port 80 with authbind, or forward it from a reverse-proxy.
-1. Set `acme:enabled` to `true` in homeserver.yaml.
+1. Allow Synapse to listen for incoming ACME challenges.
+1. Enable ACME support in `homeserver.yaml`.
 1. Move your old certificates (files `example.com.tls.crt` and `example.com.tls.key` out of the way if they currently exist at the paths specified in `homeserver.yaml`.
-1. Restart Synapse
+1. Restart Synapse.
 
 Detailed instructions for each step are provided below.
 
@@ -71,7 +71,7 @@ location /.well-known/acme-challenge {
 }
 ```
 
-For Apache, add the following to your existing webserver config::
+For Apache, add the following to your existing webserver config:
 
 ```
 ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge
@@ -79,6 +79,14 @@ ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-cha
 
 Make sure to restart/reload your webserver after making changes.
 
+Now make the relevant changes in `homeserver.yaml` to enable ACME support:
+
+```
+acme:
+    enabled: true
+    port: 8009
+```
+
 
 #### Authbind
 
@@ -102,24 +110,20 @@ sudo touch /etc/authbind/byport/80
 sudo chmod 777 /etc/authbind/byport/80
 ```
 
-When Synapse is started, use the following syntax::
+When Synapse is started, use the following syntax:
 
 ```
 authbind --deep <synapse start command>
 ```
 
-### Config file editing
-
-Once Synapse is able to listen on port 80 for ACME challenge
-requests, it must be told to perform ACME provisioning by setting `enabled`
-to true under the `acme` section in `homeserver.yaml`:
+Make the relevant changes in `homeserver.yaml` to enable ACME support:
 
 ```
 acme:
     enabled: true
 ```
 
-### Starting synapse
+### (Re)starting synapse
 
 Ensure that the certificate paths specified in `homeserver.yaml` (`tls_certificate_path` and `tls_private_key_path`) do not currently point to any files. Synapse will not provision certificates if files exist, as it does not want to overwrite existing certificates.