|
|
|
@@ -39,11 +39,95 @@
|
|
|
|
|
|
|
|
|
|
### 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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The two paths that must be served on `SERVER_NAME` are:
|
|
|
|
|
|
|
|
|
|
- `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"}}`
|
|
|
|
|
|
|
|
|
|
**Recommended — let this recipe serve them via Traefik** by enabling `compose.wellknown.yml`:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
COMPOSE_FILE="$COMPOSE_FILE:compose.wellknown.yml"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This publishes a Traefik router `Host(${SERVER_NAME}) && PathPrefix(/.well-known/matrix)`
|
|
|
|
|
pointing at the matrix nginx, which already serves both files. The path-scoped, high-priority
|
|
|
|
|
rule coexists with any apex website that also serves `Host(${SERVER_NAME})` — that site keeps
|
|
|
|
|
serving everything except `/.well-known/matrix`. `SERVER_NAME` must resolve to this Traefik so
|
|
|
|
|
ACME can issue its certificate.
|
|
|
|
|
|
|
|
|
|
**Alternative** — serve the two files yourself from whatever already hosts `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.
|
|
|
|
|
|
|
|
|
|
#### Option 4: DNS SRV records (usually not viable here)
|
|
|
|
|
|
|
|
|
|
Federation can also be delegated with a DNS `SRV` record on `SERVER_NAME` instead of well-known:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
_matrix-fed._tcp.example.com. 3600 IN SRV 10 0 8448 matrix.example.com. # modern
|
|
|
|
|
_matrix._tcp.example.com. 3600 IN SRV 10 0 8448 matrix.example.com. # deprecated, for older peers
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The catch is TLS: on the SRV path a remote validates the certificate against **`SERVER_NAME`**, *not* the SRV target. This recipe's Traefik only issues a cert for **`DOMAIN`**, so:
|
|
|
|
|
|
|
|
|
|
- **SRV → `DOMAIN`:443 fails** — the presented cert is for `DOMAIN`, but the peer requires one for `SERVER_NAME`.
|
|
|
|
|
- **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
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
You'll need to deploy something like [this](https://git.autonomic.zone/ruangrupa/well-known-uris). This could be implemented in this recipe but we haven't merged it in yet. Change sets are welcome.
|
|
|
|
|
Enable `compose.wellknown.yml` (see Option 2 above) — it serves `/.well-known/matrix/client`
|
|
|
|
|
on `SERVER_NAME` too, so clients signing in as `@alice:example.com` auto-discover the homeserver.
|
|
|
|
|
|
|
|
|
|
## Bridges
|
|
|
|
|
For all Bridges:
|
|
|
|
|
notplants