first draft of adding .well-known to general docs

docs/well-known.md

@@ -0,0 +1,49 @@
+# Well-Known
+
+The mapping for a server name to a hostname for federation is done via
+`SRV` records. Synapse v1.0 mandates valid X.509 certificates for the
+federation endpoint where the certificate must match the server name.
+
+This presents difficulties for hosted server offerings: ExampleCorp
+may want to delegate responsibility for running its Matrix homeserver to an
+outside supplier, but it may be difficult for that supplier to obtain a TLS
+certificate for `exmaple.com` (and ExampleCorp may be reluctant to let them have
+one).
+
+`.well-known` solves this problem by augmenting the current `SRV` record
+with a `.well-known` lookup.
+
+## Configuring `.well-known`
+
+ 1. Give synapse a certificate corresponding to the target domain
+    (`customer.example.net`). Currently Synapse's ACME
+    support [does not support
+    this](https://github.com/matrix-org/synapse/issues/4552), so you will have
+    to acquire a certificate yourself and give it to Synapse via
+    `tls_certificate_path` and `tls_private_key_path`.
+
+ 2. Restart Synapse to ensure the new certificate is loaded.
+
+ 3. Arrange for a `.well-known` file at
+    `https://<server_name>/.well-known/matrix/server` with contents:
+
+    ```json
+    {"m.server": "<target server name>"}
+    ```
+
+    where the target server name is resolved as usual (i.e. SRV lookup, falling
+    back to talking to port 8448).
+
+    In the above example, where synapse is listening on port 8000,
+    `https://example.com/.well-known/matrix/server` should have `m.server`
+    set to one of:
+
+    1. `customer.example.net` ─ with a SRV record on
+       `_matrix._tcp.customer.example.com` pointing to port 8000, or:
+
+    2. `customer.example.net` ─ updating synapse to listen on the default port
+       8448, or:
+
+    3. `customer.example.net:8000` ─ ensuring that if there is a reverse proxy
+       on `customer.example.net:8000` it correctly handles HTTP requests with
+       Host header set to `customer.example.net:8000`.