diff --git a/.env.sample b/.env.sample index c319013..fe6fde9 100644 --- a/.env.sample +++ b/.env.sample @@ -23,6 +23,8 @@ SECRET_REGISTRATION_VERSION=v1 #DISABLE_FEDERATION=1 +# SERVE_SERVER_WELLKNOWN only works if SERVER_NAME and DOMAIN are the same +# if they are different, then a different federation method is needed (like compose.wellknown.yml) # Set "true" to enable federation endpoint on $DOMAIN/.well-known/matrix/server SERVE_SERVER_WELLKNOWN=false diff --git a/README.md b/README.md index f5843ff..755fbbb 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,8 @@ ### Enabling federation -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. +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. At least one needs to be working for federation to work (and matrix will fallback between them). #### Option 1: built-in well-known (`SERVER_NAME` = `DOMAIN`) @@ -49,7 +50,7 @@ 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: +Use when you want users to be e.g. `@alice:example.com` while Synapse runs at `matrix.example.com` (and SERVER_NAME is served by the same machine that Synapse is running on). Set: ``` SERVER_NAME=example.com @@ -79,7 +80,7 @@ ACME can issue its certificate. #### 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. +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 (also requires SERVER_NAME pointing to same server that matrix is running on). Requirements: @@ -88,8 +89,13 @@ Requirements: 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. + #### Option 4: DNS SRV records (usually not viable here) +For reasons explained below, I might be confused, but I think SRV records usually don't help with co-op cloud matrix deployments. + +You should probably prefer Option 2 (well known), but the possibility of SRV is explained below: + Federation can also be delegated with a DNS `SRV` record on `SERVER_NAME` instead of well-known: ``` @@ -103,7 +109,6 @@ The catch is TLS: on the SRV path a remote validates the certificate against **` - **SRV → `SERVER_NAME`:443 collides** — Traefik routes TLS by SNI, and `Host(SERVER_NAME)` on `:443` is already owned by whatever apex site serves `SERVER_NAME`. - **SRV → `SERVER_NAME`:8448 works** — the Option 3 `matrix-federation` router holds a cert for `SERVER_NAME` — but that's just Option 3 made explicit (the `:8448` fallback already works with no SRV record). -So I think SRV does little here. Probably prefer Option 2 (well-known). #### Verifying