194 lines
9.0 KiB
Markdown
194 lines
9.0 KiB
Markdown
# Matrix (Synapse)
|
||
|
||
<!-- metadata -->
|
||
|
||
* **Category**: Apps
|
||
* **Status**: 0, work-in-progress
|
||
* **Image**: [`matrixdotorg/synapse`](https://hub.docker.com/r/matrixdotorg/synapse), 4, upstream
|
||
* **Healthcheck**: Yes
|
||
* **Backups**: No
|
||
* **Email**: Yes
|
||
* **Tests**: No
|
||
* **SSO**: Yes
|
||
|
||
<!-- endmetadata -->
|
||
|
||
## Basic usage
|
||
|
||
1. Set up Docker Swarm and [`abra`](https://docs.coopcloud.tech/abra/)
|
||
2. Deploy [`coop-cloud/traefik`](https://git.coopcloud.tech/coop-cloud/traefik)
|
||
3. `abra app new matrix-synapse --secrets` (optionally with `--pass` if you'd like to save secrets in `pass`)
|
||
4. `abra app config YOURAPPDOMAIN` - be sure to change `$DOMAIN` to something that resolves to your Docker swarm box
|
||
5. `abra app deploy YOURAPPDOMAIN`
|
||
6. 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`](https://git.coopcloud.tech/coop-cloud/traefik/src/branch/master/compose.matrix.yml) in your traefik config to keep the federation ports closed
|
||
|
||
### 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!
|
||
|
||
### 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.
|
||
|
||
### Matrix Authentication Service (MAS)
|
||
|
||
[MAS](https://element-hq.github.io/matrix-authentication-service/) 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`.
|
||
|
||
> [!IMPORTANT]
|
||
> **If you plan to migrate an existing homeserver with `syn2mas`:** deploy and configure MAS as below, 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.
|
||
|
||
**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`
|
||
- `abra app cmd -l YOURAPPDOMAIN generate_mas_signing_rsa` — generates and inserts the PEM RSA key for `SECRET_MAS_SIGNING_RSA_VERSION`. Requires `openssl` on the local machine.
|
||
- `abra app cmd YOURAPPDOMAIN db ensure_mas_database` (once, creates the `mas` database in Postgres)
|
||
- `abra app deploy YOURAPPDOMAIN`
|
||
|
||
<details>
|
||
<summary><strong>Migrating an existing server (<code>syn2mas</code>)</strong></summary>
|
||
|
||
Requires PostgreSQL on Synapse and a dedicated MAS database. Backup Postgres (and configs) before you start. Official background: [MAS migration guide](https://element-hq.github.io/matrix-authentication-service/setup/migration.html).
|
||
|
||
1. **Prepare (Synapse still running):** With MAS in `COMPOSE_FILE` but **`MAS_ENABLED` still off**, deploy, then run checks from your machine:
|
||
```bash
|
||
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.
|
||
|
||
2. **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`.
|
||
|
||
3. **Downtime — stop Synapse:** run on the **host** with Docker/Swarm access (not inside a container), e.g.:
|
||
```bash
|
||
docker service scale <STACK_NAME>_app=0
|
||
```
|
||
Use the real service name from `docker service ls` (suffix `_app`).
|
||
|
||
4. **Migration:** with MAS still running and Synapse at zero replicas, run `run_mas_migration` from your machine. The homeserver snapshot at `/tmp/homeserver.yaml` in `mas` must still be present from step 1.
|
||
```bash
|
||
abra app cmd YOURAPPDOMAIN run_mas_migration
|
||
```
|
||
|
||
5. **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.
|
||
|
||
</details>
|
||
|
||
## 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](https://git.coopcloud.tech/coop-cloud/matrix-synapse/commit/3d1350533079ce1ad3bea92039fe003684589b95)
|
||
|
||
### Telegram bridging
|
||
|
||
You need to get your bot setup on the telegram side first by creating a [telegram app](https://my.telegram.org/apps) and a [telegram bot](https://docs.mau.fi/bridges/python/telegram/relay-bot.html#setup) 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:
|
||
|
||
- [`docs.mau.fi`](https://docs.mau.fi/bridges/python/setup/docker.html?bridge=telegram)
|
||
- [`example-config.yaml`](https://mau.dev/mautrix/telegram/-/blob/master/mautrix_telegram/example-config.yaml)
|
||
|
||
### Discord bridging
|
||
|
||
> WIP docs
|
||
|
||
Just as messy as the Telegram bridging above! Rough guide:
|
||
|
||
- get a local copy of [`config.yaml`](https://github.com/matrix-org/matrix-appservice-discord/blob/develop/config/config.sample.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:
|
||
|
||
- [`matrix-org/matrix-appservice-discord` docs](https://github.com/matrix-org/matrix-appservice-discord#bridging-a-room)
|
||
- [`t2bot.io/discord`](https://t2bot.io/discord/)
|
||
|
||
### 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
|
||
```
|
||
Alternatively a manual guide for the necessary steps:
|
||
```
|
||
DOMAIN=<domain>
|
||
abra app secret insert $DOMAIN signal_hs_token v1 foo
|
||
abra app secret insert $DOMAIN signal_as_token v1 foo
|
||
abra app secret generate $DOMAIN -a
|
||
abra app deploy $DOMAIN
|
||
abra app run $DOMAIN signalbridge cat /data/registration.yaml
|
||
|
||
abra app secret rm $DOMAIN signal_as_token
|
||
abra app secret insert $DOMAIN signal_as_token v1 <secret>
|
||
abra app secret rm $DOMAIN signal_hs_token
|
||
abra app secret insert $DOMAIN signal_hs_token v1 <secret>
|
||
|
||
abra app deploy $DOMAIN
|
||
```
|
||
|
||
- message `@signalbot:example.com` to test
|
||
- See the [docs](https://docs.mau.fi/bridges/go/signal/authentication.html) for authentication
|