recipe-maintainers/matrix-synapse

Fork 0

Files

notplants b730cadb06 docs: document the three federation setup options

2026-05-25 13:05:11 -04:00

7.9 KiB

Raw Blame History

Matrix (Synapse)

Category: Apps
Status: 0, work-in-progress
Image: matrixdotorg/synapse, 4, upstream
Healthcheck: Yes
Backups: No
Email: Yes
Tests: No
SSO: Yes

Basic usage

Set up Docker Swarm and abra
Deploy coop-cloud/traefik
abra app new matrix-synapse --secrets (optionally with --pass if you'd like to save secrets in pass)
abra app config YOURAPPDOMAIN - be sure to change $DOMAIN to something that resolves to your Docker swarm box
abra app deploy YOURAPPDOMAIN
Create an initial user: abra app run YOURAPPDOMAIN app register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

Tips & Tricks

Create User

register_new_matrix_user -u <username> -k $(cat /var/run/secrets/registration) -p <password>

Set Admin User

abra app cmd YOURAPPDOMAIN db set_admin <adminuser>

Disabling federation

Use DISABLE_FEDERATION=1 to turn off federation listeners
Don't use compose.matrix.yml in your traefik config to keep the federation ports closed

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.

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

Then configure whatever web service hosts example.com to serve:

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"}}

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 >= 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.

Verifying

The canonical test:

https://federationtester.matrix.org/#YOUR_SERVER_NAME

Or check the underlying paths directly. They should all return JSON:

# 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. This could be implemented in this recipe but we haven't merged it in yet. Change sets are welcome.

Bridges

For all Bridges:

Setting it up is a bit of a chicken/egg & chasing cats moment.
Make sure to uncomment APP_SERVICES_ENABLED, HOMESERVER_URL, HOMESERVER_DOMAIN, compose.shared_secret_auth.yml, SHARED_SECRET_AUTH_ENABLED and SECRET_SHARED_SECRET_AUTH_VERSION
include the registration in synapse, e.g. APP_SERVICE_CONFIGS="[\"/telegram-data/registration.yaml\"]"
and set yourself as admin, e.g.: TELEGRAM_BRIDGE_PERMISSIONS="{ \"*\": \"relaybot\", \"@akadmin:example.com\": \"admin\"}"

Important

The shared secret authenticator may break when matrix-synapse uses a newer python version with an error stating something like "module not found". You have to fix the path in the compose.shared_secret_auth.yml like here

Telegram bridging

You need to get your bot setup on the telegram side first by creating a telegram app and a telegram bot and have these values:

api_id: ...
api_hash: ...
telegram_bot_token: ...

Experimental script for a automated token replacement:

DOMAIN=<domain>
abra app secret insert $DOMAIN telegram_api_hash v1 <secret>
abra app secret insert $DOMAIN telegram_bot_token v1 <secret>
abra app secret generate -a $DOMAIN

abra app deploy $DOMAIN
abra app cmd -l $DOMAIN set_bridge_tokens telegram

Alternatively a manual guide for the necessary steps:

DOMAIN=<domain>
abra app secret insert $DOMAIN telegram_api_hash v1 <secret>
abra app secret insert $DOMAIN telegram_bot_token v1 <secret>
abra app secret generate -a $DOMAIN

abra app deploy $DOMAIN
abra app run $DOMAIN telegrambridge cat /data/registration.yaml
abra app undeploy $DOMAIN

abra app secret rm $DOMAIN telegram_as_token
abra app secret insert $DOMAIN telegram_as_token v1 <secret>

abra app secret rm $DOMAIN telegram_hs_token
abra app secret insert $DOMAIN telegram_hs_token v1 <secret>

abra app deploy $DOMAIN

Some helpful documentation:

Discord bridging

WIP docs

Just as messy as the Telegram bridging above! Rough guide:

get a local copy of config.yaml
fill it out with the values you need, all the discord token stuff, etc.
run mkdir -p data && cp config.yaml data/ then docker run --rm -v data:/data halfshot/matrix-appservice-discord:v1.0.0 sh -c "cd /data && node /build/src/discordas.js -r -u "http://discordbridge:9005" -c config.yaml"
this generates the app service registration configuration you need to feed to the homeserver
run secret generation for the discord_db_password, insert your discord_bot_token
run abra app cp <domain> discord-registration.yaml app:/discord-data (it has to be called discord-registration.yaml)
deploy the bridge & happy hacking