Merge pull request 'Add documentation for matrix federation + traefik labels for federation via port 8448 on matrix-federation entrypoint' (#62) from compress-and-federate into main

Reviewed-on: https://git.coopcloud.tech/coop-cloud/matrix-synapse/pulls/62
Reviewed-by: 3wordchant <3wordchant@noreply.git.coopcloud.tech>

.drone.yml

@@ -0,0 +1,53 @@
+---
+kind: pipeline
+name: deploy to swarm-test.autonomic.zone
+steps:
+  - name: deployment
+    image: git.coopcloud.tech/coop-cloud/stack-ssh-deploy:latest
+    settings:
+      host: swarm-test.autonomic.zone
+      stack: matrix-synapse
+      generate_secrets: true
+      purge: true
+      deploy_key:
+        from_secret: drone_ssh_swarm_test
+      networks:
+        - proxy
+    environment:
+      DOMAIN: matrix-synapse.swarm-test.autonomic.zone
+      STACK_NAME: matrix-synapse
+      LETS_ENCRYPT_ENV: production
+      DISCORD_BRIDGE_YAML_VERSION: v2
+      ENTRYPOINT_CONF_VERSION: v3
+      HOMESERVER_YAML_VERSION: v29
+      LOG_CONFIG_VERSION: v2
+      SHARED_SECRET_AUTH_VERSION: v2
+      SIGNAL_BRIDGE_YAML_VERSION: v5
+      TELEGRAM_BRIDGE_YAML_VERSION: v6
+      PG_BACKUP_VERSION: v1
+      WK_CLIENT_VERSION: v1
+      WK_SERVER_VERSION: v1
+      NGINX_CONFIG_VERSION: v8
+      SECRET_DB_PASSWORD_VERSION: v1
+      SECRET_FORM_SECRET_VERSION: v1
+      SECRET_MACAROON_VERSION: v1
+      SECRET_REGISTRATION_VERSION: v1
+trigger:
+  branch:
+    - main
+---
+kind: pipeline
+name: generate recipe catalogue
+steps:
+  - name: release a new version
+    image: plugins/downstream
+    settings:
+      server: https://build.coopcloud.tech
+      token:
+        from_secret: drone_abra-bot_token
+      fork: true
+      repositories:
+        - toolshed/auto-recipes-catalogue-json
+
+trigger:
+  event: tag

.env.sample

@@ -1,44 +1,38 @@
 TYPE=matrix-synapse
-
-DOMAIN=matrix.example.com
+DOMAIN=matrix-synapse.example.com
+# SERVER_NAME=example.com
+TIMEOUT=300
+ENABLE_AUTO_UPDATE=true
 LETS_ENCRYPT_ENV=production
+COMPOSE_FILE="compose.yml"
+# POST_DEPLOY_CMDS="db set_admin"
+ENABLE_BACKUPS=true
+
+## Admin details
+
+ADMIN_EMAIL=admin@example.com
+
+## Secrets
 
 SECRET_DB_PASSWORD_VERSION=v1
-
-SYNAPSE_ADMIN_EMAIL=admin@example.com
-
-SECRET_REGISTRATION_SHARED_SECRET_VERSION=v1
-SECRET_MACAROON_SECRET_KEY_VERSION=v1
 SECRET_FORM_SECRET_VERSION=v1
+SECRET_MACAROON_VERSION=v1
+SECRET_REGISTRATION_VERSION=v1
 
-COMPOSE_FILE="compose.yml"
+## Authentication
 
-#DISABLE_FEDERATION=1
+# All login / SSO / MAS-related toggles in one place.
 
-# Set "true" to enable federation endpoint on $DOMAIN/.well-known/matrix/server
-SERVE_SERVER_WELLKNOWN=false
+### Local password & registration (Synapse native)
 
-ENABLE_REGISTRATION=false
+# With MAS_ENABLED=1 you must set PASSWORD_LOGIN_ENABLED=false — Synapse forbids legacy password DB alongside matrix_authentication_service.
 PASSWORD_LOGIN_ENABLED=true
+ENABLE_REGISTRATION=false
 
-#AUTO_JOIN_ROOM_ENABLED=1
-#AUTO_JOIN_ROOM="#example:example.com"
+# Token based registration. Enable ADMIN_INTERFACE (below) to use the admin interface to generate tokens.
+#REGISTRATION_REQUIRES_TOKEN=true
 
-SQL_LOG_LEVEL=WARN
-ROOT_LOG_LEVEL=WARN
-
-REDACTION_RETENTION_PERIOD=7d
-
-RETENTION_MAX_LIFETIME=4w
-
-ENABLE_3PID_LOOKUP=true
-
-USER_IPS_MAX_AGE=1d
-
-ENCRYPTED_BY_DEFAULT=all
-
-#ENABLE_ALLOWLIST=1
-#FEDERATION_ALLOWLIST="[]"
+### OIDC via Keycloak-shaped API (e.g. Authentik)
 
 #COMPOSE_FILE="$COMPOSE_FILE:compose.keycloak.yml"
 #KEYCLOAK_ENABLED=1
@@ -50,6 +44,8 @@ ENCRYPTED_BY_DEFAULT=all
 #KEYCLOAK_ALLOW_EXISTING_USERS=false
 #SECRET_KEYCLOAK_CLIENT_SECRET_VERSION=v1
 
+### Second OIDC provider (compose.keycloak2.yml)
+
 #COMPOSE_FILE="$COMPOSE_FILE:compose.keycloak2.yml"
 #KEYCLOAK2_ENABLED=1
 #KEYCLOAK2_ID=keycloak2
@@ -60,13 +56,136 @@ ENCRYPTED_BY_DEFAULT=all
 #KEYCLOAK2_ALLOW_EXISTING_USERS=false
 #SECRET_KEYCLOAK2_CLIENT_SECRET_VERSION=v1
 
+### Third OIDC provider (compose.keycloak3.yml)
+
+#COMPOSE_FILE="$COMPOSE_FILE:compose.keycloak3.yml"
+#KEYCLOAK3_ENABLED=1
+#KEYCLOAK3_ID=keycloak3
+#KEYCLOAK3_NAME=
+#KEYCLOAK3_URL=
+#KEYCLOAK3_CLIENT_ID=
+#KEYCLOAK3_CLIENT_DOMAIN=
+#KEYCLOAK3_ALLOW_EXISTING_USERS=false
+#SECRET_KEYCLOAK3_CLIENT_SECRET_VERSION=v1
+
+### Matrix Authentication Service (MAS) — Element X / OIDC-native auth
+
+#COMPOSE_FILE="$COMPOSE_FILE:compose.mas.yml"
+#MAS_ENABLED=1 # Leave commented if you plan to migrate an existing homeserver
+#PASSWORD_LOGIN_ENABLED=false
+#SECRET_MAS_ENCRYPTION_VERSION=v1 # length=64 charset=hex
+#SECRET_MAS_SYNAPSE_SHARED_VERSION=v1 # length=64 charset=hex
+# PEM private key: abra cannot generate this format — use `abra app cmd -l YOURAPPDOMAIN generate_mas_signing_rsa`
+#SECRET_MAS_SIGNING_RSA_VERSION=v1 # generate=false
+
+#### MAS upstream OIDC provider (e.g. Authentik)
+# Create a new OAuth2 app in your IdP with redirect URI: https://<DOMAIN>/upstream/callback/<MAS_UPSTREAM_PROVIDER_ID>
+#COMPOSE_FILE="$COMPOSE_FILE:compose.mas-upstream.yml"
+#MAS_UPSTREAM_PROVIDER_ID=          # ULID, e.g. 01JSHPZHAXC50QBKH67MH33TNF — generate at https://www.ulidtools.com
+#MAS_UPSTREAM_ISSUER=               # e.g. https://auth.example.com/application/o/matrix-mas/
+#MAS_UPSTREAM_CLIENT_ID=
+#MAS_UPSTREAM_HUMAN_NAME=Authentik
+# For migration from previous direct Keycloud-style config: set to oidc-<your old KEYCLOAK_ID> so syn2mas maps users correctly.
+#MAS_UPSTREAM_SYNAPSE_IDP_ID=
+#SECRET_MAS_UPSTREAM_CLIENT_VERSION=v1
+
+### Shared secret auth (bridges / automation)
+
+#COMPOSE_FILE="$COMPOSE_FILE:compose.shared_secret_auth.yml"
+#SHARED_SECRET_AUTH_ENABLED=1
+#SECRET_SHARED_SECRET_AUTH_VERSION=v1 # length=128
+
+## Federation
+
+#DISABLE_FEDERATION=1
+
+# SERVE_SERVER_WELLKNOWN only works if SERVER_NAME and DOMAIN are the same
+# if they are different, then a different federation method is needed (like compose.wellknown.yml)
+# Set "true" to enable federation endpoint on $DOMAIN/.well-known/matrix/server
+SERVE_SERVER_WELLKNOWN=false
+
+# Serve /.well-known/matrix/{server,client} on SERVER_NAME via Traefik.
+# Can be used when SERVER_NAME != DOMAIN and SERVER_NAME is served by Traefik.
+#COMPOSE_FILE="$COMPOSE_FILE:compose.wellknown.yml"
+
+ALLOW_PUBLIC_ROOMS_FEDERATION=false
+
+## Room auto-join
+
+#AUTO_JOIN_ROOM_ENABLED=1
+#AUTO_JOIN_ROOM="#example:example.com"
+
+## Logging
+
+# for the homserver
+SQL_LOG_LEVEL=WARN
+ROOT_LOG_LEVEL=WARN
+
+# for nginx
+NGINX_ACCESS_LOG_LOCATION="/dev/null"
+NGINX_ERROR_LOG_LOCATION="/dev/null"
+# Comment the previous two lines and uncomment these to enable logging
+#NGINX_ACCESS_LOG_LOCATION="/dev/stdout"
+#NGINX_ERROR_LOG_LOCATION="/dev/stderr"
+
+## Privacy
+
+ENABLE_3PID_LOOKUP=true
+
+USER_IPS_MAX_AGE=1d
+
+ENCRYPTED_BY_DEFAULT=all
+
+#ENABLE_ALLOWLIST=1
+#FEDERATION_ALLOWLIST="[]"
+
+# Set these to keyservers you trust - usually the same as your federation allowlist
+#TRUSTED_KEYSERVERS="trusted_key_servers:\n  - server_name: 'example.com'\n  - server_name: 'example2.com'"
+
+# some optional configs to increase privacy and security
+#REQUIRE_AUTH_FOR_PROFILE_REQUESTS=true
+#LIMIT_PROFILE_REQUESTS_TO_USERS_WHO_SHARE_ROOMS=true
+#DELETE_STALE_DEVICES_AFTER=1y
+#SESSION_LIFETIME=60d
+#TRACK_PUPPETED_USER_IPS=true
+
+
+## Room complexity limit (prevents joining large remote rooms that cause DB bloat)
+## complexity ≈ state_events / 500. Default 100.0 blocks rooms with >50000 state events.
+#ROOM_COMPLEXITY_LIMIT=100.0
+
+## Retention
+
+ALLOWED_LIFETIME_MAX=4w
+
+REDACTION_RETENTION_PERIOD=7d
+RETENTION_MAX_LIFETIME=4w
+
+#MEDIA_RETENTION_LOCAL_LIFETIME=30d
+#MEDIA_RETENTION_REMOTE_LIFETIME=14d
+
+## Old Signing Key
+#OLD_SIGNING_KEY_ID=a_OLDKEYID
+#OLD_SIGNING_KEY=base64string
+#OLD_SIGNING_KEY_EXPIRES=123456789123
+
+## Ratelimit
+
+#LOGIN_LIMIT_IP_PER_SECOND=5
+#LOGIN_LIMIT_IP_BURST=15
+#LOGIN_LIMIT_ACCOUNT_PER_SECOND=1
+#LOGIN_LIMIT_ACCOUNT_BURST=10
+
+## TURN
+
 #COMPOSE_FILE="$COMPOSE_FILE:compose.turn.yml"
 #TURN_ENABLED=1
 #TURN_URIS="[\"turns:coturn.foo.zone?transport=udp\", \"turns:coturn.foo.zone?transport=tcp\"]"
 #TURN_ALLOW_GUESTS=true
-#KEYCLOAK2_ALLOW_EXISTING_USERS=false
 #SECRET_TURN_SHARED_SECRET_VERSION=v1
 
+## SMTP
+
 #COMPOSE_FILE="$COMPOSE_FILE:compose.smtp.yml"
 #SMTP_ENABLED=1
 #SMTP_APP_NAME=
@@ -76,28 +195,68 @@ ENCRYPTED_BY_DEFAULT=all
 #SMTP_USER=
 #SECRET_SMTP_PASSWORD_VERSION=v1
 
+## USER-DIRECTORY
+
+#USER_DIRECTORY_ENABLED=true
+#USER_DIRECTORY_SEARCH_ALL_USERS=true
+#USER_DIRECTORY_PREFER_LOCAL_USERS=true
+#USER_DIRECTORY_SHOW_LOCKED_USERS=false
+
+## App services
+
 #APP_SERVICES_ENABLED=1
 #APP_SERVICE_CONFIGS="[\"...\"]"
 
+## Telegram bridge
+
 #COMPOSE_FILE="$COMPOSE_FILE:compose.telegram.yml"
 #APP_SERVICE_BOT_USERNAME=telegrambot
 #APP_SERVICE_DISPLAY_NAME="Telegram bridge bot"
 #APP_SERVICE_ID=
-#HOMESERVER_DOMAIN=
-#HOMESERVER_URL=
+#HOMESERVER_DOMAIN=$DOMAIN
+#HOMESERVER_URL=https://$DOMAIN
 #VERIFY_SSL=false
 #ENABLE_ENCRYPTION=true
 #TELEGRAM_APP_ID=
-#TELEGRAM_BRIDGE_ADMIN_1=
-#TELEGRAM_BRIDGE_ADMIN_2=
+#TELEGRAM_BRIDGE_PERMISSIONS="{ \"*\": \"relaybot\", \"@foo:matrix.example.com\": \"admin\" }"
+#TELEGRAM_SYNC_CHANNEL_MEMBERS=true
 #SECRET_TELEGRAM_DB_PASSWORD_VERSION=v1
 #SECRET_TELEGRAM_API_HASH_VERSION=v1
 #SECRET_TELEGRAM_BOT_TOKEN_VERSION=v1
 #SECRET_TELEGRAM_AS_TOKEN_VERSION=v1
 #SECRET_TELEGRAM_HS_TOKEN_VERSION=v1
 
-COMPOSE_FILE="$COMPOSE_FILE:compose.discord.yml"
+## Discord bridge
+
+#COMPOSE_FILE="$COMPOSE_FILE:compose.discord.yml"
 #DISCORD_CLIENT_ID=
 #DISCORD_BRIDGE_ADMIN=
 #SECRET_DISCORD_BOT_TOKEN_VERSION=v1
 #SECRET_DISCORD_DB_PASSWORD_VERSION=v1
+
+## Signal bridge
+
+#COMPOSE_FILE="$COMPOSE_FILE:compose.signal.yml"
+#SIGNAL_ENABLE_ENCRYPTION=true
+#SIGNAL_DEFAULT_ENCRYPTION=true
+#SIGNAL_BRIDGE_PERMISSIONS="{ \"*\": \"relay\" }"
+#SECRET_SIGNAL_AS_TOKEN_VERSION=v1
+#SECRET_SIGNAL_DB_PASSWORD_VERSION=v1
+#SECRET_SIGNAL_HS_TOKEN_VERSION=v1
+#SECRET_SIGNAL_PICKLE_KEY_VERSION=v1
+
+## Web Client (Redirect)
+#WEB_CLIENT_LOCATION=https://element-web.example.com
+
+
+## State compression (reduces database bloat from federation)
+## Runs synapse_auto_compressor daily, built from source on first start
+#COMPOSE_FILE="$COMPOSE_FILE:compose.compress-state.yml"
+# See https://github.com/matrix-org/rust-synapse-compress-state#running-options
+#STATE_COMPRESS_CHUNK_SIZE=500
+#STATE_COMPRESS_CHUNKS=100
+#STATE_COMPRESS_SCHEDULE=0 3 * * *
+
+## Admin interface at /admin
+#COMPOSE_FILE="$COMPOSE_FILE:compose.admin.yml"
+#ADMIN_INTERFACE_ENABLED=1

README.md

@@ -18,100 +18,214 @@
 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 YOURAPPDOMAIN config` - be sure to change `$DOMAIN` to something that resolves to your Docker swarm box
-5. `abra app YOURAPPDOMAIN deploy`
-6. Create an initial user: `abra app YOURAPPDOMAIN run app register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008`
+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
 
-> We're not sure this does it exactly and there is still a discussion running
-> upstrem about whether this is the right way to do it & whether it could be
-> more convenient. We welcome issues / change sets to close up more federation
-> functionality.
-
-- 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
+- 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.
+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. At least one needs to be working for federation to work (and matrix will fallback between them).
 
-Depending on your setup, using `SERVE_SERVER_WELLKNOWN=true` might work to start federating.
+#### Option 1: built-in well-known (`SERVER_NAME` = `DOMAIN`)
 
-### Seeing what changed in `homeserver.yaml` between versions
+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`. 
 
-Change the version range to suit your needs.
+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` (and SERVER_NAME is served by the same machine that Synapse is running on). Set:
 
 ```
-git clone https://github.com/matrix-org/synapse
-cd synapse/docs
-git log --follow -p v1.48.0..v1.51.0 sample_config.yaml
+SERVER_NAME=example.com
+DOMAIN=matrix.example.com
+SERVE_SERVER_WELLKNOWN=false
 ```
 
-### Generating a new `homeserver.yaml`
+The two paths that must be served on `SERVER_NAME` are:
 
-The default is also available to see [here](https://matrix-org.github.io/synapse/latest/usage/configuration/homeserver_sample_config.html).
+- `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`:
 
 ```
-docker run -it \
-  --entrypoint="" \
-  -e SYNAPSE_SERVER_NAME=foo.com \
-  -e SYNAPSE_REPORT_STATS=no \
-  matrixdotorg/synapse:v1.48.0 \
-  sh -c '/start.py generate; cat /data/homeserver.yaml' > homeserver.yaml.tmpl`
+COMPOSE_FILE="$COMPOSE_FILE:compose.wellknown.yml"
 ```
 
-### Generating a new `<server>.log.config`
+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 (also requires SERVER_NAME pointing to same server that matrix is running on).
+
+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)
+
+For reasons explained below, I might be confused, but I think SRV records usually don't help with co-op cloud matrix deployments.
+
+You should probably prefer Option 2 (well known), but the possibility of SRV is explained below:
+
+Federation can also be delegated with a DNS `SRV` record on `SERVER_NAME` instead of well-known:
 
 ```
-docker run -it \
-  --entrypoint="" \
-  -e SYNAPSE_SERVER_NAME=foo.com \
-  -e SYNAPSE_REPORT_STATS=no \
-  matrixdotorg/synapse:v1.48.0 \
-  sh -c '/start.py generate; cat /data/foo.com.log.config' > log.config
+_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).
+
+
+#### 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).
+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.
 
-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
 
-> WIP
-
-Setting it up is a bit of a chicken/egg & chasing cats moment.
-
-You need to get your bot setup on the telegram side first and have these values:
+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
 
-Here is a rough guide:
+abra app deploy $DOMAIN
+abra app cmd -l $DOMAIN set_bridge_tokens telegram
+```
+
+Alternatively a manual guide for the necessary steps:
 
 ```
-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>
+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 matrix.fva.wtf telegram_bridge cat /data/registration.yaml
-abra app undeploy <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_as_token
+abra app secret insert $DOMAIN telegram_as_token v1 <secret>
 
-abra app secret rm <domain> telegram_as_token
-abra app secret insert <domain> telegram_hs_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>
+abra app deploy $DOMAIN
 ```
 
 Some helpful documentation:
