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

See #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!

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.

Matrix Authentication Service (MAS)

MAS is Element’s OAuth/OIDC-native auth service for Matrix: it handles login, tokens, and upstream IdPs while Synapse delegates authentication via matrix_authentication_service.

Enable the stack:

In .env, uncomment compose.mas.yml (and compose.mas-upstream.yml plus upstream envs if you use an external IdP), and uncomment the SECRET_MAS_* version lines.
abra app secret generate YOURAPPDOMAIN
Manually insert the PEM RSA key for SECRET_MAS_SIGNING_RSA_VERSION (generate=false in .env.sample) — abra cannot generate that format; see the comment there (e.g. openssl genrsa 2048 piped to abra app secret insert).
abra app cmd YOURAPPDOMAIN db ensure_mas_database (once, creates the mas database in Postgres)
abra app deploy YOURAPPDOMAIN

If you plan to migrate an existing homeserver with syn2mas: deploy and configure MAS as above, but leave MAS_ENABLED=1 commented until migration and cutover are done, so Synapse keeps using your current login path until you intentionally switch. You cannot use Synapse legacy OIDC/Keycloak SSO alongside MAS; plan IdP apps and envs accordingly.

Migrating an existing server (syn2mas)

Requires PostgreSQL on Synapse and a dedicated MAS database. Backup Postgres (and configs) before you start. Official background: MAS migration guide.

Prepare (Synapse still running): With MAS in COMPOSE_FILE but MAS_ENABLED still off, deploy, then run checks from your machine:
```
abra app cmd YOURAPPDOMAIN prepare_mas_migration
```
This fetches rendered homeserver.yaml into the MAS container, runs syn2mas check, then migrate --dry-run (the dry run rolls back MAS data at the end). The file stays in the MAS container until next restart, so you can repeat this step to provide the file for the actual migration.
Optional snapshot: save a copy of the rendered config while app is up, e.g. abra app run -t YOURAPPDOMAIN app cat /data/homeserver.yaml > homeserver.snapshot.yaml.
Downtime — stop Synapse: run on the host with Docker/Swarm access (not inside a container), e.g.:
```
docker service scale <STACK_NAME>_app=0
```
Use the real service name from docker service ls (suffix _app).

Migration: with MAS still running and Synapse at zero replicas,

abra app run YOURAPPDOMAIN mas -- mas-cli syn2mas migrate \
  --config /etc/mas/config.yaml \
  --synapse-config /tmp/homeserver.yaml

Cutover: in .env, set MAS_ENABLED=1, PASSWORD_LOGIN_ENABLED=false, remove legacy Keycloak/SSO envs, then abra app deploy YOURAPPDOMAIN (Synapse comes back with MAS delegation). syn2mas does not write to the Synapse database; if you abort before serving traffic through MAS, you can often drop and recreate the MAS DB and revert env.

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

Some helpful documentation:

Signal bridging

Experimental script for a more automated token replacement:

DOMAIN=<domain>
abra app secret generate -a $DOMAIN
abra app deploy $DOMAIN
abra app cmd -l $DOMAIN set_bridge_tokens signal