improve documentation of federation

compose.wellknown.yml

@@ -0,0 +1,24 @@
+---
+version: "3.8"
+
+# Serve /.well-known/matrix/{server,client} on SERVER_NAME via Traefik, routed to
+# the matrix nginx (`web`) — so server/client delegation works without hand-placing
+# files on whatever else hosts SERVER_NAME.
+#
+# Enable when SERVER_NAME != DOMAIN (users are @alice:example.com, Synapse runs at
+# matrix.example.com). The PathPrefix rule is more specific than a bare Host()
+# router, and the explicit high priority guarantees it wins over any apex website
+# that also serves Host(SERVER_NAME) — so the two coexist, the apex site keeps
+# serving everything except /.well-known/matrix.
+#
+# Requires SERVER_NAME to resolve to this Traefik so ACME can issue its cert.
+services:
+  web:
+    deploy:
+      labels:
+        - "traefik.http.routers.${STACK_NAME}-wellknown.rule=Host(`${SERVER_NAME}`) && PathPrefix(`/.well-known/matrix`)"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.entrypoints=web-secure"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.tls=true"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.tls.certresolver=${LETS_ENCRYPT_ENV}"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.service=${STACK_NAME}"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.priority=1000"