@@ -121,7 +235,7 @@ Some helpful documentation:
 
 ### Discord bridging
 
-> WIP
+> WIP docs
 
 Just as messy as the Telegram bridging above! Rough guide:
 
@@ -137,3 +251,32 @@ 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

abra.sh

@@ -1,5 +1,354 @@
-export ENTRYPOINT_CONF_VERSION=v1
-export HOMESERVER_YAML_VERSION=v11
+export DISCORD_BRIDGE_YAML_VERSION=v2
+export ENTRYPOINT_CONF_VERSION=v3
+export HOMESERVER_YAML_VERSION=v37
 export LOG_CONFIG_VERSION=v2
-export TELEGRAM_BRIDGE_YAML_VERSION=v2
-export DISCORD_BRIDGE_YAML_VERSION=v1
+export SHARED_SECRET_AUTH_VERSION=v2
+export SIGNAL_BRIDGE_YAML_VERSION=v6
+export TELEGRAM_BRIDGE_YAML_VERSION=v6
+export NGINX_CONFIG_VERSION=v13
+export WK_SERVER_VERSION=v1
+export WK_CLIENT_VERSION=v2
+export MAS_CONFIG_VERSION=v2
+export PG_BACKUP_VERSION=v2
+export ADMIN_CONFIG_VERSION=v1
+export COMPRESS_STATE_ENTRYPOINT_VERSION=v5
+
+###############################################################################
+# Database maintenance — shrink a bloated Synapse database
+#
+# See https://levans.fr/shrink-synapse-database.html
+#
+# Recommended steps to reclaim disk space:
+#   1. abra app cmd <domain> compress-state run_compressor 500 10000
+#      (compress redundant state — safe while Synapse is running)
+#   2. abra app cmd <domain> db reindex
+#      (rebuild indexes — stop Synapse first)
+#   3. abra app cmd <domain> db vacuum_full
+#      (rewrite tables and reclaim disk — stop Synapse first)
+#
+# Diagnostic commands (safe to run anytime):
+#   abra app cmd <domain> db db_size
+#   abra app cmd <domain> db state_bloat
+#   abra app cmd <domain> db empty_rooms
+#
+# Purge commands (require an admin token):
+#   abra app cmd <domain> app register_admin <user> <pass>
+#   abra app cmd <domain> app get_token <user> <pass>
+#   abra app cmd <domain> app purge_remote_media <days> <token>
+#   abra app cmd <domain> app purge_empty_rooms <token>
+#   abra app cmd <domain> app purge_room <room_id> <token>
+#   abra app cmd <domain> app purge_history <room_id> <days> <token>
+###############################################################################
+
+# --- Diagnostics (db) ---
+
+db_size() {
+    echo "=== Database size ==="
+    psql -U synapse -d synapse -c "SELECT pg_size_pretty(pg_database_size('synapse')) AS db_size;"
+    echo ""
+    echo "=== Top 10 largest tables ==="
+    psql -U synapse -d synapse -c "
+        SELECT nspname || '.' || relname AS table,
+               pg_size_pretty(pg_total_relation_size(C.oid)) AS total_size
+        FROM pg_class C
+        LEFT JOIN pg_namespace N ON (N.oid = C.relnamespace)
+        WHERE nspname NOT IN ('pg_catalog', 'information_schema')
+        ORDER BY pg_total_relation_size(C.oid) DESC
+        LIMIT 10;"
+}
+
+state_bloat() {
+    echo "=== Rooms with most state bloat ==="
+    psql -U synapse -d synapse -c "
+        SELECT room_id, count(*) AS state_entries
+        FROM state_groups_state
+        GROUP BY room_id
+        ORDER BY state_entries DESC
+        LIMIT 20;"
+}
+
+empty_rooms() {
+    echo "=== Rooms with no local members ==="
+    psql -U synapse -d synapse -c "
+        SELECT room_id, room_version
+        FROM rooms
+        WHERE room_id NOT IN (
+            SELECT room_id FROM local_current_membership WHERE membership = 'join'
+        );"
+}
+
+# --- Compression (compress-state) ---
+
+run_compressor() {
+    CHUNK_SIZE="${1:-${STATE_COMPRESS_CHUNK_SIZE:-500}}"
+    CHUNKS="${2:-${STATE_COMPRESS_CHUNKS:-100}}"
+    DB_PASS=$(cat /run/secrets/db_password)
+    echo "Running synapse_auto_compressor (chunk_size=$CHUNK_SIZE, chunks=$CHUNKS)..."
+    /build/synapse_auto_compressor \
+        -p "postgresql://synapse:${DB_PASS}@db:5432/synapse" \
+        -c "$CHUNK_SIZE" -n "$CHUNKS"
+}
+
+# --- Maintenance (db) — stop Synapse before running these ---
+
+reindex() {
+    echo "WARNING: REINDEX locks tables. Synapse should be stopped before running this."
+    echo "Running REINDEX on synapse database..."
+    psql -U synapse -d synapse -c "REINDEX (VERBOSE) DATABASE synapse;"
+    echo "REINDEX complete."
+    psql -U synapse -d synapse -c "SELECT pg_size_pretty(pg_database_size('synapse')) AS db_size;"
+}
+
+vacuum_full() {
+    echo "WARNING: VACUUM FULL locks tables and requires temporary disk space."
+    echo "Synapse should be stopped before running this."
+    echo "Running VACUUM FULL on synapse database..."
+    psql -U synapse -d synapse -c "VACUUM FULL;"
+    echo "VACUUM FULL complete."
+    psql -U synapse -d synapse -c "SELECT pg_size_pretty(pg_database_size('synapse')) AS db_size;"
+}
+
+# --- Purge commands (app) — require an admin access token ---
+
+register_admin() {
+    USER="${1}"
+    PASS="${2}"
+    if [ -z "$USER" ] || [ -z "$PASS" ]; then
+        echo "Usage: register_admin <username> <password>"
+        return 1
+    fi
+    register_new_matrix_user -u "$USER" -p "$PASS" -a -c /data/homeserver.yaml http://localhost:8008
+}
+
+get_token() {
+    USER="${1}"
+    PASS="${2}"
+    if [ -z "$USER" ] || [ -z "$PASS" ]; then
+        echo "Usage: get_token <username> <password>"
+        echo "Returns an admin access token for use with purge commands."
+        return 1
+    fi
+    curl -s -X POST "http://localhost:8008/_matrix/client/r0/login" \
+        -H "Content-Type: application/json" \
+        -d "{\"type\":\"m.login.password\",\"user\":\"$USER\",\"password\":\"$PASS\"}" \
+        | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('access_token', d.get('error', 'unknown error')))"
+}
+
+purge_remote_media() {
+    DAYS="${1:-30}"
+    TOKEN="${2}"
+    if [ -z "$TOKEN" ]; then
+        echo "Usage: purge_remote_media <days> <admin_token>"
+        return 1
+    fi
+    BEFORE_TS=$(( $(date +%s) * 1000 - DAYS * 86400000 ))
+    echo "Purging remote media older than $DAYS days..."
+    curl -s -X POST "http://localhost:8008/_synapse/admin/v1/purge_media_cache?before_ts=$BEFORE_TS" \
+        -H "Authorization: Bearer $TOKEN"
+    echo ""
+}
+
+purge_room() {
+    ROOM_ID="${1}"
+    TOKEN="${2}"
+    if [ -z "$ROOM_ID" ] || [ -z "$TOKEN" ]; then
+        echo "Usage: purge_room <room_id> <admin_token>"
+        return 1
+    fi
+    echo "Purging room $ROOM_ID..."
+    curl -s -X DELETE "http://localhost:8008/_synapse/admin/v1/rooms/$ROOM_ID" \
+        -H "Authorization: Bearer $TOKEN" \
+        -H "Content-Type: application/json" \
+        -d '{"purge": true}'
+    echo ""
+}
+
+purge_history() {
+    ROOM_ID="${1}"
+    DAYS="${2:-90}"
+    TOKEN="${3}"
+    if [ -z "$ROOM_ID" ] || [ -z "$TOKEN" ]; then
+        echo "Usage: purge_history <room_id> <days> <admin_token>"
+        return 1
+    fi
+    BEFORE_TS=$(( $(date +%s) * 1000 - DAYS * 86400000 ))
+    echo "Purging history older than $DAYS days from $ROOM_ID..."
+    curl -s -X POST "http://localhost:8008/_synapse/admin/v1/purge_history/$ROOM_ID" \
+        -H "Authorization: Bearer $TOKEN" \
+        -H "Content-Type: application/json" \
+        -d "{\"purge_up_to_ts\": $BEFORE_TS}"
+    echo ""
+}
+
+purge_empty_rooms() {
+    TOKEN="${1}"
+    if [ -z "$TOKEN" ]; then
+        echo "Usage: purge_empty_rooms <admin_token>"
+        return 1
+    fi
+    echo "Fetching rooms with no local members..."
+    ROOMS=$(curl -s "http://localhost:8008/_synapse/admin/v1/rooms?limit=1000" \
+        -H "Authorization: Bearer $TOKEN" \
+        | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for r in data.get('rooms', []):
+    if r.get('joined_local_members', 0) == 0:
+        print(r['room_id'])
+")
+    COUNT=$(echo "$ROOMS" | grep -c '.' || true)
+    echo "Found $COUNT empty rooms."
+    if [ "$COUNT" -eq 0 ]; then
+        echo "Nothing to purge."
+        return 0
+    fi
+    echo "$ROOMS"
+    echo ""
+    echo "Purging..."
+    for ROOM_ID in $ROOMS; do
+        echo "  Purging $ROOM_ID"
+        curl -s -X DELETE "http://localhost:8008/_synapse/admin/v1/rooms/$ROOM_ID" \
+            -H "Authorization: Bearer $TOKEN" \
+            -H "Content-Type: application/json" \
+            -d '{"purge": true}' > /dev/null
+    done
+    echo "Done."
+}
+
+###############################################################################
+# Other commands
+###############################################################################
+
+ensure_mas_database () {
+    if ! psql -U synapse -d postgres -v ON_ERROR_STOP=1 -Atqc "SELECT 1 FROM pg_database WHERE datname = 'mas'" | grep -qx 1
+    then
+        psql -U synapse -d postgres -v ON_ERROR_STOP=1 -c "CREATE DATABASE mas OWNER synapse"
+    fi
+}
+
+# Generate a PEM RSA private key and insert it as the MAS signing secret.
+# `abra app secret generate` can only produce random hex/charset strings, so this
+# secret is marked `generate=false` in .env.sample and handled here instead.
+generate_mas_signing_rsa() {
+    if ! command -v openssl &> /dev/null; then
+        echo "openssl is required on your local machine to generate the MAS signing key."
+        echo "It could not be found in your PATH, please install openssl to proceed."
+        exit 1
+    fi
+
+    KEY=$(openssl genrsa 2048 2>/dev/null)
+    if [ -z "$KEY" ]; then
+        echo "Failed to generate RSA private key with openssl."
+        exit 1
+    fi
+
+    if printf '%s\n' "$KEY" | abra app secret insert -C "$APP_NAME" mas_signing_rsa v1; then
+        echo "MAS signing RSA key generated and inserted as v1."
+    else
+        echo "Failed to insert MAS signing RSA key."
+        exit 1
+    fi
+}
+
+# Local helper: fetch homeserver.yaml from app, push to mas, then syn2mas check + dry-run.
+prepare_mas_migration () {
+    local syn_cfg
+
+    syn_cfg=/tmp/homeserver.yaml
+
+    cleanup_prepare_mas_migration() {
+        rm -f "homeserver.yaml"
+    }
+    trap cleanup_prepare_mas_migration EXIT
+
+    echo "Fetching /data/homeserver.yaml from app to homeserver.yaml (abra app run … cat)..."
+    if ! abra app run -t "$DOMAIN" app cat /data/homeserver.yaml > "homeserver.yaml"
+    then
+        return 1
+    fi
+    if [ ! -s "homeserver.yaml" ]; then
+        echo "Error: fetched homeserver.yaml is empty." >&2
+        return 1
+    fi
+
+    echo "Copying into mas:/tmp"
+    abra app cp "$DOMAIN" "homeserver.yaml" "mas:/tmp" || return 1
+
+    echo "Running mas-cli syn2mas check..."
+    abra app run -t "$DOMAIN" mas -- mas-cli syn2mas check \
+        --config /etc/mas/config.yaml \
+        --synapse-config "$syn_cfg" || return 1
+
+    echo "Running mas-cli syn2mas migrate --dry-run..."
+    abra app run -t "$DOMAIN" mas -- mas-cli syn2mas migrate \
+        --config /etc/mas/config.yaml \
+        --synapse-config "$syn_cfg" \
+        --dry-run || return 1
+
+    trap - EXIT
+    cleanup_prepare_mas_migration
+
+    echo ""
+    echo "=== Next migration step: stop Synapse (downtime) ==="
+    echo "Run on a host whose Docker CLI targets this Swarm (same machine you use for 'abra app deploy')."
+    if [ -n "${STACK_NAME:-}" ]; then
+        echo "  docker service scale ${STACK_NAME}_app=0"
+    else
+        echo "STACK_NAME is not set here; resolve the Synapse service name with 'docker service ls' on that host, then:"
+        echo "docker service scale <STACK_NAME>_app=0"
+    fi
+}
+
+# Run syn2mas migrate for real (writes MAS data). Run from your operator machine as MAS image is distroless.
+# Requires /tmp/homeserver.yaml in the mas container (e.g. from prepare_mas_migration) and
+# Synapse scaled down before migrate.
+run_mas_migration () {
+    local syn_cfg=/tmp/homeserver.yaml
+
+    echo "Running mas-cli syn2mas migrate in mas via abra app run..."
+    abra app run -t "$DOMAIN" mas -- mas-cli syn2mas migrate \
+        --config /etc/mas/config.yaml \
+        --synapse-config "$syn_cfg"
+}
+
+set_admin () {
+    admin=akadmin
+    if [ -n "$1" ]
+    then
+        admin=$1
+    fi
+    psql -U synapse -c "UPDATE users SET admin = 1 WHERE name = '@$admin:$DOMAIN'";
+}
+
+set_bridge_tokens() {
+    if [ -z "$1" ]; then
+        echo "Error: Missing parameter. Usage: set_bridge_tokens <BRIDGETYPE>"
+        return 1
+    fi
+
+    BRIDGETYPE=$1
+    echo "retrieve tokens from registration.yaml..."
+    output=$(abra app run $DOMAIN app cat /${BRIDGETYPE}-data/registration.yaml)
+    if [ $? -ne 0 ]; then
+        echo "Error: Failed to retrieve registration.yaml for ${BRIDGETYPE} bridge:"
+        echo "$output"
+        return 1
+    fi
+
+    hs_token=$(echo "$output" | sed -n 's/^hs_token:[[:space:]]*\(.*\)$/\1/p')
+    as_token=$(echo "$output" | sed -n 's/^as_token:[[:space:]]*\(.*\)$/\1/p')
+
+    echo "HS Token: $hs_token"
+    echo "AS Token: $as_token"
+    echo "UNDEPLOY $DOMAIN?"
+    abra app undeploy $DOMAIN
+
+    echo "Replacing tokens:"
+    abra app secret rm $DOMAIN ${BRIDGETYPE}_as_token
+    abra app secret insert $DOMAIN ${BRIDGETYPE}_as_token v1 $as_token
+    abra app secret rm $DOMAIN ${BRIDGETYPE}_hs_token
+    abra app secret insert $DOMAIN ${BRIDGETYPE}_hs_token v1 $hs_token
+
+    echo "Redeploying $DOMAIN..."
+    abra app deploy -n $DOMAIN
+}

admin.conf.tmpl

@@ -0,0 +1,3 @@
+{
+  "restrictBaseUrl": "https://{{ env "DOMAIN" }}"
+}

alaconnect.yml

@@ -0,0 +1,15 @@
+authentik:
+    env:
+        KEYCLOAK_ID: authentik
+        KEYCLOAK_NAME: sso
+        KEYCLOAK_URL: https://authentik.example.com/application/o/matrix/
+        KEYCLOAK_CLIENT_DOMAIN: https://element-web.example.com
+        KEYCLOAK_ALLOW_EXISTING_USERS: "true"
+        KEYCLOAK_CLIENT_ID: matrix
+    uncomment:
+        - compose.keycloak.yml
+        - KEYCLOAK_ENABLED
+        - KEYCLOAK_CLIENT_ID
+        - SECRET_KEYCLOAK_CLIENT_SECRET_VERSION
+    shared_secrets:
+        matrix_secret: keycloak_client_secret

compose.admin.yml

@@ -0,0 +1,46 @@
+---
+version: "3.8"
+
+services:
+  admin:
+    image: awesometechnologies/synapse-admin:0.11.4
+    networks:
+      - proxy
+    deploy:
+      labels:
+        - "traefik.enable=true"
+        - "traefik.swarm.network=proxy"
+        - "traefik.http.services.${STACK_NAME}_admin.loadbalancer.server.port=80"
+        - "traefik.http.routers.${STACK_NAME}_admin.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS})&&PathPrefix(`/admin`)"
+        - "traefik.http.routers.${STACK_NAME}_admin.entrypoints=web-secure"
+        - "traefik.http.routers.${STACK_NAME}_admin.tls.certresolver=${LETS_ENCRYPT_ENV}"
+        - "traefik.http.routers.${STACK_NAME}_admin.middlewares=admin,admin_path"
+        - "traefik.http.middlewares.admin.redirectregex.regex=^(.*)/admin/?"
+        - "traefik.http.middlewares.admin.redirectregex.replacement=$${1}/admin/"
+        - "traefik.http.middlewares.admin_path.stripprefix.prefixes=/admin"
+    environment:
+      - DOMAIN
+    configs:
+      - source: admin_config
+        target: /app/config.json
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost"]
+      interval: 30s
+      timeout: 10s
+      retries: 10
+      start_period: 1m
+  web:
+    environment:
+      - ADMIN_INTERFACE_ENABLED
+
+
+networks:
+  proxy:
+    external: true
+
+configs:
+  admin_config:
+    name: ${STACK_NAME}_admin_config_${ADMIN_CONFIG_VERSION}
+    file: admin.conf.tmpl
+    template_driver: golang
+

compose.compress-state.yml

@@ -0,0 +1,31 @@
+version: "3.8"
+
+services:
+  compress-state:
+    image: rust:1-alpine
+    entrypoint: /compress_state_entrypoint.sh
+    environment:
+      - STATE_COMPRESS_CHUNK_SIZE=${STATE_COMPRESS_CHUNK_SIZE:-500}
+      - STATE_COMPRESS_CHUNKS=${STATE_COMPRESS_CHUNKS:-100}
+      - STATE_COMPRESS_SCHEDULE=${STATE_COMPRESS_SCHEDULE:-0 3 * * *}
+    secrets:
+      - db_password
+    configs:
+      - source: compress_entrypoint
+        target: /compress_state_entrypoint.sh
+        mode: 0555
+    volumes:
+      - compress_state_build:/build
+    networks:
+      - internal
+    deploy:
+      restart_policy:
+        condition: on-failure
+
+volumes:
+  compress_state_build:
+
+configs:
+  compress_entrypoint:
+    name: ${STACK_NAME}_compress_ep_${COMPRESS_STATE_ENTRYPOINT_VERSION}
+    file: compress_state_entrypoint.sh

compose.discord.yml

@@ -43,7 +43,7 @@ services:
     networks:
       - internal
     healthcheck:
-      test: ["CMD", "pg_isready", "-U", "synapse"]
+      test: ["CMD", "pg_isready", "-U", "$POSTGRES_USER" ]
     volumes:
       - discord-postgres:/var/lib/postgresql/data
 

compose.keycloak.yml

@@ -7,8 +7,8 @@ services:
       - db_password
       - form_secret
       - keycloak_client_secret
-      - macaroon_secret_key
-      - registration_shared_secret
+      - macaroon
+      - registration
     environment:
       - KEYCLOAK_CLIENT_DOMAIN
       - KEYCLOAK_CLIENT_ID

compose.keycloak3.yml

@@ -0,0 +1,19 @@
+---
+version: "3.8"
+
+services:
+  app:
+    secrets:
+      - keycloak3_client_secret
+    environment:
+      - KEYCLOAK3_ALLOW_EXISTING_USERS
+      - KEYCLOAK3_CLIENT_ID
+      - KEYCLOAK3_ENABLED
+      - KEYCLOAK3_ID
+      - KEYCLOAK3_NAME
+      - KEYCLOAK3_URL
+
+secrets:
+  keycloak3_client_secret:
+    external: true
+    name: ${STACK_NAME}_keycloak3_client_secret_${SECRET_KEYCLOAK3_CLIENT_SECRET_VERSION}

compose.mas-upstream.yml

@@ -0,0 +1,21 @@
+---
+version: "3.8"
+
+# Upstream OIDC provider for MAS (e.g. Authentik, Keycloak).
+# Requires compose.mas.yml. Adds the client secret and env vars needed by mas.config.yaml.tmpl.
+
+services:
+  mas:
+    environment:
+      - MAS_UPSTREAM_PROVIDER_ID
+      - MAS_UPSTREAM_ISSUER
+      - MAS_UPSTREAM_CLIENT_ID
+      - MAS_UPSTREAM_HUMAN_NAME
+      - MAS_UPSTREAM_SYNAPSE_IDP_ID
+    secrets:
+      - mas_upstream_client
+
+secrets:
+  mas_upstream_client:
+    external: true
+    name: ${STACK_NAME}_mas_upstream_client_${SECRET_MAS_UPSTREAM_CLIENT_VERSION}

compose.mas.yml

@@ -0,0 +1,64 @@
+---
+version: "3.8"
+
+# Matrix Authentication Service (MAS) — optional overlay for Element X / OIDC-native auth.
+
+services:
+  mas:
+    image: ghcr.io/element-hq/matrix-authentication-service:1.14.0
+    command: ["server", "--config=/etc/mas/config.yaml"]
+    environment:
+      - DOMAIN
+      - SERVER_NAME
+      - STACK_NAME
+    networks:
+      - internal
+    configs:
+      - source: mas_config
+        target: /etc/mas/config.yaml
+    secrets:
+      - db_password
+      - mas_encryption
+      - mas_synapse_shared
+      - mas_signing_rsa
+    # Official image is distroless (no curl/wget); upstream suggests `mas-cli config check` for probes.
+    # See https://github.com/element-hq/matrix-authentication-service/issues/3741 — validates config, not HTTP.
+    # GET /health is still served (resource `health` in mas.config.yaml.tmpl) for probes from other images.
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "/usr/local/bin/mas-cli",
+          "--config",
+          "/etc/mas/config.yaml",
+          "config",
+          "check",
+        ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    deploy:
+      restart_policy:
+        condition: on-failure
+
+  app:
+    secrets:
+      - mas_synapse_shared
+
+configs:
+  mas_config:
+    name: ${STACK_NAME}_mas_config_${MAS_CONFIG_VERSION}
+    file: mas.config.yaml.tmpl
+    template_driver: golang
+
+secrets:
+  mas_encryption:
+    external: true
+    name: ${STACK_NAME}_mas_encryption_${SECRET_MAS_ENCRYPTION_VERSION}
+  mas_synapse_shared:
+    external: true
+    name: ${STACK_NAME}_mas_synapse_shared_${SECRET_MAS_SYNAPSE_SHARED_VERSION}
+  mas_signing_rsa:
+    external: true
+    name: ${STACK_NAME}_mas_signing_rsa_${SECRET_MAS_SIGNING_RSA_VERSION}

compose.shared_secret_auth.yml

@@ -0,0 +1,22 @@
+---
+version: "3.8"
+
+services:
+  app:
+    environment:
+      - SHARED_SECRET_AUTH_ENABLED
+    secrets:
+      - shared_secret_auth
+    configs:
+      - source: shared_secret_auth
+        target: /usr/local/lib/python3.13/site-packages/shared_secret_authenticator.py
+
+configs:
+  shared_secret_auth:
+    name: ${STACK_NAME}_shared_secret_auth_${SHARED_SECRET_AUTH_VERSION}
+    file: shared_secret_authenticator.py
+
+secrets:
+  shared_secret_auth:
+    external: true
+    name: ${STACK_NAME}_shared_secret_auth_${SECRET_SHARED_SECRET_AUTH_VERSION}

compose.signal.yml

@@ -0,0 +1,86 @@
+---
+version: "3.8"
+
+services:
+  app:
+    environment:
+      - APP_SERVICES_ENABLED
+      - APP_SERVICE_CONFIGS
+    volumes:
+      - signal-data:/signal-data
+
+  signalbridge:
+    image: dock.mau.dev/mautrix/signal:v0.8.7
+    depends_on:
+      - signaldb
+    configs:
+      - source: signal_bridge_yaml
+        target: /data/config.yaml
+    environment:
+      - HOMESERVER_DOMAIN
+      - HOMESERVER_URL
+      - SIGNAL_BRIDGE_PERMISSIONS
+      - SIGNAL_ENABLE_ENCRYPTION
+      - SIGNAL_DEFAULT_ENCRYPTION=${SIGNAL_DEFAULT_ENCRYPTION:-false}
+      - VERIFY_SSL
+    secrets:
+      - signal_as_token
+      - signal_db_password
+      - signal_hs_token
+      - shared_secret_auth
+      - signal_pickle_key
+    volumes:
+      - signal-data:/data
+    networks:
+      - internal
+
+  signaldb:
+    image: postgres:13-alpine
+    secrets:
+      - signal_db_password
+    environment:
+      - LC_COLLATE=C
+      - LC_CTYPE=C
+      - POSTGRES_DB=signalbridge
+      - POSTGRES_INITDB_ARGS="-E \"UTF8\""
+      - POSTGRES_PASSWORD_FILE=/run/secrets/signal_db_password
+      - POSTGRES_USER=signalbridge
+    networks:
+      - internal
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "$POSTGRES_USER" ]
+    volumes:
+      - signal-postgres:/var/lib/postgresql/data
+    deploy:
+      labels:
+        backupbot.backup.pre-hook: "/pg_backup.sh backup"
+        backupbot.backup.volumes.signal-postgres.path: "backup.sql"
+        backupbot.restore.post-hook: '/pg_backup.sh restore'
+    configs:
+        - source: pg_backup
+          target: /pg_backup.sh
+          mode: 0555
+
+configs:
+  signal_bridge_yaml:
+    name: ${STACK_NAME}_signal_bridge_yaml_${SIGNAL_BRIDGE_YAML_VERSION}
+    file: signal_bridge.yaml.tmpl
+    template_driver: golang
+
+volumes:
+  signal-data:
+  signal-postgres:
+
+secrets:
+  signal_db_password:
+    external: true
+    name: ${STACK_NAME}_signal_db_password_${SECRET_SIGNAL_DB_PASSWORD_VERSION}
+  signal_as_token:
+    external: true
+    name: ${STACK_NAME}_signal_as_token_${SECRET_SIGNAL_AS_TOKEN_VERSION}
+  signal_hs_token:
+    external: true
+    name: ${STACK_NAME}_signal_hs_token_${SECRET_SIGNAL_HS_TOKEN_VERSION}
+  signal_pickle_key:
+    external: true
+    name: ${STACK_NAME}_signal_pickle_key_${SECRET_SIGNAL_PICKLE_KEY_VERSION}

