Add documentation for matrix federation + traefik labels for federation via port 8448 on matrix-federation entrypoint #62

Merged
notplants merged 4 commits from compress-and-federate into main 2026-06-08 18:17:35 +00:00
Owner
No description provided.
notplants added 2 commits 2026-05-25 17:08:44 +00:00
Adds a second Traefik router on the web (nginx) service that listens on
the `matrix-federation` entrypoint (host port 8448 via the traefik
recipe's compose.matrix.yml) and uses Host(${SERVER_NAME}).

Lets remote homeservers reach this server's federation/key endpoints via
the standard `<server_name>:8448` fallback when no .well-known or SRV
delegation exists for SERVER_NAME — useful when SERVER_NAME differs from
DOMAIN and no external service serves /.well-known/matrix/server.

Requires MATRIX_FEDERATION_ENABLED=1 on the traefik stack.
notplants changed title from Add documentation for matrix federation + traefik labels for federation via port 8443 on matrix-federation entrypoint to Add documentation for matrix federation + traefik labels for federation via port 8448 on matrix-federation entrypoint 2026-05-25 17:10:19 +00:00
Author
Owner

This PR makes use of the entrypoint provided by traefik here: coop-cloud/traefik#105

previously compose.matrix.yml was forwarding port 9001 (not sure why, I don't think thats used by matrix).

between these two PRs, this allows federation via port 8448

also added documentation about allowing federation via the container built-in /.well-known and via an external /.well-known (e.g. on a webserver on the apex domain)

This PR makes use of the entrypoint provided by traefik here: https://git.coopcloud.tech/coop-cloud/traefik/pulls/105 previously compose.matrix.yml was forwarding port 9001 (not sure why, I don't think thats used by matrix). between these two PRs, this allows federation via port 8448 also added documentation about allowing federation via the container built-in /.well-known and via an external /.well-known (e.g. on a webserver on the apex domain)
Owner

Looks beautiful, great docs!

Looks beautiful, great docs!
notplants added 1 commit 2026-06-04 18:31:21 +00:00
Author
Owner

ty for taking a look @3wordchant

this matrix federation stuff is really hurting my brain. the cooperative.computer matrix deployment federation broke again (because a server reboot removed the wellknown file which was not persistent from tiny-html).

I've just added Yet One More , way to do matrix federation here, which is hopefully portable and resilient

compose.wellknown.yml

tested and seems to be working but my brain is also tired so I am not sure to reasonably explain it right this second

ty for taking a look @3wordchant this matrix federation stuff is really hurting my brain. the cooperative.computer matrix deployment federation broke again (because a server reboot removed the wellknown file which was not persistent from tiny-html). I've just added Yet One More , way to do matrix federation here, which is hopefully portable and resilient `compose.wellknown.yml` tested and seems to be working but my brain is also tired so I am not sure to reasonably explain it right this second
Owner

I've just added Yet One More , way to do matrix federation here, which is hopefully portable and resilient

Ah neat idea, LGTM

> I've just added Yet One More , way to do matrix federation here, which is hopefully portable and resilient Ah neat idea, LGTM
3wordchant approved these changes 2026-06-04 21:45:38 +00:00
.env.sample Outdated
@ -26,6 +26,10 @@ SECRET_REGISTRATION_VERSION=v1
# Set "true" to enable federation endpoint on $DOMAIN/.well-known/matrix/server
Owner

Maybe worth mentioning in the .env as well that only one method is necessary? It's in the README already though so 🤷

Maybe worth mentioning in the `.env` as well that only one method is necessary? It's in the README already though so 🤷
Author
Owner

agreed. added some comments to .env.sample in case the operator doesn't make it to the readme

agreed. added some comments to .env.sample in case the operator doesn't make it to the readme
3wordchant marked this conversation as resolved
@ -43,0 +49,4 @@
#### 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:
Owner

Maybe "and when the apex domain is served by the same machine than Synapse is running on"?

Maybe "and when the apex domain is served by the same machine than Synapse is running on"?
Author
Owner

hmm I also think your phrase seems easier to understand, and i'm not 100% sure but I think maybe technically this stuff could apply even when SERVER_NAME is not apex domain ...
like could have SERVER_NAME = matrix.mydomain.tld
DOMAIN = synapse.mydomain.tld

but surely the most common situation where SERVER_NAME does not equal DOMAIN is when SERVER_NAME is apex and DOMAIN (of synapse) is a subdomain

hmm I also think your phrase seems easier to understand, and i'm not 100% sure but I think maybe technically this stuff could apply even when SERVER_NAME is not apex domain ... like could have SERVER_NAME = matrix.mydomain.tld DOMAIN = synapse.mydomain.tld but surely the most common situation where SERVER_NAME does not equal DOMAIN is when SERVER_NAME is apex and DOMAIN (of synapse) is a subdomain
Author
Owner

ah I am reading what you wrote differently now. an additional AND clause. I will add this

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. 
ah I am reading what you wrote differently now. an additional AND clause. I will add this ``` 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. ```
3wordchant marked this conversation as resolved
@ -43,0 +79,4 @@
#### 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.
Owner

Ditto, requires apex pointing to same server.

Ditto, requires apex pointing to same server.
Author
Owner

ty, added

ty, added
3wordchant marked this conversation as resolved
@ -43,0 +103,4 @@
- **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).
Owner

Maybe worth moving this warning higher up in the section?

Maybe worth moving this warning higher up in the section?
Author
Owner

ty, I moved this up

ty, I moved this up
3wordchant marked this conversation as resolved
notplants added 1 commit 2026-06-08 18:08:26 +00:00
notplants changed target branch from compress to main 2026-06-08 18:17:12 +00:00
notplants merged commit 74f1adaccb into main 2026-06-08 18:17:35 +00:00
notplants deleted branch compress-and-federate 2026-06-08 18:17:35 +00:00
Sign in to join this conversation.
No description provided.