docs: document the three federation setup options

README.md

@@ -39,7 +39,57 @@
 
 ### Enabling federation
 
-See [`#27`](https://git.coopcloud.tech/coop-cloud/matrix-synapse/pulls/27) for more. Depending on your setup, using `SERVE_SERVER_WELLKNOWN=true` might work to start federating. Make sure you don't leave `DISABLE_FEDERATION=1` set!
+Federation is on by default (`DISABLE_FEDERATION=0`). Remote homeservers need a way to discover the host:port that serves your `SERVER_NAME`. There are three supported approaches.
+
+#### Option 1: built-in well-known (`SERVER_NAME` = `DOMAIN`)
+
+Set `SERVE_SERVER_WELLKNOWN=true` and leave `SERVER_NAME` unset (defaults to `DOMAIN`). The recipe's nginx serves `/.well-known/matrix/server` and `/.well-known/matrix/client` on `DOMAIN`. Suitable when users are e.g. `@alice:matrix.example.com`.
+
+#### Option 2: external well-known on `SERVER_NAME`
+
+Use when you want users to be e.g. `@alice:example.com` while Synapse runs at `matrix.example.com`. Set:
+
+```
+SERVER_NAME=example.com
+DOMAIN=matrix.example.com
+SERVE_SERVER_WELLKNOWN=false
+```
+
+Then configure whatever web service hosts `example.com` to serve:
+
+- `https://example.com/.well-known/matrix/server` → `{"m.server": "matrix.example.com:443"}`
+- `https://example.com/.well-known/matrix/client` → `{"m.homeserver": {"base_url": "https://matrix.example.com"}}`
+
+
+#### Option 3: Traefik `matrix-federation` entrypoint (port 8448)
+
+Use when `SERVER_NAME` ≠ `DOMAIN` but you have no separate web service at `SERVER_NAME`. Remote homeservers fall back to `SERVER_NAME:8448` when there's no delegation.
+
+Requirements:
+
+- [traefik](https://git.coopcloud.tech/coop-cloud/traefik) `>= 5.1.2+v3.6.15` with `MATRIX_FEDERATION_ENABLED=1` and `compose.matrix.yml` enabled.
+- `SERVER_NAME` set in your matrix-synapse env (used by the federation router's Host rule).
+
+With these in place, the recipe publishes a Traefik router on `Host(${SERVER_NAME})` via the `matrix-federation` entrypoint, reusing the existing matrix nginx → synapse path.
+
+#### Verifying
+
+The canonical test:
+
+- https://federationtester.matrix.org/#YOUR_SERVER_NAME
+
+Or check the underlying paths directly. They should all return JSON:
+
+```bash
+# Options 1 & 2 — delegation
+curl https://SERVER_NAME/.well-known/matrix/server
+
+# Option 3 — federation endpoint via 8448
+curl https://SERVER_NAME:8448/_matrix/key/v2/server
+
+# Confirms Synapse itself is healthy (independent of the path remote servers use)
+curl https://DOMAIN/_matrix/key/v2/server
+```
 
 ### Getting client discovery on a custom domain