compose.smtp.yml

@@ -6,8 +6,8 @@ services:
     secrets:
       - db_password
       - form_secret
-      - macaroon_secret_key
-      - registration_shared_secret
+      - macaroon
+      - registration
       - smtp_password
     environment:
       - SMTP_APP_NAME

compose.telegram.yml

@@ -10,7 +10,7 @@ services:
       - telegram-data:/telegram-data
 
   telegrambridge:
-    image: dock.mau.dev/mautrix/telegram:1f5b91cbec7866663d8dd8f4c9a62115e2905552-amd64
+    image: dock.mau.dev/mautrix/telegram:v0.15.3
     depends_on:
       - telegramdb
     configs:
@@ -24,8 +24,8 @@ services:
       - HOMESERVER_DOMAIN
       - HOMESERVER_URL
       - TELEGRAM_APP_ID
-      - TELEGRAM_BRIDGE_ADMIN_1
-      - TELEGRAM_BRIDGE_ADMIN_2
+      - TELEGRAM_BRIDGE_PERMISSIONS
+      - TELEGRAM_SYNC_CHANNEL_MEMBERS
       - VERIFY_SSL
     secrets:
       - telegram_api_hash
@@ -33,6 +33,7 @@ services:
       - telegram_bot_token
       - telegram_db_password
       - telegram_hs_token
