recipe-maintainers/matrix-synapse
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improvements to readme

Browse Source
This commit is contained in:
notplants
2026-06-08 14:03:16 -04:00
parent e257349b37
commit f836c74386
2 changed files with 11 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.env.sample
View File

@ -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

13
README.md
View File

@ -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