+      - shared_secret_auth
     volumes:
       - telegram-data:/data
     networks:
@@ -52,9 +53,18 @@ services:
     networks:
       - internal
     healthcheck:
-      test: ["CMD", "pg_isready", "-U", "synapse"]
+      test: ["CMD", "pg_isready", "-U", "$POSTGRES_USER" ]
     volumes:
       - telegram-postgres:/var/lib/postgresql/data
+    deploy:
+      labels:
+        backupbot.backup.pre-hook: "/pg_backup.sh backup"
+        backupbot.backup.volumes.telegram-postgres.path: "backup.sql"
+        backupbot.restore.post-hook: '/pg_backup.sh restore'
+    configs:
+        - source: pg_backup
+          target: /pg_backup.sh
+          mode: 0555
 
 configs:
   telegram_bridge_yaml:

compose.turn.yml

@@ -6,8 +6,8 @@ services:
     secrets:
       - db_password
       - form_secret
-      - macaroon_secret_key
-      - registration_shared_secret
+      - macaroon
+      - registration
       - turn_shared_secret
     environment:
       - TURN_ALLOW_GUESTS

compose.wellknown.yml

@@ -0,0 +1,24 @@
+---
+version: "3.8"
+
+# Serve /.well-known/matrix/{server,client} on SERVER_NAME via Traefik, routed to
+# the matrix nginx (`web`) — so server/client delegation works without hand-placing
+# files on whatever else hosts SERVER_NAME.
+#
+# Enable when SERVER_NAME != DOMAIN (users are @alice:example.com, Synapse runs at
+# matrix.example.com). The PathPrefix rule is more specific than a bare Host()
+# router, and the explicit high priority guarantees it wins over any apex website
+# that also serves Host(SERVER_NAME) — so the two coexist, the apex site keeps
+# serving everything except /.well-known/matrix.
+#
+# Requires SERVER_NAME to resolve to this Traefik so ACME can issue its cert.
+services:
+  web:
+    deploy:
+      labels:
+        - "traefik.http.routers.${STACK_NAME}-wellknown.rule=Host(`${SERVER_NAME}`) && PathPrefix(`/.well-known/matrix`)"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.entrypoints=web-secure"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.tls=true"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.tls.certresolver=${LETS_ENCRYPT_ENV}"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.service=${STACK_NAME}"
+        - "traefik.http.routers.${STACK_NAME}-wellknown.priority=1000"

compose.yml

@@ -2,19 +2,59 @@
 version: "3.8"
 
 services:
+  web:
+    image: nginx:1.29.6
+    networks:
+      - proxy
+      - internal
+    environment:
+      - DOMAIN
+      - STACK_NAME
+      - MAS_ENABLED
+      - NGINX_ACCESS_LOG_LOCATION
+      - NGINX_ERROR_LOG_LOCATION
+      - MAX_UPLOAD_SIZE
+    configs:
+      - source: nginx_config
+        target: /etc/nginx/nginx.conf
+      - source: wk_server
+        target: /var/www/.well-known/matrix/server
+      - source: wk_client
+        target: /var/www/.well-known/matrix/client
+    deploy:
+      restart_policy:
+        condition: any
+      labels:
+        - "traefik.enable=true"
+        - "traefik.http.services.${STACK_NAME}.loadbalancer.server.port=80"
+        - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`)"
+        - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
+        - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
+        - "traefik.http.routers.${STACK_NAME}-federation.rule=Host(`${SERVER_NAME}`)"
+        - "traefik.http.routers.${STACK_NAME}-federation.entrypoints=matrix-federation"
+        - "traefik.http.routers.${STACK_NAME}-federation.tls=true"
+        - "traefik.http.routers.${STACK_NAME}-federation.tls.certresolver=${LETS_ENCRYPT_ENV}"
+        - "traefik.http.routers.${STACK_NAME}-federation.service=${STACK_NAME}"
+    healthcheck:
+      test: curl -f http://${STACK_NAME}_app:8008/health || exit 1
+      interval: 30s
+      timeout: 15s
+      retries: 90
+      start_period: 2m
+
   app:
-    image: "matrixdotorg/synapse:v1.62.0"
+    image: "matrixdotorg/synapse:v1.149.1"
     volumes:
       - "data:/data"
-    depends_on:
-      - db
     secrets:
       - db_password
-      - registration_shared_secret
-      - macaroon_secret_key
+      - registration
+      - macaroon
       - form_secret
     environment:
-      - ENCRYPTED_BY_DEFAULT
+      - MAS_ENABLED
+      - ALLOWED_LIFETIME_MAX
+      - ALLOW_PUBLIC_ROOMS_FEDERATION
       - AUTO_JOIN_ROOM
       - AUTO_JOIN_ROOM_ENABLED
       - DISABLE_FEDERATION
@@ -22,10 +62,27 @@ services:
       - ENABLE_3PID_LOOKUP
       - ENABLE_ALLOWLIST
       - ENABLE_REGISTRATION
+      - REGISTRATION_REQUIRES_TOKEN
+      - ENCRYPTED_BY_DEFAULT
+      - OLD_SIGNING_KEY
+      - OLD_SIGNING_KEY_ID
+      - OLD_SIGNING_KEY_EXPIRES
+      - USER_DIRECTORY_ENABLED=${USER_DIRECTORY_ENABLED:-true}
+      - USER_DIRECTORY_SEARCH_ALL_USERS=${USER_DIRECTORY_SEARCH_ALL_USERS:-true}
+      - USER_DIRECTORY_PREFER_LOCAL_USERS=${USER_DIRECTORY_PREFER_LOCAL_USERS:-true}
+      - USER_DIRECTORY_SHOW_LOCKED_USERS=${USER_DIRECTORY_SHOW_LOCKED_USERS:-false}
       - FEDERATION_ALLOWLIST
+      - REQUIRE_AUTH_FOR_PROFILE_REQUESTS=${REQUIRE_AUTH_FOR_PROFILE_REQUESTS:-false}
+      - LIMIT_PROFILE_REQUESTS_TO_USERS_WHO_SHARE_ROOMS=${LIMIT_PROFILE_REQUESTS_TO_USERS_WHO_SHARE_ROOMS:-false}
+      - DELETE_STALE_DEVICES_AFTER
+      - SESSION_LIFETIME
+      - TRACK_PUPPETED_USER_IPS=${TRACK_PUPPETED_USER_IPS:-false}
       - LETSENCRYPT_HOST=${DOMAIN}
+      - MEDIA_RETENTION_LOCAL_LIFETIME
+      - MEDIA_RETENTION_REMOTE_LIFETIME
       - PASSWORD_LOGIN_ENABLED
       - REDACTION_RETENTION_PERIOD
+      - RETENTION_MAX_LIFETIME
       - ROOT_LOG_LEVEL
       - SERVE_SERVER_WELLKNOWN
       - SQL_LOG_LEVEL
@@ -36,9 +93,13 @@ services:
       - USER_IPS_MAX_AGE
       - VIRTUAL_HOST=${DOMAIN}
       - VIRTUAL_PORT=8008
-      - RETENTION_MAX_LIFETIME
+      - LOGIN_LIMIT_IP_PER_SECOND=${LOGIN_LIMIT_IP_PER_SECOND:-0.003}
+      - LOGIN_LIMIT_IP_BURST=${LOGIN_LIMIT_IP_BURST:-5}
+      - LOGIN_LIMIT_ACCOUNT_PER_SECOND=${LOGIN_LIMIT_ACCOUNT_PER_SECOND:-0.003}
+      - LOGIN_LIMIT_ACCOUNT_BURST=${LOGIN_LIMIT_ACCOUNT_BURST:-5}
+      - ROOM_COMPLEXITY_LIMIT=${ROOM_COMPLEXITY_LIMIT:-100.0}
+      - WEB_CLIENT_LOCATION
     networks:
-      - proxy
       - internal
     entrypoint: /docker-entrypoint.sh
     configs:
@@ -53,36 +114,46 @@ services:
       restart_policy:
         condition: on-failure
       labels:
-        - "traefik.enable=true"
-        - "traefik.http.services.${STACK_NAME}.loadbalancer.server.port=8008"
-        - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`)"
-        - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
-        - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
-        - "coop-cloud.${STACK_NAME}.version=2.1.0+v1.62.0"
+        - "coop-cloud.${STACK_NAME}.version=7.1.1+v1.149.1"
+        - "coop-cloud.${STACK_NAME}.timeout=${TIMEOUT}"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8008/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 30
+      start_period: 1m
 
   db:
-    image: postgres:13-alpine
+    image: pgautoupgrade/pgautoupgrade:17-alpine
     secrets:
       - db_password
     environment:
       - LC_COLLATE=C
       - LC_CTYPE=C
       - POSTGRES_DB=synapse
-      - POSTGRES_INITDB_ARGS="-E \"UTF8\""
+      - POSTGRES_INITDB_ARGS=-E UTF8
       - POSTGRES_PASSWORD_FILE=/run/secrets/db_password
       - POSTGRES_USER=synapse
+      - DOMAIN
     networks:
       - internal
     healthcheck:
-      test: ["CMD", "pg_isready", "-U", "synapse"]
+      interval: 30s
+      timeout: 10s
+      retries: 20
+      start_period: 1m
     volumes:
       - postgres:/var/lib/postgresql/data
     deploy:
       labels:
-          backupbot.backup: "true"
-          backupbot.backup.pre-hook: "mkdir -p /tmp/backup/ && PGPASSWORD=$$(cat $${POSTGRES_PASSWORD_FILE}) pg_dump -U $${POSTGRES_USER} $${POSTGRES_DB} > /tmp/backup/backup.sql"
-          backupbot.backup.post-hook: "rm -rf /tmp/backup"
-          backupbot.backup.path: "/tmp/backup/"
+        backupbot.backup: "${ENABLE_BACKUPS:-true}"
+        backupbot.backup.pre-hook: "/pg_backup.sh backup"
+        backupbot.backup.volumes.postgres.path: "backup.sql"
+        backupbot.restore.post-hook: "/pg_backup.sh restore"
+    configs:
+      - source: pg_backup
+        target: /pg_backup.sh
+        mode: 0555
 
 volumes:
   data:
@@ -99,24 +170,39 @@ configs:
     file: entrypoint.sh.tmpl
     template_driver: golang
   homeserver_yaml:
-    name: ${STACK_NAME}_homserver_yaml_${HOMESERVER_YAML_VERSION}
+    name: ${STACK_NAME}_homeserver_yaml_${HOMESERVER_YAML_VERSION}
     file: homeserver.yaml.tmpl
     template_driver: golang
   log_config:
     name: ${STACK_NAME}_log_config_${LOG_CONFIG_VERSION}
     file: log.config.tmpl
     template_driver: golang
+  nginx_config:
+    name: ${STACK_NAME}_nginx_config_${NGINX_CONFIG_VERSION}
+    file: nginx.conf.tmpl
+    template_driver: golang
+  wk_server:
+    name: ${STACK_NAME}_wk_server_${WK_SERVER_VERSION}
+    file: well_known_server.conf.tmpl
+    template_driver: golang
+  wk_client:
+    name: ${STACK_NAME}_wk_client_${WK_CLIENT_VERSION}
+    file: well_known_client.conf.tmpl
+    template_driver: golang
+  pg_backup:
+    name: ${STACK_NAME}_pg_backup_${PG_BACKUP_VERSION}
+    file: pg_backup.sh
 
 secrets:
   db_password:
     external: true
     name: ${STACK_NAME}_db_password_${SECRET_DB_PASSWORD_VERSION}
-  registration_shared_secret:
+  registration:
     external: true
-    name: ${STACK_NAME}_db_password_${SECRET_REGISTRATION_SHARED_SECRET_VERSION}
-  macaroon_secret_key:
+    name: ${STACK_NAME}_registration_${SECRET_REGISTRATION_VERSION}
+  macaroon:
     external: true
-    name: ${STACK_NAME}_db_password_${SECRET_MACAROON_SECRET_KEY_VERSION}
+    name: ${STACK_NAME}_macaroon_${SECRET_MACAROON_VERSION}
   form_secret:
     external: true
-    name: ${STACK_NAME}_db_password_${SECRET_FORM_SECRET_VERSION}
+    name: ${STACK_NAME}_form_secret_${SECRET_FORM_SECRET_VERSION}

compress_state_entrypoint.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+set -e
+
+BINARY="/build/synapse_auto_compressor"
+REPO_DIR="/build/rust-synapse-compress-state"
+DB_PASS=$(cat /run/secrets/db_password)
+CONN="postgresql://synapse:${DB_PASS}@db:5432/synapse"
+CHUNK_SIZE="${STATE_COMPRESS_CHUNK_SIZE:-500}"
+CHUNKS="${STATE_COMPRESS_CHUNKS:-100}"
+SCHEDULE="${STATE_COMPRESS_SCHEDULE:-0 3 * * *}"
+
+# Build from source if binary doesn't exist
+if [ ! -f "$BINARY" ]; then
+  echo "[compress-state] Binary not found, building from source..."
+  apk add --no-cache git openssl-dev openssl-libs-static perl make musl-dev jemalloc-dev
+  rm -rf "$REPO_DIR"
+  git clone https://github.com/matrix-org/rust-synapse-compress-state "$REPO_DIR"
+  cd "$REPO_DIR"
+  cargo build --release -p synapse_auto_compressor
+  cp target/release/synapse_auto_compressor "$BINARY"
+  echo "[compress-state] Build complete"
+  # Clean up source to save space
+  rm -rf "$REPO_DIR"
+else
+  echo "[compress-state] Using cached binary"
+fi
+
+# Run once at startup
+echo "[compress-state] Running initial compression at $(date)"
+"$BINARY" -p "$CONN" -c "$CHUNK_SIZE" -n "$CHUNKS" || echo "[compress-state] Error: $?"
+
+# Set up cron job
+CRON_SCRIPT="/build/run_compressor.sh"
+cat > "$CRON_SCRIPT" <<EOF
+#!/bin/sh
+echo "[compress-state] Running at \$(date)"
+$BINARY -p "$CONN" -c $CHUNK_SIZE -n $CHUNKS || echo "[compress-state] Error: \$?"
+echo "[compress-state] Done at \$(date)"
+EOF
+chmod +x "$CRON_SCRIPT"
+
+echo "$SCHEDULE $CRON_SCRIPT" | crontab -
+echo "[compress-state] Cron scheduled: $SCHEDULE"
+
+# Run crond in the foreground
+exec crond -f -l 2

discord_bridge.yaml.tmpl

@@ -50,7 +50,7 @@ auth:
 
 logging:
   # What level should the logger output to the console at.
-  console: "warn" #silly, verbose, info, http, warn, error, silent
+  console: "error" #silly, verbose, info, http, warn, error, silent
   lineDateFormat: "MMM-D HH:mm:ss.SSS" # This is in moment.js format
   files:
     - file: "debug.log"

entrypoint.sh.tmpl

@@ -6,6 +6,11 @@ chown 991:991 /data
 
 if [[ ! -f /data/{{ env "DOMAIN" }}.signing.key ]]; then
     /start.py generate
+    chown -R 991:991 /data/*.config /data/*.key
+fi
+
+if [[ -d /signal-data ]]; then
+    chown -R 991:991 /signal-data
 fi
 
 /start.py

mas.config.yaml.tmpl

@@ -0,0 +1,73 @@
+# Docs: https://element-hq.github.io/matrix-authentication-service/
+
+http:
+  public_base: https://{{ env "DOMAIN" }}/
+  trusted_proxies:
+    - 10.0.0.0/8
+    - 172.16.0.0/12
+    - 192.168.0.0/16
+    - 127.0.0.0/8
+    - fd00::/8
+    - ::1/128
+  listeners:
+    - name: web
+      resources:
+        - name: discovery
+        - name: human
+        - name: oauth
+        - name: compat
+        - name: graphql
+          playground: false
+        - name: assets
+        # https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#httplisteners
+        - name: health
+      binds:
+        - address: "[::]:8080"
+
+database:
+  uri: postgresql://synapse:{{ secret "db_password" }}@{{ env "STACK_NAME" }}_db:5432/mas?sslmode=disable
+
+matrix:
+  kind: synapse
+  homeserver: {{ or (env "SERVER_NAME") (env "DOMAIN") }}
+  endpoint: http://{{ env "STACK_NAME" }}_app:8008/
+  secret_file: /run/secrets/mas_synapse_shared
+
+secrets:
+  # Plain hex in file (abra: length=64 charset=hex). See .env.sample modifiers.
+  encryption_file: /run/secrets/mas_encryption
+  keys:
+    - key_file: /run/secrets/mas_signing_rsa
+
+passwords:
+  enabled: true
+  schemes:
+    - version: 1
+      algorithm: bcrypt
+      unicode_normalization: true
+    - version: 2
+      algorithm: argon2id
+
+{{ if env "MAS_UPSTREAM_PROVIDER_ID" }}
+# https://element-hq.github.io/matrix-authentication-service/setup/sso.html
+upstream_oauth2:
+  providers:
+    - id: {{ env "MAS_UPSTREAM_PROVIDER_ID" }}
+      {{ if env "MAS_UPSTREAM_SYNAPSE_IDP_ID" }}synapse_idp_id: {{ env "MAS_UPSTREAM_SYNAPSE_IDP_ID" }}{{ end }}
+      human_name: {{ or (env "MAS_UPSTREAM_HUMAN_NAME") "SSO" }}
+      issuer: {{ env "MAS_UPSTREAM_ISSUER" }}
+      client_id: {{ env "MAS_UPSTREAM_CLIENT_ID" }}
+      client_secret_file: /run/secrets/mas_upstream_client
+      token_endpoint_auth_method: client_secret_basic
+      scope: "openid profile email"
+      claims_imports:
+        localpart:
+          action: require
+          template: "{{ "{{ user.preferred_username }}" }}"
+        displayname:
+          action: suggest
+          template: "{{ "{{ user.name }}" }}"
+        email:
+          action: suggest
+          template: "{{ "{{ user.email }}" }}"
+{{ end }}

nginx.conf.tmpl

@@ -0,0 +1,96 @@
+user www-data;
+
+events {
+  worker_connections 768;
+}
+
+http {
+
+  resolver 127.0.0.11 valid=30s ipv6=off;
+  resolver_timeout 5s;
+
+  upstream matrix_upstream {
+    zone matrix_upstream 64k;
+    server {{ env "STACK_NAME"}}_app:8008 resolve;
+    keepalive 16;
+  }
+
+{{ if eq (env "MAS_ENABLED") "1" }}
+  upstream mas_upstream {
+    zone mas_upstream 64k;
+    server {{ env "STACK_NAME"}}_mas:8080 resolve;
+    keepalive 8;
+  }
+{{ end }}
+
+  server {
+    listen 80;
+
+    access_log {{ or (env "NGINX_ACCESS_LOG_LOCATION") "/dev/null" }};
+    error_log {{ or (env "NGINX_ERROR_LOG_LOCATION") "/dev/null" }};
+
+    server_name {{ env "DOMAIN" }};
+
+    location = / {
+      proxy_pass http://matrix_upstream;
+      proxy_set_header X-Forwarded-For $remote_addr;
+      proxy_set_header X-Forwarded-Proto https;
+      proxy_set_header Host $host;
+      client_max_body_size 50M;
+      proxy_http_version 1.1;
+    }
+    
+{{ if eq (env "MAS_ENABLED") "1" }}
+    # MAS on same Host as Synapse (public_base = https://$DOMAIN/): browser/OIDC paths live at repo root, not only under /_matrix/
+    # Router reference: element-hq/matrix-authentication-service crates/router/src/endpoints.rs
+    # https://element-hq.github.io/matrix-authentication-service/setup/reverse-proxy.html
+    location ~ ^/(complete-compat-sso/|oauth2/|\.well-known/(openid-configuration|webfinger|change-password)|authorize|login|logout|register(/|$)|account/|upstream/|consent/|link(\?|/|$)|device/|recover(/|$)|assets/|graphql(/|$)|api/) {
+      proxy_pass http://mas_upstream;
+      proxy_http_version 1.1;
+      proxy_set_header Host $host;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto https;
+      client_max_body_size 50M;
+    }
+    # Matrix CS API compat (login / logout / refresh and subpaths, e.g. …/login/sso/redirect) — before generic /_matrix
+    location ~ ^/_matrix/client/[^/]+/(login|logout|refresh)(/.*)?$ {
+      proxy_pass http://mas_upstream;
+      proxy_http_version 1.1;
+      proxy_set_header Host $host;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto https;
+      client_max_body_size 50M;
+    }
+{{ end }}
+
+    location ~* ^(\/_matrix|\/_synapse\/client|\/_synapse\/mas) {
+      proxy_pass http://matrix_upstream;
+      proxy_set_header X-Forwarded-For $remote_addr;
+      proxy_set_header X-Forwarded-Proto https;
+      proxy_set_header Host $host;
+      client_max_body_size 50M;
+      proxy_http_version 1.1;
+    }
+
+    location /.well-known/matrix/ {
+      root /var/www/;
+      default_type application/json;
+      add_header Access-Control-Allow-Origin  *;
+    }
+
+{{ if eq (env "ADMIN_INTERFACE_ENABLED") "1" }}
+    location ^~ /_synapse/admin {
+      if ($http_referer !~ "^https://{{ env "DOMAIN" }}/admin/") {
+        return 403;
+      }
+      proxy_pass http://matrix_upstream;
+      proxy_set_header X-Forwarded-For $remote_addr;
+      proxy_set_header X-Forwarded-Proto https;
+      proxy_set_header Host $host;
+      client_max_body_size 50M;
+      proxy_http_version 1.1;
+    }
+{{ end }}
+
+  }
+}

pg_backup.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+set -e
+
+BACKUP_FILE='/var/lib/postgresql/data/backup.sql'
+
+function backup {
+  export PGPASSWORD=$(cat $POSTGRES_PASSWORD_FILE)
+  pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB} | gzip > $BACKUP_FILE
+}
+
+function restore {
+    cd /var/lib/postgresql/data/
+    restore_config(){
+        # Restore allowed connections
+        cat pg_hba.conf.bak > pg_hba.conf
+        su postgres -c 'pg_ctl reload'
+    }
+    # Don't allow any other connections than local
+    cp pg_hba.conf pg_hba.conf.bak
+    echo "local all all trust" > pg_hba.conf
+    su postgres -c 'pg_ctl reload'
+    trap restore_config EXIT INT TERM
+
+    # Recreate Database
+    psql -U ${POSTGRES_USER} -d postgres -c "DROP DATABASE ${POSTGRES_DB} WITH (FORCE);" 
+    createdb -U ${POSTGRES_USER} ${POSTGRES_DB}
+    gunzip -c $BACKUP_FILE | psql -U ${POSTGRES_USER} -d ${POSTGRES_DB} -1 -f -
+
+    trap - EXIT INT TERM
+    restore_config
+}
+
+$@

release/2.1.0+v1.62.0

@@ -1,5 +1,9 @@
-The only release note worthy point for this release is: if you're using the
-horrendous `compose.keycloak2.yml` (as creator of this horrible hack, I am
-allowed to call it horrendous ;)), you will need to re-check the new
-~/.abra/recipes/matrix-synapse/.env.sample, there are some new default env vars
-which you'll have to add in (e.g. KEYCLOAK2_ID=...).
+If you're using the horrendous `compose.keycloak2.yml` (as creator of this
+horrible hack, I am allowed to call it horrendous ;)), you will need to
+re-check the new ~/.abra/recipes/matrix-synapse/.env.sample, there are some new
+default env vars which you'll have to add in (e.g. KEYCLOAK2_ID=...).
+
+You'll also need to add `KEYCLOAK_ID=keycloak` if using `compose.keycloak.yml`,
+it isn't vendored any more.
+
+@decentral1se

release/3.0.0+v1.74.0

@@ -0,0 +1,17 @@
+WARNING: There are a lot of config breaking changes in this one, watch out!
+
+* KEYCLOAK2* env vars have gone away, they were experimental.
+
+* TELEGRAM_BRIDGE_ADMIN* is replaced by TELEGRAM_BRIDGE_PERMISSIONS.
+
+* SIGNAL_BRIDGE_ADMIN* is replaced by SIGNAL_BRIDGE_PERMISSIONS.
+
+* The homeserver config has been trimmed, see coop-cloud/matrix-synapse#33 for more.
+
+* Bridge logging is only ERROR level now to minimise leaking plaintext.
+
+* It is possible to use SSO & federation env vars in combination now.
+
+* Media retention is now configurable with #MEDIA_RETENTION_* env vars.
+
+@decentral1se

release/4.0.0+v1.93.0

@@ -0,0 +1,10 @@
+We had to rename some secrets: https://git.coopcloud.tech/coop-cloud/matrix-synapse/issues/35
+
+Copy the secrets:
+
+* `registration_shared_secret` to `registration`
+* `macaroon_secret_key` to `macaroon`
+
+The easiest way to do this is to run `abra app run <matrix.example.com> app bash` BEFORE this upgrade, then `cat /run/secrets/registration_shared_secret`.  If you haven't saved the secrets yet, and would like to, please Ctrl+C out of this upgrade and do that first.
+
+Regeneration of these secrets should also work.

release/5.0.0+v1.93.0

@@ -0,0 +1 @@
+It's recommended not to upgrade / downgrade directly to this version (or other 5.y.z versions), because of service renaming which was reverted in 6.0.0+v1.100.0.

release/5.0.1+v1.93.0

@@ -0,0 +1,6 @@
+Logging is now disabled by default. If you want to reënable it, set these options:
+
+```
+NGINX_ACCESS_LOG_LOCATION="/dev/stdout"
+NGINX_ERROR_LOG_LOCATION="/dev/stderr"
+```

release/6.0.0+v1.100.0

@@ -0,0 +1 @@
+If you are upgrading from verison 5.y.z of this recipe, you will need to `undeploy` then `deploy`, because of a service rename which was reverted.

release/6.6.1+v1.124.0

@@ -0,0 +1 @@
+added env REGISTRATION_REQUIRES_TOKEN

release/6.6.2+v1.124.0

@@ -0,0 +1 @@
+new optional env vars for user_directory and privacy options

release/6.6.3+v1.124.0

@@ -0,0 +1 @@
+added env for old-signing-keys

release/6.7.1+v1.133.0

@@ -0,0 +1 @@
+This patch contains a critical nginx fix, to allow resolving docker internal hosts.

release/6.8.2+v1.139.2

@@ -0,0 +1 @@
+this patch is a reset to the state of the last known deploying version 6.8.0 – so better skip 6.8.1

release/7.0.0+v1.149.1

@@ -0,0 +1,2 @@
+WARNING: Backup your database!
+This upgrade switches the database image from postgres to pgautoupgrade and performs an in-place database upgrades from version 13 to 17.

release/7.1.0+v1.149.1

@@ -0,0 +1 @@
+added matrix-authentication-service as opt-in to the recipe, see readme for details

renovate.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ]
+}

shared_secret_authenticator.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+#
+# Shared Secret Authenticator module for Matrix Synapse
+# Copyright (C) 2018 Slavi Pantaleev
+#
+# https://devture.com/
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+from typing import Awaitable, Callable, Optional, Tuple
+
+import hashlib
+import hmac
+import logging
+
+import synapse
+from synapse import module_api
+
+logger = logging.getLogger(__name__)
+
+class SharedSecretAuthProvider:
+    def __init__(self, config: dict, api: module_api):
+        for k in ('shared_secret',):
+            if k not in config:
+                raise KeyError('Required `{0}` configuration key not found'.format(k))
+
+        m_login_password_support_enabled = bool(config['m_login_password_support_enabled']) if 'm_login_password_support_enabled' in config else False
+        com_devture_shared_secret_auth_support_enabled = bool(config['com_devture_shared_secret_auth_support_enabled']) if 'com_devture_shared_secret_auth_support_enabled' in config else True
+
+        self.api = api
+        self.shared_secret = config['shared_secret']
+
+        auth_checkers: Optional[Dict[Tuple[str, Tuple], CHECK_AUTH_CALLBACK]] = {}
+        if com_devture_shared_secret_auth_support_enabled:
+            auth_checkers[("com.devture.shared_secret_auth", ("token",))] = self.check_com_devture_shared_secret_auth
+        if m_login_password_support_enabled:
+            auth_checkers[("m.login.password", ("password",))] = self.check_m_login_password
+
+        enabled_login_types = [k[0] for k in auth_checkers]
+
+        if len(enabled_login_types) == 0:
+            raise RuntimeError('At least one login type must be enabled')
+
+        logger.info('Enabled login types: %s', enabled_login_types)
+
+        api.register_password_auth_provider_callbacks(
+            auth_checkers=auth_checkers,
+        )
+
+    async def check_com_devture_shared_secret_auth(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "com.devture.shared_secret_auth":
+            return None
+        return await self._log_in_username_with_token("com.devture.shared_secret_auth", username, login_dict.get("token"))
+
+    async def check_m_login_password(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "m.login.password":
+            return None
+        return await self._log_in_username_with_token("m.login.password", username, login_dict.get("password"))
+
+    async def _log_in_username_with_token(
+        self,
+        login_type: str,
+        username: str,
+        token: str,
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        logger.info('Authenticating user `%s` with login type `%s`', username, login_type)
+
+        full_user_id = self.api.get_qualified_user_id(username)
+
+        # The password (token) is supposed to be an HMAC of the full user id, keyed with the shared secret.
+        given_hmac = token.encode('utf-8')
+
+        h = hmac.new(self.shared_secret.encode('utf-8'), full_user_id.encode('utf-8'), hashlib.sha512)
+        computed_hmac = h.hexdigest().encode('utf-8')
+
+        if not hmac.compare_digest(computed_hmac, given_hmac):
+            logger.info('Bad hmac value for user: %s', full_user_id)
+            return None
+
+        user_info = await self.api.get_userinfo_by_id(full_user_id)
+        if user_info is None:
+            logger.info('Refusing to authenticate missing user: %s', full_user_id)
+            return None
+
+        logger.info('Authenticated user: %s', full_user_id)
+
+        return full_user_id, None

signal_bridge.yaml.tmpl

@@ -0,0 +1,411 @@
+# Network-specific config options
+network:
+    # Displayname template for Signal users.
+    # {{ "{{.ProfileName}}" }} - The Signal profile name set by the user.
+    # {{ "{{.ContactName}}" }} - The name for the user from your phone's contact list. This is not safe on multi-user instances.
+    # {{ "{{.PhoneNumber}}" }} - The phone number of the user.
+    # {{ "{{.UUID}}" }} - The UUID of the Signal user.
+    # {{ "{{.AboutEmoji}}" }} - The emoji set by the user in their profile.
+    displayname_template: '{{ "{{or .ProfileName .PhoneNumber \"Unknown user\"}}" }}'
+    # Should avatars from the user's contact list be used? This is not safe on multi-user instances.
+    use_contact_avatars: false
+    # Should the bridge request the user's contact list from the phone on startup?
+    sync_contacts_on_startup: true
+    # Should the bridge sync ghost user info even if profile fetching fails? This is not safe on multi-user instances.
+    use_outdated_profiles: false
+    # Should the Signal user's phone number be included in the room topic in private chat portal rooms?
+    number_in_topic: true
+    # Default device name that shows up in the Signal app.
+    device_name: mautrix-signal
+    # Avatar image for the Note to Self room.
+    note_to_self_avatar: mxc://maunium.net/REBIVrqjZwmaWpssCZpBlmlL
+    # Format for generating URLs from location messages for sending to Signal.
+    # Google Maps: 'https://www.google.com/maps/place/%[1]s,%[2]s'
+    # OpenStreetMap: 'https://www.openstreetmap.org/?mlat=%[1]s&mlon=%[2]s'
+    location_format: 'https://www.google.com/maps/place/%[1]s,%[2]s'
+    
+
+# Config options that affect the central bridge module.
+bridge:
+    # The prefix for commands. Only required in non-management rooms.
+    command_prefix: '!signal'
+    # Should the bridge create a space for each login containing the rooms that account is in?
+    personal_filtering_spaces: true
+    # Whether the bridge should set names and avatars explicitly for DM portals.
+    # This is only necessary when using clients that don't support MSC4171.
+    private_chat_portal_meta: false
+
+    # Should leaving Matrix rooms be bridged as leaving groups on the remote network?
+    bridge_matrix_leave: false
+    # Should room tags only be synced when creating the portal? Tags mean things like favorite/pin and archive/low priority.
+    # Tags currently can't be synced back to the remote network, so a continuous sync means tagging from Matrix will be undone.
+    tag_only_on_create: true
+    # Should room mute status only be synced when creating the portal?
+    # Like tags, mutes can't currently be synced back to the remote network.
+    mute_only_on_create: true
+
+    # What should be done to portal rooms when a user logs out or is logged out?
+    # Permitted values:
+    #   nothing - Do nothing, let the user stay in the portals
+    #   kick - Remove the user from the portal rooms, but don't delete them
+    #   unbridge - Remove all ghosts in the room and disassociate it from the remote chat
+    #   delete - Remove all ghosts and users from the room (i.e. delete it)
+    cleanup_on_logout:
+        # Should cleanup on logout be enabled at all?
+        enabled: false
+        # Settings for manual logouts (explicitly initiated by the Matrix user)
+        manual:
+            # Action for private portals which will never be shared with other Matrix users.
+            private: nothing
+            # Action for portals with a relay user configured.
+            relayed: nothing
+            # Action for portals which may be shared, but don't currently have any other Matrix users.
+            shared_no_users: nothing
+            # Action for portals which have other logged-in Matrix users.
+            shared_has_users: nothing
+        # Settings for credentials being invalidated (initiated by the remote network, possibly through user action).
+        # Keys have the same meanings as in the manual section.
+        bad_credentials:
+            private: nothing
+            relayed: nothing
+            shared_no_users: nothing
+            shared_has_users: nothing
+
+    # Settings for relay mode
+    relay:
+        # Whether relay mode should be allowed. If allowed, the set-relay command can be used to turn any
+        # authenticated user into a relaybot for that chat.
+        enabled: true
+        # Should only admins be allowed to set themselves as relay users?
+        # If true, non-admins can only set users listed in default_relays as relays in a room.
+        admin_only: true
+        # List of user login IDs which anyone can set as a relay, as long as the relay user is in the room.
+        default_relays: []
+        # The formats to use when sending messages via the relaybot.
+        # Available variables:
+        #   .Sender.UserID - The Matrix user ID of the sender.
+        #   .Sender.Displayname - The display name of the sender (if set).
+        #   .Sender.RequiresDisambiguation - Whether the sender's name may be confused with the name of another user in the room.
+        #   .Sender.DisambiguatedName - The disambiguated name of the sender. This will be the displayname if set,
+        #                               plus the user ID in parentheses if the displayname is not unique.
+        #                               If the displayname is not set, this is just the user ID.
+        #   .Message - The `formatted_body` field of the message.
+        #   .Caption - The `formatted_body` field of the message, if it's a caption. Otherwise an empty string.
+        #   .FileName - The name of the file being sent.
+        message_formats:
+            m.text: "{{`{{ .Sender.DisambiguatedName }}: {{ .Message }}`}}"
+            m.notice: "{{`{{ .Sender.DisambiguatedName }}: {{ .Message }}`}}"
+            m.emote: "{{`* {{ .Sender.DisambiguatedName }} {{ .Message }}`}}"
+            m.file: "{{`{{ .Sender.DisambiguatedName }} sent a file{{ if .Caption }}: {{ .Caption }}{{ end }}`}}"
+            m.image: "{{`{{ .Sender.DisambiguatedName }} sent an image{{ if .Caption }}: {{ .Caption }}{{ end }}`}}"
+            m.audio: "{{`{{ .Sender.DisambiguatedName }} sent an audio file{{ if .Caption }}: {{ .Caption }}{{ end }}`}}"
+            m.video: "{{`{{ .Sender.DisambiguatedName }} sent a video{{ if .Caption }}: {{ .Caption }}{{ end }}`}}"
+            m.location: "{{`{{ .Sender.DisambiguatedName }} sent a location{{ if .Caption }}: {{ .Caption }}{{ end }}`}}"
+        # For networks that support per-message displaynames (i.e. Slack and Discord), the template for those names.
+        # This has all the Sender variables available under message_formats (but without the .Sender prefix).
+        # Note that you need to manually remove the displayname from message_formats above.
+        displayname_format: "{{`{{ .DisambiguatedName }}`}}"
+
+
+    # Permissions for using the bridge.
+    # Permitted values:
+    #    relay - Talk through the relaybot (if enabled), no access otherwise
+    # commands - Access to use commands in the bridge, but not login.
+    #     user - Access to use the bridge with puppeting.
+    #    admin - Full access, user level with some additional administration tools.
+    # Permitted keys:
+    #        * - All Matrix users
+    #   domain - All users on that homeserver
+    #     mxid - Specific user
+    permissions: {{ env "SIGNAL_BRIDGE_PERMISSIONS" }}
+
+# Config for the bridge's database.
+database:
+    # The database type. "sqlite3-fk-wal" and "postgres" are supported.
+    type: postgres
+    # The database URI.
+    #   SQLite: A raw file path is supported, but `file:<path>?_txlock=immediate` is recommended.
+    #           https://github.com/mattn/go-sqlite3#connection-string
+    #   Postgres: Connection string. For example, postgres://user:password@host/database?sslmode=disable
+    #             To connect via Unix socket, use something like postgres:///dbname?host=/var/run/postgresql
+    uri:  postgres://signalbridge:{{ secret "signal_db_password" }}@signaldb/signalbridge?sslmode=disable
+    # Maximum number of connections.
+    max_open_conns: 5
+    max_idle_conns: 1
+    # Maximum connection idle time and lifetime before they're closed. Disabled if null.
+    # Parsed with https://pkg.go.dev/time#ParseDuration
+    max_conn_idle_time: null
+    max_conn_lifetime: null
+
+# Homeserver details.
+homeserver:
+    # The address that this appservice can use to connect to the homeserver.
+    # Local addresses without HTTPS are generally recommended when the bridge is running on the same machine,
+    # but https also works if they run on different machines.
+    address: {{ env "HOMESERVER_URL" }}
+    # The domain of the homeserver (also known as server_name, used for MXIDs, etc).
+    domain: {{ env "HOMESERVER_DOMAIN" }}
+
+    # What software is the homeserver running?
+    # Standard Matrix homeservers like Synapse, Dendrite and Conduit should just use "standard" here.
+    software: standard
+    # The URL to push real-time bridge status to.
+    # If set, the bridge will make POST requests to this URL whenever a user's remote network connection state changes.
+    # The bridge will use the appservice as_token to authorize requests.
+    status_endpoint: null
+    # Endpoint for reporting per-message status.
+    # If set, the bridge will make POST requests to this URL when processing a message from Matrix.
+    # It will make one request when receiving the message (step BRIDGE), one after decrypting if applicable
+    # (step DECRYPTED) and one after sending to the remote network (step REMOTE). Errors will also be reported.
+    # The bridge will use the appservice as_token to authorize requests.
+    message_send_checkpoint_endpoint:
+    # Does the homeserver support https://github.com/matrix-org/matrix-spec-proposals/pull/2246?
+    async_media: false
+
+    # Should the bridge use a websocket for connecting to the homeserver?
+    # The server side is currently not documented anywhere and is only implemented by mautrix-wsproxy,
+    # mautrix-asmux (deprecated), and hungryserv (proprietary).
+    websocket: false
+    # How often should the websocket be pinged? Pinging will be disabled if this is zero.
+    ping_interval_seconds: 0
+
+# Application service host/registration related details.
+# Changing these values requires regeneration of the registration (except when noted otherwise)
+appservice:
+    # The address that the homeserver can use to connect to this appservice.
+    address: http://signalbridge:29328
+    # A public address that external services can use to reach this appservice.
+    # This value doesn't affect the registration file.
+    public_address: https://bridge.example.com
+
+    # The hostname and port where this appservice should listen.
+    hostname: 0.0.0.0
+    port: 29328
+
+    # The unique ID of this appservice.
+    id: signal
+    # Appservice bot details.
+    bot:
+        # Username of the appservice bot.
+        username: signalbot
+        # Display name and avatar for bot. Set to "remove" to remove display name/avatar, leave empty
+        # to leave display name/avatar as-is.
+        displayname: Signal bridge bot
+        avatar: mxc://maunium.net/wPJgTQbZOtpBFmDNkiNEMDUp
+
+    # Whether to receive ephemeral events via appservice transactions.
+    ephemeral_events: true
+    # Should incoming events be handled asynchronously?
+    # This may be necessary for large public instances with lots of messages going through.
+    # However, messages will not be guaranteed to be bridged in the same order they were sent in.
+    # This value doesn't affect the registration file.
+    async_transactions: false
+
+    # Authentication tokens for AS <-> HS communication. Autogenerated; do not modify.
+    as_token: "{{ secret "signal_as_token" }}"
+    hs_token: "{{ secret "signal_hs_token" }}"
+
+    # Localpart template of MXIDs for remote users.
+    # {{ "{{.}}" }} is replaced with the internal ID of the user.
+    username_template: signal_{{ "{{.}}" }}
+
+# Config options that affect the Matrix connector of the bridge.
+matrix:
+    # Whether the bridge should send the message status as a custom com.beeper.message_send_status event.
+    message_status_events: false
+    # Whether the bridge should send a read receipt after successfully bridging a message.
+    delivery_receipts: false
+    # Whether the bridge should send error notices via m.notice events when a message fails to bridge.
+    message_error_notices: true
+    # Whether the bridge should update the m.direct account data event when double puppeting is enabled.
+    sync_direct_chat_list: false
+    # Whether created rooms should have federation enabled. If false, created portal rooms
+    # will never be federated. Changing this option requires recreating rooms.
+    federate_rooms: true
+
+# Settings for provisioning API
+provisioning:
+    # Prefix for the provisioning API paths.
+    prefix: /_matrix/provision
+    # Shared secret for authentication. If set to "generate" or null, a random secret will be generated,
+    # or if set to "disable", the provisioning API will be disabled.
+    shared_secret: generate
+    # Whether to allow provisioning API requests to be authed using Matrix access tokens.
+    # This follows the same rules as double puppeting to determine which server to contact to check the token,
+    # which means that by default, it only works for users on the same server as the bridge.
+    allow_matrix_auth: true
+    # Enable debug API at /debug with provisioning authentication.
+    debug_endpoints: false
+
+# Some networks require publicly accessible media download links (e.g. for user avatars when using Discord webhooks).
+# These settings control whether the bridge will provide such public media access.
+public_media:
+    # Should public media be enabled at all?
+    # The public_address field under the appservice section MUST be set when enabling public media.
+    enabled: false
+    # A key for signing public media URLs.
+    # If set to "generate", a random key will be generated.
+    signing_key: generate
+    # Number of seconds that public media URLs are valid for.
+    # If set to 0, URLs will never expire.
+    expiry: 0
+    # Length of hash to use for public media URLs. Must be between 0 and 32.
+    hash_length: 32
+
+# Settings for converting remote media to custom mxc:// URIs instead of reuploading.
+# More details can be found at https://docs.mau.fi/bridges/go/discord/direct-media.html
+direct_media:
+    # Should custom mxc:// URIs be used instead of reuploading media?
+    enabled: false
+    # The server name to use for the custom mxc:// URIs.
+    # This server name will effectively be a real Matrix server, it just won't implement anything other than media.
+    # You must either set up .well-known delegation from this domain to the bridge, or proxy the domain directly to the bridge.
+    server_name: discord-media.example.com
+    # Optionally a custom .well-known response. This defaults to `server_name:443`
+    well_known_response:
+    # Optionally specify a custom prefix for the media ID part of the MXC URI.
+    media_id_prefix:
+    # If the remote network supports media downloads over HTTP, then the bridge will use MSC3860/MSC3916
+    # media download redirects if the requester supports it. Optionally, you can force redirects
+    # and not allow proxying at all by setting this to false.
+    # This option does nothing if the remote network does not support media downloads over HTTP.
+    allow_proxy: true
+    # Matrix server signing key to make the federation tester pass, same format as synapse's .signing.key file.
+    # This key is also used to sign the mxc:// URIs to ensure only the bridge can generate them.
+    server_key: generate
+
+# Settings for backfilling messages.
+# Note that the exact way settings are applied depends on the network connector.
+# See https://docs.mau.fi/bridges/general/backfill.html for more details.
+backfill:
+    # Whether to do backfilling at all.
+    enabled: false
+    # Maximum number of messages to backfill in empty rooms.
+    max_initial_messages: 50
+    # Maximum number of missed messages to backfill after bridge restarts.
+    max_catchup_messages: 500
+    # If a backfilled chat is older than this number of hours,
+    # mark it as read even if it's unread on the remote network.
+    unread_hours_threshold: 720
+    # Settings for backfilling threads within other backfills.
+    threads:
+        # Maximum number of messages to backfill in a new thread.
+        max_initial_messages: 50
+    # Settings for the backwards backfill queue. This only applies when connecting to
+    # Beeper as standard Matrix servers don't support inserting messages into history.
+    queue:
+        # Should the backfill queue be enabled?
+        enabled: false
+        # Number of messages to backfill in one batch.
+        batch_size: 100
+        # Delay between batches in seconds.
+        batch_delay: 20
+        # Maximum number of batches to backfill per portal.
+        # If set to -1, all available messages will be backfilled.
+        max_batches: -1
+        # Optional network-specific overrides for max batches.
+        # Interpretation of this field depends on the network connector.
+        max_batches_override: {}
+
+# Settings for enabling double puppeting
+double_puppet:
+    # Servers to always allow double puppeting from.
+    # This is only for other servers and should NOT contain the server the bridge is on.
+    servers:
+        {{ env "HOMESERVER_DOMAIN" }}: {{ env "HOMESERVER_URL" }}
+    # Whether to allow client API URL discovery for other servers. When using this option,
+    # users on other servers can use double puppeting even if their server URLs aren't
+    # explicitly added to the servers map above.
+    allow_discovery: false
+    # Shared secrets for automatic double puppeting.
+    # See https://docs.mau.fi/bridges/general/double-puppeting.html for instructions.
+    secrets:
+        {{ env "HOMESERVER_DOMAIN" }}: {{ secret "shared_secret_auth" }}
+
+# End-to-bridge encryption support options.
+#
+# See https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html for more info.
+encryption:
+    # Whether to enable encryption at all. If false, the bridge will not function in encrypted rooms.
+    allow: {{ env "SIGNAL_ENABLE_ENCRYPTION" }}
+    # Whether to force-enable encryption in all bridged rooms.
+    default: {{ env "SIGNAL_DEFAULT_ENCRYPTION" }}
+    # Whether to require all messages to be encrypted and drop any unencrypted messages.
+    require: false
+    # Whether to use MSC2409/MSC3202 instead of /sync long polling for receiving encryption-related data.
+    # This option is not yet compatible with standard Matrix servers like Synapse and should not be used.
+    appservice: false
+    # Enable key sharing? If enabled, key requests for rooms where users are in will be fulfilled.
+    # You must use a client that supports requesting keys from other users to use this feature.
+    allow_key_sharing: false
+    # Pickle key for encrypting encryption keys in the bridge database.
+    # If set to generate, a random key will be generated.
+    pickle_key: {{ secret "signal_pickle_key" }}
+    # Options for deleting megolm sessions from the bridge.
+    delete_keys:
+        # Beeper-specific: delete outbound sessions when hungryserv confirms
+        # that the user has uploaded the key to key backup.
+        delete_outbound_on_ack: false
+        # Don't store outbound sessions in the inbound table.
+        dont_store_outbound: false
+        # Ratchet megolm sessions forward after decrypting messages.
+        ratchet_on_decrypt: false
+        # Delete fully used keys (index >= max_messages) after decrypting messages.
+        delete_fully_used_on_decrypt: false
+        # Delete previous megolm sessions from same device when receiving a new one.
+        delete_prev_on_new_session: false
+        # Delete megolm sessions received from a device when the device is deleted.
+        delete_on_device_delete: false
+        # Periodically delete megolm sessions when 2x max_age has passed since receiving the session.
+        periodically_delete_expired: false
+        # Delete inbound megolm sessions that don't have the received_at field used for
+        # automatic ratcheting and expired session deletion. This is meant as a migration
+        # to delete old keys prior to the bridge update.
+        delete_outdated_inbound: false
+    # What level of device verification should be required from users?
+    #
+    # Valid levels:
+    #   unverified - Send keys to all device in the room.
+    #   cross-signed-untrusted - Require valid cross-signing, but trust all cross-signing keys.
+    #   cross-signed-tofu - Require valid cross-signing, trust cross-signing keys on first use (and reject changes).
+    #   cross-signed-verified - Require valid cross-signing, plus a valid user signature from the bridge bot.
+    #                           Note that creating user signatures from the bridge bot is not currently possible.
+    #   verified - Require manual per-device verification
+    #              (currently only possible by modifying the `trust` column in the `crypto_device` database table).
+    verification_levels:
+        # Minimum level for which the bridge should send keys to when bridging messages from the remote network to Matrix.
+        receive: unverified
+        # Minimum level that the bridge should accept for incoming Matrix messages.
+        send: unverified
+        # Minimum level that the bridge should require for accepting key requests.
+        share: cross-signed-tofu
+    # Options for Megolm room key rotation. These options allow you to configure the m.room.encryption event content.
+    # See https://spec.matrix.org/v1.10/client-server-api/#mroomencryption for more information about that event.
+    rotation:
+        # Enable custom Megolm room key rotation settings. Note that these
+        # settings will only apply to rooms created after this option is set.
+        enable_custom: false
+        # The maximum number of milliseconds a session should be used
+        # before changing it. The Matrix spec recommends 604800000 (a week)
+        # as the default.
+        milliseconds: 604800000
+        # The maximum number of messages that should be sent with a given a
+        # session before changing it. The Matrix spec recommends 100 as the
+        # default.
+        messages: 100
+        # Disable rotating keys when a user's devices change?
+        # You should not enable this option unless you understand all the implications.
+        disable_device_change_key_rotation: false
+
+# Logging config. See https://github.com/tulir/zeroconfig for details.
+logging:
+    min_level: debug
+    writers:
+        - type: stdout
+          format: pretty-colored
+        - type: file
+          format: json
+          filename: ./logs/bridge.log
+          max_size: 100
+          max_backups: 10
+          compress: false

telegram_bridge.yaml.tmpl

@@ -151,7 +151,7 @@ bridge:
     # Whether or not to sync the member list in channels.
     # If no channel admins have logged into the bridge, the bridge won't be able to sync the member
     # list regardless of this setting.
-    sync_channel_members: true
+    sync_channel_members: {{ env "TELEGRAM_SYNC_CHANNEL_MEMBERS" }}
     # Whether or not to skip deleted members when syncing members.
     skip_deleted_members: true
     # Whether or not to automatically synchronize contacts and chats of Matrix users logged into
@@ -189,7 +189,7 @@ bridge:
     sync_direct_chat_list: false
     # Servers to always allow double puppeting from
     double_puppet_server_map:
-        example.com: https://example.com
+        {{ env "HOMESERVER_DOMAIN" }}: {{ env "HOMESERVER_URL" }}
     # Allow using double puppeting from any server with a valid client .well-known file.
     double_puppet_allow_discovery: false
     # Shared secrets for https://github.com/devture/matrix-synapse-shared-secret-auth
@@ -200,7 +200,7 @@ bridge:
     # If using this for other servers than the bridge's server,
     # you must also set the URL in the double_puppet_server_map.
     login_shared_secret_map:
-        example.com: foobar
+        {{ env "HOMESERVER_DOMAIN" }}: {{ secret "shared_secret_auth" }}
     # Set to false to disable link previews in messages sent to Telegram.
     telegram_link_preview: true
     # Whether or not the !tg join command should do a HTTP request
@@ -412,10 +412,7 @@ bridge:
     #        * - All Matrix users
     #   domain - All users on that homeserver
     #     mxid - Specific user
-    permissions:
-        "*": "relaybot"
-        "{{ env "TELEGRAM_BRIDGE_ADMIN_1" }}": "admin"
-        "{{ env "TELEGRAM_BRIDGE_ADMIN_2" }}": "admin"
+    permissions: {{ env "TELEGRAM_BRIDGE_PERMISSIONS" }}
 
     # Options related to the message relay Telegram bot.
     relaybot:
@@ -537,11 +534,11 @@ logging:
             formatter: colored
     loggers:
         mau:
-            level: DEBUG
+            level: ERROR
         telethon:
-            level: INFO
+            level: ERROR
         aiohttp:
-            level: INFO
+            level: ERROR
     root:
-        level: DEBUG
+        level: ERROR
         handlers: [file, console]

well_known_client.conf.tmpl

@@ -0,0 +1,8 @@
+{
+  "m.homeserver": {
+    "base_url": "https://{{ env "DOMAIN" }}"
+  }{{ if eq (env "MAS_ENABLED") "1" }},
+  "org.matrix.msc2965.authentication": {
+    "issuer": "https://{{ env "DOMAIN" }}/"
+  }{{ end }}
+}

well_known_server.conf.tmpl

@@ -0,0 +1,3 @@
+{
+  "m.server": "{{ env "DOMAIN" }}:443"
+}