Add pre-commit check for migration version sync between defaults and examples/vars.yml

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.codespellrc

@@ -1,2 +1,2 @@
 [codespell]
-ignore-words-list = aNULL,brose,doub,Udo,re-use,re-used,registr,shema
+ignore-words-list = aNULL,brose,doub,Udo,re-use,re-used,registr,shema,commet,Commet

.github/workflows/matrix.yml

@@ -9,34 +9,37 @@ name: Matrix CI
 
 on: [push, pull_request]  # yamllint disable-line rule:truthy
 
+permissions:
+  contents: read
+
 jobs:
-  yamllint:
+  prek:
-    name: yamllint
+    name: Run prek hooks
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out
-        uses: actions/checkout@v6
-      - name: Run yamllint
-        uses: frenck/action-yamllint@v1.5.0
-  ansible-lint:
-    name: ansible-lint
     runs-on: ubuntu-latest
+    container:
+      image: docker.io/archlinux:base-devel
+
     steps:
+      # git must be installed before checkout so it does a proper clone
+      # (with .git directory) instead of a tarball download.
+      - name: Install git
+        run: pacman -Sy --noconfirm git
+
       - name: Check out
         uses: actions/checkout@v6
 
-      - name: Run ansible-lint
+      - name: Restore prek cache
-        uses: ansible/ansible-lint@v26.1.1
+        uses: actions/cache@v5
         with:
-          args: "roles/custom"
+          path: var/prek
-          setup_python: "true"
+          key: arch-prek-v1-${{ hashFiles('.pre-commit-config.yaml') }}
-          working_directory: ""
+
-          requirements_file: requirements.yml
+      - name: Install dependencies
-  precommit:
+        run: pacman -S --noconfirm --needed just mise python
-    name: Run pre-commit
+
-    runs-on: ubuntu-latest
+      - name: Run prek hooks
-    steps:
+        run: |
-      - name: Checkout code
+          # The checkout action sets safe.directory using its own bundled
-        uses: actions/checkout@v6
+          # git, which is separate from the pacman-installed git that prek uses.
-      - name: Run pre-commit
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
-        uses: pre-commit/action@v3.0.1
+          just prek-run-on-all

.gitignore

@@ -4,6 +4,7 @@
 .python-version
 .idea/
 .direnv/
+/var/
 
 # ignore roles pulled by ansible-galaxy
 /roles/galaxy/*

.pre-commit-config.yaml

@@ -1,22 +1,21 @@
 ---
-default_install_hook_types: [pre-push]
 
-exclude: "LICENSES/"
+exclude: "^(LICENSES/|var/)"
 
 # See: https://pre-commit.com/hooks.html
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:
-      # - id: check-executables-have-shebangs
       - id: check-added-large-files
       - id: check-case-conflict
       - id: check-json
+      - id: check-shebang-scripts-are-executable
       - id: check-toml
       - id: trailing-whitespace
       - id: end-of-file-fixer
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.2
     hooks:
       - id: codespell
         args: ["--skip=*.po,*.pot,i18n/"]
@@ -24,3 +23,18 @@ repos:
     rev: v6.2.0
     hooks:
       - id: reuse
+  - repo: https://github.com/ansible/ansible-lint
+    rev: v26.3.0
+    hooks:
+      - id: ansible-lint
+        files: '^roles/custom/'
+        args: ['roles/custom']
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: check-examples-vars-migration-version
+        name: Check examples/vars.yml migration version matches expected
+        entry: bin/check-examples-vars-migration-version.sh
+        language: script
+        files: '(examples/vars\.yml|roles/custom/matrix_playbook_migration/defaults/main\.yml)'
+        pass_filenames: false

CHANGELOG.md

@@ -1,3 +1,96 @@
+# 2026-03-23
+
+## Migration validation system introduced
+
+Previously, when updating your setup, you had to remember to read the [CHANGELOG](CHANGELOG.md) file or risk breakage.
+
+Now, the playbook includes a migration validation system that ensures you're aware of breaking changes before they affect your deployment.
+You're now forced to acknowledge each breaking change, unless you wish to live dangerously (see below).
+
+A new `matrix_playbook_migration_validated_version` variable has been introduced.
+
+**New users** who started from the [example `vars.yml`](examples/vars.yml) file already have this variable set and do not need to do anything.
+
+**Existing users** will need to add the following to their `vars.yml` file after reviewing all changelog entries up to now:
+
+```yml
+matrix_playbook_migration_validated_version: v2026.03.23.0
+```
+
+Going forward, whenever a breaking change is introduced the playbook will:
+
+- bump its expected version value (`matrix_playbook_migration_expected_version`), causing a discrepancy with what you validated (`matrix_playbook_migration_validated_version`)
+
+- fail when you run it with a helpful message listing what changed and linking to the relevant changelog entries
+
+After reviewing and adapting your setup, you simply update the variable to the new version.
+
+If you'd like to live dangerously and skip these checks (not recommended), you can set this once and be done with it:
+
+```yml
+matrix_playbook_migration_validated_version: "{{ matrix_playbook_migration_expected_version }}"
+```
+
+# 2026-03-19
+
+## Matrix Authentication Service now prefers UNIX sockets for playbook-managed Postgres
+
+When [Matrix Authentication Service](docs/configuring-playbook-matrix-authentication-service.md) (MAS) uses the playbook-managed Postgres service, it now connects to it via a [UNIX socket](https://en.wikipedia.org/wiki/Unix_domain_socket) by default instead of TCP.
+
+This follows the same approach [applied to Synapse](#synapse-now-prefers-unix-sockets-for-playbook-managed-postgres-and-valkey) and reduces unnecessary container-network wiring, keeping local IPC off the network stack.
+
+If you use an external Postgres server for MAS, this does not change your setup.
+
+If you'd like to keep the previous TCP-based behavior, add the following configuration to your `vars.yml`:
+
+```yaml
+matrix_authentication_service_config_database_socket_enabled: false
+```
+
+# 2026-03-17
+
+## Synapse now prefers UNIX sockets for playbook-managed Postgres and Valkey
+
+When Synapse uses the playbook-managed Postgres and Valkey services, it now connects to them via [UNIX sockets](https://en.wikipedia.org/wiki/Unix_domain_socket) by default instead of TCP.
+
+This reduces unnecessary container-network wiring and keeps local IPC off the network stack, which is a bit simpler and slightly more secure.
+
+If you use an external Postgres server or external Redis/Valkey for Synapse, this does not change your setup.
+
+If you'd like to keep the previous TCP-based behavior, add the following configuration to your `vars.yml`:
+
+```yaml
+matrix_synapse_database_socket_enabled: false
+matrix_synapse_redis_path_enabled: false
+```
+
+# 2026-03-01
+
+## (Potential BC Break) Synapse S3 media prefix is now applied consistently
+
+The `matrix_synapse_ext_synapse_s3_storage_provider_config_prefix` variable is now wired consistently for both:
+
+- the Synapse `s3_storage_provider` module configuration
+- the `matrix-synapse-s3-storage-provider-migrate` migration script (`s3_media_upload --prefix`)
+
+Previously, this variable could be set, but was not effectively applied by either of these paths.
+
+**Affects**: users of [synapse-s3-storage-provider](docs/configuring-playbook-synapse-s3-storage-provider.md) who have configured a non-empty `matrix_synapse_ext_synapse_s3_storage_provider_config_prefix` value.
+
+If your bucket data was uploaded without the prefix before this fix, enabling proper prefix usage can make existing objects appear missing until data is migrated/copied to the prefixed key namespace.
+
+# 2026-02-26
+
+## Internal refactor: merged the Synapse reverse-proxy companion role into `matrix-synapse`
+
+The standalone `matrix-synapse-reverse-proxy-companion` role has been merged into the [matrix-synapse](roles/custom/matrix-synapse/) role.
+
+This is not a user-facing change and does not change variable names (`matrix_synapse_reverse_proxy_companion_*` remain the same). The split looked clean on paper, but in practice both parts are tightly coupled through worker routing, tags (`setup-synapse`/`install-synapse`), and lifecycle ordering, so keeping them separate added coordination overhead with little practical benefit.
+
+Compatibility note: existing companion-specific tags (`setup-synapse-reverse-proxy-companion` and `install-synapse-reverse-proxy-companion`) are still available.
+
+With this change, Synapse and its reverse-proxy companion are managed in one role (`matrix-synapse`) while still keeping companion logic in dedicated task/template subdirectories for maintainability.
+
 # 2026-02-21
 
 ## (BC Break) coturn is no longer auto-enabled by default

README.md

@@ -64,6 +64,7 @@ Web clients for Matrix that you can host on your own domains.
 | [Element Web](https://github.com/element-hq/element-web) | ✅ | Default Matrix web client, configured to connect to your own Synapse server | [Link](docs/configuring-playbook-client-element-web.md) |
 | [Hydrogen](https://github.com/element-hq/hydrogen-web) | ❌ | Lightweight Matrix client with legacy and mobile browser support | [Link](docs/configuring-playbook-client-hydrogen.md) |
 | [Cinny](https://github.com/ajbura/cinny) |  ❌ | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
+| [Sable](https://github.com/7w1/sable) | ❌ | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-sable.md) |
 | [SchildiChat Web](https://schildi.chat/) | ❌ | Based on Element Web, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat-web.md) |
 | [FluffyChat Web](https://fluffychat.im/) | ❌ | The cutest messenger in Matrix | [Link](docs/configuring-playbook-client-fluffychat-web.md) |
 
@@ -74,13 +75,12 @@ Services that run on the server to make the various parts of your installation w
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
 | [PostgreSQL](https://www.postgresql.org/)| ✅ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
-| [coturn](https://github.com/coturn/coturn) | ❌ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
 | [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. [Using your own webserver](docs/configuring-playbook-own-webserver.md) is also possible. | [Link](docs/configuring-playbook-traefik.md) |
 | [Let's Encrypt](https://letsencrypt.org/) | ✅ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
 | [Exim](https://www.exim.org/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
+| [coturn](https://github.com/coturn/coturn) | ❌ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
 | [ddclient](https://github.com/linuxserver/docker-ddclient) | ❌ | Dynamic DNS | [Link](docs/configuring-playbook-dynamic-dns.md) |
-| [LiveKit Server](https://github.com/livekit/livekit) | ❌ | WebRTC server for audio/video calls | [Link](docs/configuring-playbook-livekit-server.md) |
+| Matrix RTC stack | ❌ | Supporting components ([LiveKit Server](docs/configuring-playbook-livekit-server.md) and [LiveKit JWT Service](docs/configuring-playbook-livekit-jwt-service.md)) for in-app audio/video calls for Matrix clients | [Link](docs/configuring-playbook-matrix-rtc.md) |
-| [Livekit JWT Service](https://github.com/livekit/livekit-jwt-service) | ❌ | JWT service for integrating [Element Call](./configuring-playbook-element-call.md) with [LiveKit Server](./configuring-playbook-livekit-server.md) | [Link](docs/configuring-playbook-livekit-jwt-service.md) |
 
 ### Authentication
 

bin/check-examples-vars-migration-version.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Ensures that the migration validated version in examples/vars.yml
+# matches the expected version in the matrix_playbook_migration role defaults.
+
+set -euo pipefail
+
+defaults_file="roles/custom/matrix_playbook_migration/defaults/main.yml"
+examples_file="examples/vars.yml"
+
+expected_version=$(grep -oP '^matrix_playbook_migration_expected_version:\s*"?\K[^"]+' "$defaults_file")
+examples_version=$(grep -oP '^matrix_playbook_migration_validated_version:\s*"?\K[^"]+' "$examples_file")
+
+if [ -z "$expected_version" ]; then
+	echo "ERROR: Could not extract matrix_playbook_migration_expected_version from $defaults_file"
+	exit 1
+fi
+
+if [ -z "$examples_version" ]; then
+	echo "ERROR: Could not extract matrix_playbook_migration_validated_version from $examples_file"
+	exit 1
+fi
+
+if [ "$expected_version" != "$examples_version" ]; then
+	echo "ERROR: Migration version mismatch!"
+	echo "  $defaults_file has expected version: $expected_version"
+	echo "  $examples_file has validated version: $examples_version"
+	echo ""
+	echo "Please update $examples_file to match."
+	exit 1
+fi

docs/configuring-playbook-bot-baibot.md

@@ -39,16 +39,35 @@ Depending on your current `vars.yml` file and desired configuration, **you may r
 
 To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
+Authentication can be configured in one of two mutually-exclusive ways:
+
+- **Password authentication** (`matrix_bot_baibot_config_user_password`) - recommended for most playbook-managed setups, because it integrates with automatic user creation flow used by the playbook, and auto-creates the bot account
+- **Access-token authentication** (`matrix_bot_baibot_config_user_access_token` + `matrix_bot_baibot_config_user_device_id`) - useful for specific [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md)/OIDC setups where password authentication is not available or not desired
+
+Even when [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) is enabled, password authentication is still typically the best fit for baibot if you're using a playbook-managed bot account.
+
+For upstream details, see baibot's [🔐 Authentication](https://github.com/etkecc/baibot/blob/main/docs/configuration/authentication.md) documentation.
+
 ```yaml
 matrix_bot_baibot_enabled: true
 
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_baibot_config_user_mxid_localpart: baibot
 
+# Authentication mode (choose exactly one):
+#
+# 1) Password authentication (recommended for most setups)
 # Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
 # If you'd like to change this password subsequently, see the details below.
 matrix_bot_baibot_config_user_password: 'PASSWORD_FOR_THE_BOT'
 
+# 2) Access-token authentication (for MAS/OIDC-enabled homeservers)
+# matrix_bot_baibot_config_user_access_token: 'YOUR_MAS_COMPATIBILITY_TOKEN_HERE'
+# matrix_bot_baibot_config_user_device_id: 'BAIBOT'
+#
+# You can generate a compatibility token for MAS with:
+# mas-cli manage issue-compatibility-token <username> [device_id]
+
 # An optional passphrase to use for backing up and recovering the bot's encryption keys.
 # You can create one with a command like `pwgen -s 64 1`.
 #
@@ -387,13 +406,15 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 **Notes**:
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account when password authentication is used.
+
+- If you're using access-token authentication, the bot account must already exist and the configured token + device ID must match that account. This mode is mainly for MAS/OIDC setups where password-based bot login is not suitable.
 
 - The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
   `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
-- If you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password.
+- If you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password. (This note applies to password authentication mode.)
 
 ## Usage
 

docs/configuring-playbook-client-sable.md

@@ -0,0 +1,71 @@
+<!--
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 - 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Sable (optional)
+
+The playbook can install and configure the [Sable](https://github.com/7w1/sable) Matrix web client for you.
+
+Sable is a web client focusing primarily on simple, elegant and secure interface. It can be installed alongside or instead of [Element Web](./configuring-playbook-client-element-web.md), [Cinny](./configuring-playbook-client-cinny.md) and others.
+
+## Adjusting DNS records
+
+By default, this playbook installs Sable on the `sable.` subdomain (`sable.example.com`) and requires you to create a CNAME record for `sable`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+## Adjusting the playbook configuration
+
+To enable Sable, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+sable_enabled: true
+```
+
+### Adjusting the Sable URL (optional)
+
+By tweaking the `sable_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Switch to a different domain (`app.example.com`) than the default one (`sable.example.com`)
+sable_hostname: "app.{{ matrix_domain }}"
+
+# Expose under the /sable subpath
+# sable_path_prefix: /sable
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the Sable domain to the Matrix server.
+
+**Note**: while there is a `sable_path_prefix` variable for changing the path where Sable is served, overriding it is [not possible](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Sable requires an application rebuild (with a tweaked build config) to be functional under a custom path. You'd need to serve Sable at a dedicated subdomain.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/galaxy/sable/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/galaxy/sable/templates/config.json.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `sable_configuration_extension_json` variable
+
+## Installing
+
+After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-client-sable`.

docs/configuring-playbook-email.md

@@ -17,6 +17,16 @@ The [Ansible role for exim-relay](https://github.com/mother-of-all-self-hosting/
 - 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay/blob/main/docs/configuring-exim-relay.md) online
 - 📁 `roles/galaxy/exim_relay/docs/configuring-exim-relay.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
 
+## Why use exim-relay?
+
+**Benefits of using exim-relay** instead of configuring SMTP directly in each service:
+
+1. **Final delivery capability**: Can deliver emails directly if you don't have an SMTP server
+
+2. **Centralized configuration**: Configure your upstream SMTP server once in exim-relay, then point all services ([Synapse](configuring-playbook-synapse.md), [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), etc.) there—no need to configure SMTP in each component
+
+3. **Local spooling**: Stores messages locally and retries delivery if your upstream SMTP server is temporarily unavailable
+
 ## Firewall settings
 
 No matter whether you send email directly (the default) or you relay email through another host, you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).

docs/configuring-playbook-livekit-server.md

@@ -15,7 +15,7 @@ LiveKit Server is an open source project that provides scalable, multi-user conf
 
 The [Ansible role for LiveKit Server](https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For details about configuring LiveKit Server, you can check them via:
 - 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server/blob/main/docs/configuring-livekit-server.md) online
-- 📁 `roles/galaxy/livekit-server/docs/configuring-livekit-server.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
+- 📁 `roles/galaxy/livekit_server/docs/configuring-livekit-server.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
 
 ## Adjusting firewall rules
 
@@ -29,7 +29,9 @@ To ensure LiveKit Server functions correctly, the following firewall rules and p
 
 - `5350/tcp`: TURN/TCP. Also see the [Limitations](#limitations) section below.
 
-💡 The suggestions above are inspired by the upstream [Ports and Firewall](https://docs.livekit.io/home/self-hosting/ports-firewall/) documentation based on how LiveKit is configured in the playbook. If you've using custom configuration for the LiveKit Server role, you may need to adjust the firewall rules accordingly.
+- `30000-30020/udp`: TURN relay range used by LiveKit's embedded TURN server.
+
+💡 The suggestions above are inspired by the upstream [Ports and Firewall](https://docs.livekit.io/home/self-hosting/ports-firewall/) documentation based on how LiveKit is configured in the playbook. If you're using custom configuration for the LiveKit Server role, you may need to adjust firewall rules accordingly.
 
 ## TURN TLS handling
 

docs/configuring-playbook-matrix-rtc.md

@@ -17,8 +17,8 @@ The Matrix RTC stack is a set of supporting components ([LiveKit Server](configu
 
 - A [Synapse](configuring-playbook-synapse.md) homeserver (see the warning below)
 - Various experimental features for the Synapse homeserver which Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) (automatically done when Element Call is enabled)
-- A [LiveKit Server](configuring-playbook-livekit-server.md) (automatically installed when [Element Call or the Matrix RTC stack is enabled](#decide-between-element-call-vs-just-the-matrix-rtc-stack))
+- A [LiveKit Server](configuring-playbook-livekit-server.md) (automatically installed when [Element Call or the Matrix RTC stack is enabled](configuring-playbook-element-call.md#decide-between-element-call-vs-just-the-matrix-rtc-stack))
-- The [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (automatically installed when [Element Call or the Matrix RTC stack is enabled](#decide-between-element-call-vs-just-the-matrix-rtc-stack))
+- The [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (automatically installed when [Element Call or the Matrix RTC stack is enabled](configuring-playbook-element-call.md#decide-between-element-call-vs-just-the-matrix-rtc-stack))
 - A client compatible with Element Call. As of 2025-03-15, that's just [Element Web](configuring-playbook-client-element-web.md) and the Element X mobile clients (iOS and Android).
 
 > [!WARNING]

docs/configuring-playbook-prometheus-grafana.md

@@ -178,11 +178,11 @@ Name | Description
 `matrix_metrics_exposure_http_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.example.com/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials).
 `matrix_metrics_exposure_http_basic_auth_users`|Set this to the Basic Authentication credentials (raw `htpasswd` file content) used to protect `/metrics/*`. This htpasswd-file needs to be generated with the `htpasswd` tool and can include multiple username/password pairs.
 `prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network).
-`prometheus_node_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.example.com/metrics/node-exporter`.
+`prometheus_node_exporter_container_labels_metrics_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.example.com/metrics/node-exporter`.
 `prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](#enable-metrics-and-graphs-for-postgres-optional) (locally, on the container network).
-`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](#enable-metrics-and-graphs-for-postgres-optional) metrics on `https://matrix.example.com/metrics/postgres-exporter`.
+`prometheus_postgres_exporter_container_labels_metrics_enabled`|Set this to `true` to expose the [Postgres exporter](#enable-metrics-and-graphs-for-postgres-optional) metrics on `https://matrix.example.com/metrics/postgres-exporter`.
 `prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [prometheus-nginxlog-exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) (locally, on the container network).
-`prometheus_nginxlog_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [prometheus-nginxlog-exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) metrics on `https://matrix.example.com/metrics/nginxlog`.
+`prometheus_nginxlog_exporter_container_labels_metrics_enabled`|Set this to `true` to expose the [prometheus-nginxlog-exporter](#enable-metrics-and-graphs-for-nginx-logs-optional) metrics on `https://matrix.example.com/metrics/nginxlog`.
 
 ### Expose metrics of other services/roles
 

docs/configuring-playbook-synapse-s3-storage-provider.md

@@ -177,6 +177,8 @@ By default, we periodically ensure that all local files are uploaded to S3 and a
 - … invoked via the `matrix-synapse-s3-storage-provider-migrate.service` service
 - … triggered by the `matrix-synapse-s3-storage-provider-migrate.timer` timer, every day at 05:00
 
+The same `migrate` script also prunes empty directories in the local media repository (`remote_content` and `remote_thumbnail`) after upload/delete operations.
+
 So… you don't need to perform any maintenance yourself.
 
 The schedule is defined in the format of systemd timer calendar. To edit the schedule, add the following configuration to your `vars.yml` file (adapt to your needs):

docs/configuring-playbook-synapse.md

@@ -76,7 +76,7 @@ The only thing you **cannot** do is mix [generic workers](#generic-workers) and
 
 When Synapse workers are enabled, the integrated [Postgres database is tuned](maintenance-postgres.md#tuning-postgresql), so that the maximum number of Postgres connections are increased from `200` to `500`. If you need to decrease or increase the number of maximum Postgres connections further, use the `postgres_max_connections` variable.
 
-A separate Ansible role (`matrix-synapse-reverse-proxy-companion`) and component handles load-balancing for workers. This role/component is automatically enabled when you enable workers. Make sure to use the `setup-all` tag (not `install-all`!) during the playbook's [installation](./installing.md) process, especially if you're disabling workers, so that components may be installed/uninstalled correctly.
+The `matrix-synapse` role also manages the `matrix-synapse-reverse-proxy-companion` component for load-balancing with workers. This component is automatically enabled when you enable workers. Make sure to use the `setup-all` tag (not `install-all`!) during the playbook's [installation](./installing.md) process, especially if you're disabling workers, so that components may be installed/uninstalled correctly.
 
 In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/element-hq/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.
 

docs/configuring-playbook-turn.md

@@ -25,7 +25,7 @@ and configure its IP-related settings in the section below.
 
 If you'd like coturn to stay disabled even when Jitsi is enabled, or if you prefer to use an external TURN provider, see [disabling coturn](#disabling-coturn) section below.
 
-When Coturn is not enabled, homeservers (like Synapse) would not point to TURN servers and *legacy* audio/video call functionality may fail. If you're using [Matrix RTC](configuring-playbook-rtc.md) (for [Element Call](configuring-playbook-element-call.md)), you likely don't have a need to enable coturn.
+When Coturn is not enabled, homeservers (like Synapse) would not point to TURN servers and *legacy* audio/video call functionality may fail. If you're using [Matrix RTC](configuring-playbook-matrix-rtc.md) (for [Element Call](configuring-playbook-element-call.md)), you likely don't have a need to enable coturn.
 
 ## Adjusting firewall rules
 
@@ -37,6 +37,8 @@ To ensure Coturn functions correctly, the following firewall rules and port forw
 - `5349/udp`: TURN over UDP
 - `49152-49172/udp`: TURN/UDP relay range
 
+If LiveKit's embedded TURN is enabled at the same time (for MatrixRTC/Element Call), keep the Coturn relay range distinct from LiveKit's relay range (`livekit_server_config_turn_relay_range_start`/`livekit_server_config_turn_relay_range_end`).
+
 💡 Docker configures the server's internal firewall for you. In most cases, you don't need to do anything special on the host itself.
 
 ## Adjusting the playbook configuration

docs/configuring-playbook.md

@@ -87,6 +87,8 @@ Web clients for Matrix that you can host on your own domains.
 
 - [Setting up Cinny](configuring-playbook-client-cinny.md), if you've enabled [Cinny](https://github.com/ajbura/cinny), a web client focusing primarily on simple, elegant and secure interface
 
+- [Setting up Sable](configuring-playbook-client-sable.md), if you've enabled [Sable](https://github.com/7w1/sable), a web client focusing primarily on simple, elegant and secure interface
+
 - [Setting up SchildiChat Web](configuring-playbook-client-schildichat-web.md), if you've enabled [SchildiChat Web](https://schildi.chat/), a web client based on [Element Web](https://element.io/) with some extras and tweaks
 
 - [Setting up FluffyChat Web](configuring-playbook-client-fluffychat-web.md), if you've enabled [FluffyChat Web](https://github.com/krille-chan/fluffychat), a cute cross-platform messenger (web, iOS, Android) for Matrix written in [Flutter](https://flutter.dev/)

docs/container-images.md

@@ -39,6 +39,7 @@ Web clients for Matrix that you can host on your own domains.
 | [Element Web](configuring-playbook-client-element-web.md) | [vectorim/element-web](https://hub.docker.com/r/vectorim/element-web/) | ✅ | Default Matrix web client, configured to connect to your own Synapse server |
 | [Hydrogen](configuring-playbook-client-hydrogen.md) | [element-hq/hydrogen-web](https://ghcr.io/element-hq/hydrogen-web) | ❌ | Lightweight Matrix client with legacy and mobile browser support |
 | [Cinny](configuring-playbook-client-cinny.md) | [ajbura/cinny](https://hub.docker.com/r/ajbura/cinny) | ❌ | Simple, elegant and secure web client |
+| [Sable](configuring-playbook-client-sable.md) | [7w1/sable](https://ghcr.io/7w1/sable) | ❌ | Simple, elegant and secure web client |
 | [SchildiChat Web](configuring-playbook-client-schildichat-web.md) | [etke.cc/schildichat-web](https://ghcr.io/etkecc/schildichat-web) | ❌ | Based on Element Web, with a more traditional instant messaging experience |
 
 ## Server Components

docs/self-building.md

@@ -30,6 +30,7 @@ Possibly outdated list of roles where self-building the Docker image is currentl
 - `matrix-client-element`
 - `hydrogen`
 - `cinny`
+- `sable`
 - `matrix-registration`
 - `coturn`
 - `matrix-corporal`

examples/vars.yml

@@ -1,4 +1,9 @@
 ---
+# This variable acknowledges that you've reviewed breaking changes up to this version.
+# The playbook will fail if this is outdated, guiding you through what changed.
+# See the changelog: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md
+matrix_playbook_migration_validated_version: v2026.03.23.0
+
 # The bare domain name which represents your Matrix identity.
 # Matrix user IDs for your server will be of the form (`@alice:example.com`).
 #

flake.nix

@@ -19,6 +19,7 @@
           devShells.default = mkShell {
             buildInputs = [
               just
+              mise
               ansible
             ];
             shellHook = ''

group_vars/matrix_servers

@@ -278,7 +278,7 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': (backup_borg_identifier + '.timer'),
       'priority': 5000,
-      'restart_necessary': true,
+      'restart_necessary': (backup_borg_restart_necessary | bool),
       'groups': ['matrix', 'backup', 'borg'],
     }] if backup_borg_enabled else [])
     +
@@ -383,14 +383,14 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': 'matrix-appservice-kakaotalk.service',
       'priority': 2000,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_appservice_kakaotalk_restart_necessary | bool),
       'groups': ['matrix', 'bridges', 'appservice-kakaotalk'],
     }] if matrix_appservice_kakaotalk_enabled else [])
     +
     ([{
       'name': 'matrix-appservice-kakaotalk-node.service',
       'priority': 1900,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_appservice_kakaotalk_restart_necessary | bool),
       'groups': ['matrix', 'bridges', 'appservice-kakaotalk', 'appservice-kakaotalk-node'],
     }] if matrix_appservice_kakaotalk_enabled else [])
     +
@@ -404,14 +404,14 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': 'matrix-wechat.service',
       'priority': 2000,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_wechat_restart_necessary | bool),
       'groups': ['matrix', 'bridges', 'wechat'],
     }] if matrix_wechat_enabled else [])
     +
     ([{
       'name': 'matrix-wechat-agent.service',
       'priority': 2000,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_wechat_restart_necessary | bool),
       'groups': ['matrix', 'bridges', 'wechat'],
     }] if matrix_wechat_enabled else [])
     +
@@ -576,6 +576,13 @@ devture_systemd_service_manager_services_list_auto: |
       'groups': ['matrix', 'clients', 'cinny', 'client-cinny'],
     }] if cinny_enabled else [])
     +
+    ([{
+      'name': (sable_identifier + '.service'),
+      'priority': 2000,
+      'restart_necessary': (sable_restart_necessary | bool),
+      'groups': ['matrix', 'clients', 'sable', 'client-sable'],
+    }] if sable_enabled else [])
+    +
     ([{
       'name': 'matrix-client-element.service',
       'priority': 2000,
@@ -597,6 +604,13 @@ devture_systemd_service_manager_services_list_auto: |
       'groups': ['matrix', 'clients', 'schildichat', 'client-schildichat'],
     }] if matrix_client_schildichat_enabled else [])
     +
+    ([{
+      'name': 'matrix-client-commet.service',
+      'priority': 2000,
+      'restart_necessary': (matrix_client_commet_restart_necessary | bool),
+      'groups': ['matrix', 'clients', 'commet', 'client-commet'],
+    }] if matrix_client_commet_enabled else [])
+    +
     ([{
       'name': 'matrix-client-fluffychat.service',
       'priority': 2000,
@@ -607,7 +621,12 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': ('matrix-' + matrix_homeserver_implementation + '.service'),
       'priority': matrix_homeserver_systemd_service_manager_priority,
-      'restart_necessary': true,
+      'restart_necessary': (
+        (matrix_conduit_restart_necessary | bool) if matrix_homeserver_implementation == 'conduit'
+        else (matrix_continuwuity_restart_necessary | bool) if matrix_homeserver_implementation == 'continuwuity'
+        else (matrix_dendrite_restart_necessary | bool) if matrix_homeserver_implementation == 'dendrite'
+        else true
+      ),
       'groups': ['matrix', 'homeservers', matrix_homeserver_implementation],
     }] if matrix_homeserver_enabled else [])
     +
@@ -670,28 +689,28 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': (jitsi_identifier + '-web.service'),
       'priority': 4200,
-      'restart_necessary': true,
+      'restart_necessary': (jitsi_web_restart_necessary | bool),
       'groups': ['matrix', 'jitsi', 'jitsi-web'],
     }] if jitsi_enabled else [])
     +
     ([{
       'name': (jitsi_identifier + '-prosody.service'),
       'priority': 4000,
-      'restart_necessary': true,
+      'restart_necessary': (jitsi_prosody_restart_necessary | bool),
       'groups': ['matrix', 'jitsi', 'jitsi-prosody'],
     }] if jitsi_enabled else [])
     +
     ([{
       'name': (jitsi_identifier + '-jicofo.service'),
       'priority': 4100,
-      'restart_necessary': true,
+      'restart_necessary': (jitsi_jicofo_restart_necessary | bool),
       'groups': ['matrix', 'jitsi', 'jitsi-jicofo'],
     }] if jitsi_enabled else [])
     +
     ([{
       'name': (jitsi_identifier + '-jvb.service'),
       'priority': 4100,
-      'restart_necessary': true,
+      'restart_necessary': (jitsi_jvb_restart_necessary | bool),
       'groups': ['matrix', 'jitsi', 'jitsi-jvb'],
     }] if jitsi_enabled else [])
     +
@@ -705,7 +724,7 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': (matrix_media_repo_identifier + '.service'),
       'priority': 4000,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_media_repo_restart_necessary | bool),
       'groups': ['matrix', 'matrix-media-repo'],
     }] if matrix_media_repo_enabled else [])
     +
@@ -789,7 +808,7 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': 'matrix-element-call.service',
       'priority': 4000,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_element_call_restart_necessary | bool),
       'groups': ['matrix', 'element-call'],
     }] if matrix_element_call_enabled else [])
     +
@@ -824,14 +843,14 @@ devture_systemd_service_manager_services_list_auto: |
     ([{
       'name': 'matrix-goofys.service',
       'priority': 800,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_goofys_restart_necessary | bool),
       'groups': ['matrix', 'goofys'],
     }] if (matrix_synapse_enabled and matrix_s3_media_store_enabled) else [])
     +
     ([{
       'name': 'matrix-synapse-s3-storage-provider-migrate.timer',
       'priority': 5000,
-      'restart_necessary': true,
+      'restart_necessary': (matrix_synapse_s3_storage_provider_restart_necessary | bool),
       'groups': ['matrix'],
     }] if (matrix_synapse_enabled and matrix_synapse_ext_synapse_s3_storage_provider_enabled) else [])
     +
@@ -1065,9 +1084,18 @@ matrix_authentication_service_enabled: false
 matrix_authentication_service_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_authentication_service_path_prefix: /auth
 
-matrix_authentication_service_config_database_host: "{{ postgres_connection_hostname if postgres_enabled else '' }}"
+matrix_playbook_matrix_authentication_service_uses_managed_postgres: "{{ postgres_enabled }}"
+
+matrix_authentication_service_config_database_host: "{{ matrix_authentication_service_config_database_socket_path if matrix_authentication_service_config_database_socket_enabled else (postgres_connection_hostname if matrix_playbook_matrix_authentication_service_uses_managed_postgres else '') }}"
 matrix_authentication_service_config_database_password: "{{ (matrix_homeserver_generic_secret_key + ':mas.db') | hash('sha512') | to_uuid }}"
 
+# unix socket connection
+matrix_authentication_service_config_database_socket_enabled: "{{ matrix_playbook_matrix_authentication_service_uses_managed_postgres and postgres_container_unix_socket_enabled }}"
+# path to the Postgres socket's parent dir inside the MAS container
+matrix_authentication_service_config_database_socket_path: "{{ '/run-postgres' if matrix_playbook_matrix_authentication_service_uses_managed_postgres else '' }}"
+# path to the Postgres socket on the host
+matrix_authentication_service_config_database_socket_path_host: "{{ postgres_run_path if matrix_playbook_matrix_authentication_service_uses_managed_postgres else '' }}"
+
 matrix_authentication_service_config_matrix_homeserver: "{{ matrix_domain }}"
 matrix_authentication_service_config_matrix_secret: "{{ (matrix_homeserver_generic_secret_key + ':mas.hs.secret') | hash('sha512') | to_uuid }}"
 matrix_authentication_service_config_matrix_endpoint: "{{ matrix_homeserver_container_url }}"
@@ -1100,7 +1128,7 @@ matrix_authentication_service_container_network: "{{ matrix_homeserver_container
 matrix_authentication_service_container_additional_networks_auto: |-
   {{
     (
-      ([postgres_container_network] if postgres_enabled and matrix_authentication_service_config_database_host == postgres_connection_hostname else [])
+      ([postgres_container_network] if (matrix_playbook_matrix_authentication_service_uses_managed_postgres and not matrix_authentication_service_config_database_socket_enabled) else [])
       +
       ([exim_relay_container_network] if (exim_relay_enabled and matrix_authentication_service_config_email_transport == 'smtp' and matrix_authentication_service_config_email_hostname == exim_relay_identifier and matrix_authentication_service_container_network != exim_relay_container_network) else [])
       +
@@ -1125,7 +1153,7 @@ matrix_authentication_service_container_labels_internal_compatibility_layer_entr
 # We'll put our dependency on the homeserver as a "want", rather than a requirement.
 matrix_authentication_service_systemd_required_services_list_auto: |
   {{
-    ([postgres_identifier ~ '.service'] if postgres_enabled and matrix_authentication_service_config_database_host == postgres_connection_hostname else [])
+    ([postgres_identifier ~ '.service'] if matrix_playbook_matrix_authentication_service_uses_managed_postgres else [])
   }}
 
 # See more information about this homeserver "want" in the comment for `matrix_authentication_service_systemd_required_services_list_auto` above.
@@ -1136,9 +1164,12 @@ matrix_authentication_service_systemd_wanted_services_list_auto: |
     ([exim_relay_identifier ~ '.service'] if (exim_relay_enabled and matrix_authentication_service_config_email_transport == 'smtp' and matrix_authentication_service_config_email_hostname == exim_relay_identifier and matrix_authentication_service_container_network != exim_relay_container_network) else [])
   }}
 
-matrix_authentication_service_syn2mas_container_network: "{{ postgres_container_network if postgres_enabled and matrix_authentication_service_config_database_host == postgres_connection_hostname else matrix_authentication_service_container_network }}"
+matrix_authentication_service_syn2mas_container_network: "{{ postgres_container_network if (matrix_playbook_matrix_authentication_service_uses_managed_postgres and not matrix_authentication_service_config_database_socket_enabled) else matrix_authentication_service_container_network }}"
 
 matrix_authentication_service_syn2mas_synapse_homeserver_config_path: "{{ matrix_synapse_config_dir_path + '/homeserver.yaml' if matrix_synapse_enabled else '' }}"
+matrix_authentication_service_syn2mas_synapse_database_socket_enabled: "{{ matrix_synapse_database_socket_enabled if matrix_synapse_enabled else false }}"
+matrix_authentication_service_syn2mas_synapse_database_socket_path: "{{ matrix_synapse_database_socket_path if matrix_synapse_enabled else '' }}"
+matrix_authentication_service_syn2mas_synapse_database_socket_path_host: "{{ matrix_synapse_database_socket_path_host if matrix_synapse_enabled else '' }}"
 
 ######################################################################
 #
@@ -3257,6 +3288,9 @@ matrix_pantalaimon_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }
 ######################################################################
 
 backup_borg_enabled: false
+backup_borg_mariadb_enabled: false
+backup_borg_mysql_enabled: false
+backup_borg_mongodb_enabled: false
 
 backup_borg_identifier: matrix-backup-borg
 backup_borg_storage_archive_name_format: matrix-{now:%Y-%m-%d-%H%M%S}
@@ -3586,6 +3620,9 @@ etherpad_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
 
 etherpad_base_path: "{{ matrix_base_data_path }}/etherpad"
 
+etherpad_uid: "{{ matrix_user_uid }}"
+etherpad_gid: "{{ matrix_user_gid }}"
+
 etherpad_framing_enabled: "{{ jitsi_enabled }}"
 
 etherpad_hostname: "{{ matrix_server_fqn_etherpad }}"
@@ -3980,7 +4017,7 @@ postgres_managed_databases_auto: |
       'name': matrix_synapse_database_database,
       'username': matrix_synapse_database_user,
       'password': matrix_synapse_database_password,
-    }] if (matrix_synapse_enabled and matrix_synapse_database_host == postgres_connection_hostname) else [])
+    }] if (matrix_synapse_enabled and matrix_playbook_synapse_uses_managed_postgres) else [])
     +
     ([{
       'name': matrix_dendrite_federation_api_database,
@@ -4024,7 +4061,7 @@ postgres_managed_databases_auto: |
       'name': matrix_authentication_service_config_database_database,
       'username': matrix_authentication_service_config_database_username,
       'password': matrix_authentication_service_config_database_password,
-    }] if (matrix_authentication_service_enabled and matrix_authentication_service_config_database_host == postgres_connection_hostname) else [])
+    }] if (matrix_authentication_service_enabled and matrix_playbook_matrix_authentication_service_uses_managed_postgres) else [])
     +
     ([{
       'name': matrix_bot_matrix_reminder_bot_database_name,
@@ -4385,6 +4422,7 @@ matrix_client_element_container_additional_networks: "{{ [matrix_playbook_revers
 
 matrix_client_element_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
 matrix_client_element_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+
 matrix_client_element_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
 matrix_client_element_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
 
@@ -4427,6 +4465,36 @@ matrix_client_element_element_call_url: "{{ matrix_element_call_public_url if ma
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-client-commet
+#
+######################################################################
+
+matrix_client_commet_enabled: false
+
+matrix_client_commet_hostname: "commet.{{ matrix_domain }}"
+
+matrix_client_commet_container_http_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '8766') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
+
+matrix_client_commet_container_network: "{{ matrix_addons_container_network }}"
+
+matrix_client_commet_container_additional_networks: "{{ [matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_client_commet_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [] }}"
+
+matrix_client_commet_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_client_commet_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_client_commet_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+matrix_client_commet_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+matrix_client_commet_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_client_commet_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"
+
+######################################################################
+#
+# /matrix-client-commet
+#
+######################################################################
+
 ######################################################################
 #
 # hydrogen
@@ -4523,6 +4591,54 @@ cinny_hostname: "{{ matrix_server_fqn_cinny }}"
 #
 ######################################################################
 
+######################################################################
+#
+# sable
+#
+######################################################################
+
+sable_enabled: false
+
+sable_identifier: matrix-client-sable
+
+sable_uid: "{{ matrix_user_uid }}"
+sable_gid: "{{ matrix_user_gid }}"
+
+sable_container_image_registry_prefix: "{{ 'localhost/' if sable_container_image_self_build else sable_container_image_registry_prefix_upstream }}"
+sable_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else sable_container_image_registry_prefix_upstream_default }}"
+
+sable_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
+
+sable_container_http_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '8771') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
+
+sable_container_network: "{{ matrix_addons_container_network }}"
+
+sable_container_additional_networks: "{{ [matrix_playbook_reverse_proxyable_services_additional_network] if (sable_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [] }}"
+
+sable_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+sable_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+sable_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+sable_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+sable_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+sable_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"
+
+sable_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
+
+sable_default_hs_url: "{{ matrix_homeserver_url }}"
+
+sable_self_check_validate_certificates: "{{ matrix_playbook_ssl_enabled }}"
+
+sable_base_path: "{{ matrix_base_data_path }}/client-sable"
+
+sable_hostname: "{{ matrix_server_fqn_sable }}"
+
+######################################################################
+#
+# /sable
+#
+######################################################################
+
 ######################################################################
 #
 # matrix-client-schildichat
@@ -4649,9 +4765,9 @@ matrix_synapse_container_additional_networks_auto: |
     (
       ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_synapse_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network else [])
       +
-      ([postgres_container_network] if (postgres_enabled and postgres_container_network != matrix_synapse_container_network and matrix_synapse_database_host == postgres_connection_hostname) else [])
+      ([postgres_container_network] if (matrix_playbook_synapse_uses_managed_postgres and (not matrix_synapse_database_socket_enabled) and postgres_container_network != matrix_synapse_container_network) else [])
       +
-      ([valkey_container_network] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == valkey_identifier else [])
+      ([valkey_container_network] if (matrix_playbook_synapse_uses_managed_valkey and (not matrix_synapse_redis_path_enabled) and valkey_container_network != matrix_synapse_container_network) else [])
       +
       ([exim_relay_container_network] if (exim_relay_enabled and matrix_synapse_email_enabled and matrix_synapse_email_smtp_host == exim_relay_identifier and matrix_synapse_container_network != exim_relay_container_network) else [])
       +
@@ -4688,12 +4804,24 @@ matrix_synapse_container_labels_public_metrics_middleware_basic_auth_users: "{{
 matrix_synapse_container_labels_internal_client_api_enabled: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_enabled }}"
 matrix_synapse_container_labels_internal_client_api_traefik_entrypoints: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_name }}"
 
+# Playbook-level Synapse topology wiring helpers.
+matrix_playbook_synapse_uses_managed_postgres: "{{ postgres_enabled }}"
+matrix_playbook_synapse_uses_managed_valkey: "{{ matrix_synapse_redis_enabled and valkey_enabled }}"
+matrix_playbook_synapse_auto_compressor_uses_managed_postgres: "{{ matrix_playbook_synapse_uses_managed_postgres and matrix_synapse_auto_compressor_database_hostname == matrix_synapse_database_host }}"
+
 # For exposing the Synapse worker (and metrics) ports to the local host.
 matrix_synapse_workers_container_host_bind_address: "{{ matrix_playbook_service_host_bind_interface_prefix[0:-1] if (matrix_synapse_workers_enabled and matrix_playbook_service_host_bind_interface_prefix) else '' }}"
 
-matrix_synapse_database_host: "{{ postgres_connection_hostname if postgres_enabled else '' }}"
+matrix_synapse_database_host: "{{ postgres_connection_hostname if matrix_playbook_synapse_uses_managed_postgres else '' }}"
 matrix_synapse_database_password: "{{ (matrix_homeserver_generic_secret_key + ':synapse.db') | hash('sha512') | to_uuid }}"
 
+# unix socket connection
+matrix_synapse_database_socket_enabled: "{{ matrix_playbook_synapse_uses_managed_postgres and postgres_container_unix_socket_enabled }}"
+# path to the Postgres socket's parent dir inside the Synapse container
+matrix_synapse_database_socket_path: "{{ '/run-postgres' if matrix_playbook_synapse_uses_managed_postgres else '' }}"
+# path to the Postgres socket on the host, using Postgres
+matrix_synapse_database_socket_path_host: "{{ postgres_run_path if matrix_playbook_synapse_uses_managed_postgres else '' }}"
+
 matrix_synapse_macaroon_secret_key: "{{ (matrix_homeserver_generic_secret_key + ':synapse.mac') | hash('sha512') | to_uuid }}"
 
 # We do not enable TLS in Synapse by default, since it's handled by Traefik.
@@ -4724,9 +4852,9 @@ matrix_synapse_self_check_validate_certificates: "{{ matrix_playbook_ssl_enabled
 
 matrix_synapse_systemd_required_services_list_auto: |
   {{
-    ([postgres_identifier ~ '.service'] if (postgres_enabled and postgres_container_network != matrix_synapse_container_network and matrix_synapse_database_host == postgres_connection_hostname) else [])
+    ([postgres_identifier ~ '.service'] if (matrix_playbook_synapse_uses_managed_postgres and postgres_container_network != matrix_synapse_container_network) else [])
     +
-    ([valkey_identifier ~ '.service'] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == valkey_identifier else [])
+    ([valkey_identifier ~ '.service'] if matrix_playbook_synapse_uses_managed_valkey else [])
     +
     (['matrix-goofys.service'] if matrix_s3_media_store_enabled else [])
     +
@@ -4742,8 +4870,17 @@ matrix_synapse_systemd_wanted_services_list_auto: |
 
 # Synapse workers (used for parallel load-scaling) need Redis for IPC.
 matrix_synapse_redis_enabled: "{{ valkey_enabled }}"
-matrix_synapse_redis_host: "{{ valkey_identifier if valkey_enabled else '' }}"
+matrix_synapse_redis_host: "{{ valkey_identifier if matrix_playbook_synapse_uses_managed_valkey else '' }}"
-matrix_synapse_redis_password: "{{ valkey_connection_password if valkey_enabled else '' }}"
+matrix_synapse_redis_password: "{{ valkey_connection_password if matrix_playbook_synapse_uses_managed_valkey else '' }}"
+
+# unix socket connection
+matrix_synapse_redis_path_enabled: "{{ matrix_playbook_synapse_uses_managed_valkey }}"
+# path to the Redis socket's parent dir inside the Synapse container
+matrix_synapse_redis_path: "{{ '/run-valkey' if matrix_playbook_synapse_uses_managed_valkey else '' }}"
+# redis socket filename
+matrix_synapse_redis_path_socket: "{{ '/valkey.sock' if matrix_playbook_synapse_uses_managed_valkey else '' }}"
+# path to the Redis socket on the host, using Valkey
+matrix_synapse_redis_path_host: "{{ valkey_run_path if matrix_playbook_synapse_uses_managed_valkey else '' }}"
 
 matrix_synapse_container_extra_arguments_auto: "{{ matrix_homeserver_container_extra_arguments_auto }}"
 matrix_synapse_app_service_config_files_auto: "{{ matrix_homeserver_app_service_config_files_auto }}"
@@ -4788,6 +4925,32 @@ matrix_synapse_register_user_script_matrix_authentication_service_path: "{{ matr
 # so it stays in sync automatically.
 matrix_synapse_systemd_service_post_start_delay_seconds: "{{ (traefik_config_providers_providersThrottleDuration_seconds | int + 1) if matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] else 0 }}"
 
+matrix_synapse_reverse_proxy_companion_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
+matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream_default }}"
+matrix_synapse_reverse_proxy_companion_container_client_api_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '8008') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
+matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '8048') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname: "{{ matrix_server_fqn_matrix }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_entrypoints: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_name }}"
+matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_enabled: "{{ prometheus_nginxlog_exporter_enabled }}"
+matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_server_port: "{{ (prometheus_nginxlog_exporter_identifier | string +':'+ prometheus_nginxlog_exporter_container_syslog_port | string) | default('') }}"
+
+matrix_synapse_reverse_proxy_companion_container_additional_networks_auto: |
+  {{
+    (
+      ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network else [])
+      +
+      ([prometheus_nginxlog_exporter_container_network] if (prometheus_nginxlog_exporter_enabled and prometheus_nginxlog_exporter_container_network != matrix_synapse_reverse_proxy_companion_container_network) else [])
+      +
+      ([] if matrix_homeserver_container_network in ['', matrix_synapse_reverse_proxy_companion_container_network] else [matrix_homeserver_container_network])
+    ) | unique
+  }}
+
 ######################################################################
 #
 # /matrix-synapse
@@ -4813,7 +4976,7 @@ matrix_synapse_auto_compressor_container_image_registry_prefix_upstream: "{{ mat
 
 matrix_synapse_auto_compressor_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
 
-matrix_synapse_auto_compressor_container_network: "{{ (postgres_container_network if (postgres_enabled and matrix_synapse_auto_compressor_database_hostname == matrix_synapse_database_host and matrix_synapse_database_host == postgres_connection_hostname) else 'matrix-synapse-auto-compressor') }}"
+matrix_synapse_auto_compressor_container_network: "{{ (postgres_container_network if matrix_playbook_synapse_auto_compressor_uses_managed_postgres else 'matrix-synapse-auto-compressor') }}"
 
 matrix_synapse_auto_compressor_database_username: "{{ matrix_synapse_database_user if matrix_synapse_enabled else '' }}"
 matrix_synapse_auto_compressor_database_password: "{{ matrix_synapse_database_password if matrix_synapse_enabled else '' }}"
@@ -4823,7 +4986,7 @@ matrix_synapse_auto_compressor_database_name: "{{ matrix_synapse_database_databa
 
 matrix_synapse_auto_compressor_systemd_required_services_list_auto: |
   {{
-    ([postgres_identifier ~ '.service'] if (matrix_synapse_auto_compressor_container_network == postgres_container_network) else [])
+    ([postgres_identifier ~ '.service'] if matrix_playbook_synapse_auto_compressor_uses_managed_postgres else [])
   }}
 
 ######################################################################
@@ -4833,81 +4996,6 @@ matrix_synapse_auto_compressor_systemd_required_services_list_auto: |
 ######################################################################
 
 
-######################################################################
-#
-# matrix-synapse-reverse-proxy-companion
-#
-######################################################################
-
-matrix_synapse_reverse_proxy_companion_enabled: "{{ matrix_synapse_enabled and matrix_synapse_workers_enabled }}"
-
-matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream_default }}"
-
-matrix_synapse_reverse_proxy_companion_container_network: "{{ matrix_synapse_container_network }}"
-
-matrix_synapse_reverse_proxy_companion_container_additional_networks_auto: |
-  {{
-    (
-      ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network else [])
-      +
-      ([prometheus_nginxlog_exporter_container_network] if (prometheus_nginxlog_exporter_enabled and prometheus_nginxlog_exporter_container_network != matrix_synapse_reverse_proxy_companion_container_network) else [])
-      +
-      ([] if matrix_homeserver_container_network in ['', matrix_synapse_reverse_proxy_companion_container_network] else [matrix_homeserver_container_network])
-    ) | unique
-  }}
-
-matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb: "{{ matrix_synapse_max_upload_size_mb }}"
-
-matrix_synapse_reverse_proxy_companion_container_client_api_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '8008') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
-matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '8048') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
-
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname: "{{ matrix_server_fqn_matrix }}"
-
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"
-
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_enabled: "{{ matrix_synapse_container_labels_public_client_synapse_client_api_enabled }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_enabled: "{{ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled }}"
-
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_enabled: "{{ matrix_synapse_container_labels_internal_client_synapse_admin_api_enabled }}"
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_entrypoints: "{{ matrix_playbook_internal_matrix_client_api_traefik_entrypoint_name }}"
-
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_entrypoints: "{{ matrix_synapse_container_labels_public_federation_api_traefik_entrypoints }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_tls: "{{ matrix_synapse_container_labels_public_federation_api_traefik_tls }}"
-
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_enabled: "{{ matrix_synapse_container_labels_internal_client_api_enabled }}"
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_entrypoints: "{{ matrix_synapse_container_labels_internal_client_api_traefik_entrypoints }}"
-
-matrix_synapse_reverse_proxy_companion_synapse_workers_enabled: "{{ matrix_synapse_workers_enabled }}"
-matrix_synapse_reverse_proxy_companion_synapse_workers_list: "{{ matrix_synapse_workers_enabled_list }}"
-matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations: "{{ matrix_synapse_workers_room_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_room_worker_federation_locations: "{{ matrix_synapse_workers_room_worker_federation_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations: "{{ matrix_synapse_workers_sync_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations: "{{ matrix_synapse_workers_client_reader_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_federation_reader_federation_locations: "{{ matrix_synapse_workers_federation_reader_federation_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations: "{{ matrix_synapse_workers_generic_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations: "{{ matrix_synapse_workers_generic_worker_federation_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_typing_stream_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_to_device_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_to_device_stream_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_account_data_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_account_data_stream_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_receipts_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_receipts_stream_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_presence_stream_worker_client_server_endpoints }}"
-matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations: "{{matrix_synapse_workers_media_repository_endpoints|default([]) }}"
-matrix_synapse_reverse_proxy_companion_synapse_user_dir_locations: "{{ matrix_synapse_workers_user_dir_worker_client_server_endpoints|default([]) }}"
-
-matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_enabled: "{{ prometheus_nginxlog_exporter_enabled }}"
-matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_server_port: "{{ (prometheus_nginxlog_exporter_identifier | string +':'+ prometheus_nginxlog_exporter_container_syslog_port | string) | default('') }}"
-
-######################################################################
-#
-# /matrix-synapse-reverse-proxy-companion
-#
-######################################################################
-
 ######################################################################
 #
 # matrix-synapse-admin
@@ -5138,11 +5226,10 @@ prometheus_node_exporter_container_network: "{{ matrix_monitoring_container_netw
 
 prometheus_node_exporter_container_additional_networks_auto: "{{ [matrix_playbook_reverse_proxyable_services_additional_network] if matrix_playbook_reverse_proxyable_services_additional_network else [] }}"
 
-prometheus_node_exporter_container_labels_traefik_enabled: "{{ matrix_metrics_exposure_enabled }}"
+prometheus_node_exporter_container_labels_metrics_enabled: "{{ matrix_metrics_exposure_enabled }}"
-prometheus_node_exporter_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+prometheus_node_exporter_container_labels_metrics_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
-prometheus_node_exporter_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+prometheus_node_exporter_container_labels_metrics_entrypoints: "{{ traefik_entrypoint_primary }}"
-prometheus_node_exporter_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+prometheus_node_exporter_container_labels_metrics_tls_certResolver: "{{ traefik_certResolver_primary }}"
-
 prometheus_node_exporter_container_labels_metrics_middleware_basic_auth_enabled: "{{ matrix_metrics_exposure_http_basic_auth_enabled }}"
 prometheus_node_exporter_container_labels_metrics_middleware_basic_auth_users: "{{ matrix_metrics_exposure_http_basic_auth_users }}"
 
@@ -5178,14 +5265,13 @@ prometheus_postgres_exporter_container_additional_networks: |
   {{
     ([postgres_container_network] if (postgres_enabled and prometheus_postgres_exporter_database_hostname == postgres_connection_hostname and prometheus_postgres_exporter_container_network != postgres_container_network) else [])
     +
-    ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_playbook_reverse_proxyable_services_additional_network and prometheus_postgres_exporter_container_labels_traefik_enabled else [])
+    ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_playbook_reverse_proxyable_services_additional_network and prometheus_postgres_exporter_container_labels_metrics_enabled else [])
   }}
 
-prometheus_postgres_exporter_container_labels_traefik_enabled: "{{ matrix_metrics_exposure_enabled }}"
+prometheus_postgres_exporter_container_labels_metrics_enabled: "{{ matrix_metrics_exposure_enabled }}"
-prometheus_postgres_exporter_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+prometheus_postgres_exporter_container_labels_metrics_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
-prometheus_postgres_exporter_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+prometheus_postgres_exporter_container_labels_metrics_entrypoints: "{{ traefik_entrypoint_primary }}"
-prometheus_postgres_exporter_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+prometheus_postgres_exporter_container_labels_metrics_tls_certResolver: "{{ traefik_certResolver_primary }}"
-
 prometheus_postgres_exporter_container_labels_metrics_middleware_basic_auth_enabled: "{{ matrix_metrics_exposure_http_basic_auth_enabled }}"
 prometheus_postgres_exporter_container_labels_metrics_middleware_basic_auth_users: "{{ matrix_metrics_exposure_http_basic_auth_users }}"
 
@@ -5229,14 +5315,13 @@ prometheus_nginxlog_exporter_container_network_deletion_enabled: false
 
 prometheus_nginxlog_exporter_container_additional_networks_auto: |-
   {{
-    ([matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_playbook_reverse_proxyable_services_additional_network and prometheus_nginxlog_exporter_container_labels_traefik_enabled) else [])
+    ([matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_playbook_reverse_proxyable_services_additional_network and prometheus_nginxlog_exporter_container_labels_metrics_enabled) else [])
   }}
 
-prometheus_nginxlog_exporter_container_labels_traefik_enabled: "{{ matrix_metrics_exposure_enabled }}"
+prometheus_nginxlog_exporter_container_labels_metrics_enabled: "{{ matrix_metrics_exposure_enabled }}"
-prometheus_nginxlog_exporter_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+prometheus_nginxlog_exporter_container_labels_metrics_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
-prometheus_nginxlog_exporter_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+prometheus_nginxlog_exporter_container_labels_metrics_entrypoints: "{{ traefik_entrypoint_primary }}"
-prometheus_nginxlog_exporter_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+prometheus_nginxlog_exporter_container_labels_metrics_tls_certResolver: "{{ traefik_certResolver_primary }}"
-
 prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_enabled: "{{ matrix_metrics_exposure_http_basic_auth_enabled }}"
 prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_users: "{{ matrix_metrics_exposure_http_basic_auth_users }}"
 
@@ -5731,7 +5816,7 @@ matrix_user_creator_users_auto: |
       'username': matrix_bot_baibot_config_user_mxid_localpart,
       'initial_password': matrix_bot_baibot_config_user_password,
       'initial_type': 'bot',
-    }] if matrix_bot_baibot_enabled else [])
+    }] if matrix_bot_baibot_enabled and ((matrix_bot_baibot_config_user_password | default('', true) | string | length) > 0) else [])
     +
     ([{
       'username': matrix_bot_matrix_reminder_bot_matrix_user_id_localpart,
@@ -5814,7 +5899,10 @@ matrix_user_verification_service_container_http_host_bind_port: "{{  '' if (jits
 # URL exposed in the docker network
 matrix_user_verification_service_container_url: "http://{{  matrix_user_verification_service_container_name }}:3000"
 
-matrix_user_verification_service_uvs_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+# Using `matrix_addons_homeserver_client_api_url` would not work here,
+# because `matrix-traefik:8008` (matrix-internal-client-api) does not expose any `/_synapse` paths.
+# UVS accesses `/_synapse/admin/v1/rooms` API to check room membership.
+matrix_user_verification_service_uvs_homeserver_url: "{{ matrix_homeserver_container_url }}"
 
 # We connect via the container network (private IPs), so we need to disable IP checks
 matrix_user_verification_service_uvs_disable_ip_blacklist: "{{ matrix_synapse_enabled }}"

i18n/requirements.txt

@@ -1,13 +1,13 @@
 alabaster==1.0.0
 babel==2.18.0
 certifi==2026.2.25
-charset-normalizer==3.4.4
+charset-normalizer==3.4.6
 click==8.3.1
 docutils==0.22.4
 idna==3.11
-imagesize==1.4.1
+imagesize==2.0.0
 Jinja2==3.1.6
-linkify-it-py==2.0.3
+linkify-it-py==2.1.0
 markdown-it-py==4.0.0
 MarkupSafe==3.0.3
 mdit-py-plugins==0.5.0
@@ -17,17 +17,17 @@ packaging==26.0
 Pygments==2.19.2
 PyYAML==6.0.3
 requests==2.32.5
-setuptools==82.0.0
+setuptools==82.0.1
 snowballstemmer==3.0.1
 Sphinx==9.1.0
 sphinx-intl==2.3.2
-sphinx-markdown-builder==0.6.9
+sphinx-markdown-builder==0.6.10
 sphinxcontrib-applehelp==2.0.0
 sphinxcontrib-devhelp==2.0.0
 sphinxcontrib-htmlhelp==2.1.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0
-tabulate==0.9.0
+tabulate==0.10.0
-uc-micro-py==1.0.3
+uc-micro-py==2.0.0
 urllib3==2.6.3

justfile

@@ -4,6 +4,11 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# mise (dev tool version manager)
+mise_data_dir := env("MISE_DATA_DIR", justfile_directory() / "var/mise")
+mise_trusted_config_paths := justfile_directory() / "mise.toml"
+prek_home := env("PREK_HOME", justfile_directory() / "var/prek")
+
 # Shows help
 default:
     @{{ just_executable() }} --list --justfile "{{ justfile() }}"
@@ -39,9 +44,39 @@ update-playbook-only:
     @git pull -q
     @-git stash pop -q
 
-# Runs ansible-lint against all roles in the playbook
+# Invokes mise with the project-local data directory
-lint:
+mise *args: _ensure_mise_data_directory
-    ansible-lint
+    #!/bin/sh
+    export MISE_DATA_DIR="{{ mise_data_dir }}"
+    export MISE_TRUSTED_CONFIG_PATHS="{{ mise_trusted_config_paths }}"
+    export MISE_YES=1
+    export PREK_HOME="{{ prek_home }}"
+    mise {{ args }}
+
+# Runs prek (pre-commit hooks manager) with the given arguments
+prek *args: _ensure_mise_tools_installed
+    @{{ just_executable() }} --justfile "{{ justfile() }}" mise exec -- prek {{ args }}
+
+# Runs pre-commit hooks on staged files
+prek-run-on-staged *args: _ensure_mise_tools_installed
+    @{{ just_executable() }} --justfile "{{ justfile() }}" prek run {{ args }}
+
+# Runs pre-commit hooks on all files
+prek-run-on-all *args: _ensure_mise_tools_installed
+    @{{ just_executable() }} --justfile "{{ justfile() }}" prek run --all-files {{ args }}
+
+# Installs the git pre-commit hook
+prek-install-git-pre-commit-hook: _ensure_mise_tools_installed
+    #!/usr/bin/env sh
+    set -eu
+    {{ just_executable() }} --justfile "{{ justfile() }}" mise exec -- prek install
+    hook="{{ justfile_directory() }}/.git/hooks/pre-commit"
+    # The installed git hook runs later under Git, outside this just/mise environment.
+    # Injecting PREK_HOME keeps prek's cache under var/prek instead of a global home dir,
+    # which is more predictable and works better in sandboxed tools like Codex/OpenCode.
+    if [ -f "$hook" ] && ! grep -q '^export PREK_HOME=' "$hook"; then
+        sed -i '2iexport PREK_HOME="{{ prek_home }}"' "$hook"
+    fi
 
 # Runs the playbook with --tags=install-all,ensure-matrix-users-created,start and optional arguments
 install-all *extra_args: (run-tags "install-all,ensure-matrix-users-created,start" extra_args)
@@ -84,3 +119,12 @@ stop-group group *extra_args:
 # Rebuilds the mautrix-meta-instagram Ansible role using the mautrix-meta-messenger role as a source
 rebuild-mautrix-meta-instagram:
     /bin/bash "{{ justfile_directory() }}/bin/rebuild-mautrix-meta-instagram.sh" "{{ justfile_directory() }}/roles/custom"
+
+# Internal - ensures var/mise and var/prek directories exist
+_ensure_mise_data_directory:
+    @mkdir -p "{{ mise_data_dir }}"
+    @mkdir -p "{{ prek_home }}"
+
+# Internal - ensures mise tools are installed
+_ensure_mise_tools_installed: _ensure_mise_data_directory
+    @{{ just_executable() }} --justfile "{{ justfile() }}" mise install --quiet

mise.toml

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[tools]
+prek = "0.3.2"
+
+[settings]
+yes = true

requirements.yml

@@ -4,20 +4,20 @@
   version: v1.0.0-6
   name: auxiliary
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg.git
-  version: v1.4.3-2.1.1-1
+  version: v1.4.3-2.1.3-2
   name: backup_borg
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-cinny.git
-  version: v4.10.5-0
+  version: v4.11.1-1
   name: cinny
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-container-socket-proxy.git
-  version: v0.4.2-3
+  version: v0.4.2-4
   name: container_socket_proxy
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-coturn.git
-  version: v4.9.0-0
+  version: v4.9.0-1
   name: coturn
   activation_prefix: coturn_
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-ddclient.git
-  version: v4.0.0-1
+  version: v4.0.0-2
   name: ddclient
   activation_prefix: ddclient_
 - src: git+https://github.com/geerlingguy/ansible-role-docker
@@ -27,25 +27,25 @@
   version: 542a2d68db4e9a8e9bb4b508052760b900c7dce6
   name: docker_sdk_for_python
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-etherpad.git
-  version: v2.6.1-1
+  version: v2.6.1-3
   name: etherpad
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay.git
-  version: v4.98.1-r0-2-3
+  version: v4.99.1-r0-0-1
   name: exim_relay
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-grafana.git
-  version: v11.6.5-7
+  version: v11.6.5-9
   name: grafana
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-hydrogen.git
-  version: v0.5.1-1
+  version: v0.5.1-2
   name: hydrogen
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-jitsi.git
-  version: v10741-0
+  version: v10741-2
   name: jitsi
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server.git
-  version: v1.9.11-2
+  version: v1.9.12-1
   name: livekit_server
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-ntfy.git
-  version: v2.17.0-1
+  version: v2.19.2-1
   name: ntfy
 - src: git+https://github.com/devture/com.devture.ansible.role.playbook_help.git
   version: 8630e4f1749bcb659c412820f754473f09055052
@@ -57,38 +57,41 @@
   version: dd6e15246b7a9a2d921e0b3f9cd8a4a917a1bb2f
   name: playbook_state_preserver
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-postgres.git
-  version: v18.2-2
+  version: v18.3-1
   name: postgres
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-postgres-backup.git
-  version: v18-1
+  version: v18-2
   name: postgres_backup
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus.git
-  version: v3.9.1-1
+  version: v3.10.0-1
   name: prometheus
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-nginxlog-exporter.git
-  version: v1.10.0-0
+  version: v1.10.0-2
   name: prometheus_nginxlog_exporter
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-node-exporter.git
-  version: v1.9.1-14
+  version: v1.10.2-0
   name: prometheus_node_exporter
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-postgres-exporter.git
-  version: v0.19.0-1
+  version: v0.19.1-3
   name: prometheus_postgres_exporter
+- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-sable.git
+  version: v1.6.0-2
+  name: sable
 - src: git+https://github.com/devture/com.devture.ansible.role.systemd_docker_base.git
-  version: v1.4.1-0
+  version: v1.5.0-0
   name: systemd_docker_base
 - src: git+https://github.com/devture/com.devture.ansible.role.systemd_service_manager.git
-  version: v3.0.0-1
+  version: v3.2.0-0
   name: systemd_service_manager
 - src: git+https://github.com/devture/com.devture.ansible.role.timesync.git
   version: v1.1.0-1
   name: timesync
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik.git
-  version: v3.6.9-0
+  version: v3.6.11-2
   name: traefik
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik-certs-dumper.git
   version: v2.10.0-5
   name: traefik_certs_dumper
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-valkey.git
-  version: v9.0.3-0
+  version: v9.0.3-3
   name: valkey

roles/custom/matrix-alertmanager-receiver/defaults/main.yml

@@ -11,7 +11,7 @@
 matrix_alertmanager_receiver_enabled: true
 
 # renovate: datasource=docker depName=docker.io/metio/matrix-alertmanager-receiver
-matrix_alertmanager_receiver_version: 2026.2.25
+matrix_alertmanager_receiver_version: 2026.3.18
 
 matrix_alertmanager_receiver_scheme: https
 

roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2024 MDAD project contributors
-# SPDX-FileCopyrightText: 2024 - 2025 Catalan Lover <catalanlover@protonmail.com>
+# SPDX-FileCopyrightText: 2024 - 2026 Catalan Lover <catalanlover@protonmail.com>
 # SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2024 Suguru Hirahara
 #
@@ -20,7 +20,8 @@ matrix_appservice_draupnir_for_all_container_image_self_build_repo: "https://git
 matrix_appservice_draupnir_for_all_container_image_registry_prefix: "{{ 'localhost/' if matrix_appservice_draupnir_for_all_container_image_self_build else matrix_appservice_draupnir_for_all_container_image_registry_prefix_upstream }}"
 matrix_appservice_draupnir_for_all_container_image_registry_prefix_upstream: "{{ matrix_appservice_draupnir_for_all_container_image_registry_prefix_upstream_default }}"
 matrix_appservice_draupnir_for_all_container_image_registry_prefix_upstream_default: "docker.io/"
-matrix_appservice_draupnir_for_all_container_image: "{{ matrix_appservice_draupnir_for_all_container_image_registry_prefix }}gnuxie/draupnir:{{ matrix_appservice_draupnir_for_all_version }}"
+matrix_appservice_draupnir_for_all_container_image: "{{ matrix_appservice_draupnir_for_all_container_image_registry_prefix }}{{ matrix_appservice_draupnir_for_all_container_image_registry_namespace_identifier }}:{{ matrix_appservice_draupnir_for_all_version }}"
+matrix_appservice_draupnir_for_all_container_image_registry_namespace_identifier: "gnuxie/draupnir"
 matrix_appservice_draupnir_for_all_container_image_force_pull: "{{ matrix_appservice_draupnir_for_all_container_image.endswith(':latest') }}"
 
 matrix_appservice_draupnir_for_all_base_path: "{{ matrix_base_data_path }}/draupnir-for-all"

roles/custom/matrix-authentication-service/defaults/main.yml

@@ -22,7 +22,7 @@ matrix_authentication_service_container_repo_version: "{{ 'main' if matrix_authe
 matrix_authentication_service_container_src_files_path: "{{ matrix_base_data_path }}/matrix-authentication-service/container-src"
 
 # renovate: datasource=docker depName=ghcr.io/element-hq/matrix-authentication-service
-matrix_authentication_service_version: 1.12.0
+matrix_authentication_service_version: 1.13.0
 matrix_authentication_service_container_image_registry_prefix: "{{ 'localhost/' if matrix_authentication_service_container_image_self_build else matrix_authentication_service_container_image_registry_prefix_upstream }}"
 matrix_authentication_service_container_image_registry_prefix_upstream: "{{ matrix_authentication_service_container_image_registry_prefix_upstream_default }}"
 matrix_authentication_service_container_image_registry_prefix_upstream_default: "ghcr.io/"
@@ -300,6 +300,15 @@ matrix_authentication_service_config_database_idle_timeout: 600
 # Controls the `database.max_lifetime` configuration setting.
 matrix_authentication_service_config_database_max_lifetime: 1800
 
+# Controls whether the database connection is made via a UNIX socket.
+matrix_authentication_service_config_database_socket_enabled: false
+
+# The path to the Postgres socket's parent directory inside the MAS container.
+matrix_authentication_service_config_database_socket_path: "/run-postgres"
+
+# The path to the Postgres socket directory on the host (bind-mount source).
+matrix_authentication_service_config_database_socket_path_host: ""
+
 ########################################################################################
 #                                                                                      #
 # /Database configuration                                                              #
@@ -613,6 +622,10 @@ matrix_authentication_service_syn2mas_synapse_homeserver_config_path: ""
 
 matrix_authentication_service_syn2mas_container_network: "{{ matrix_authentication_service_container_network }}"
 
+matrix_authentication_service_syn2mas_synapse_database_socket_enabled: false
+matrix_authentication_service_syn2mas_synapse_database_socket_path: ""
+matrix_authentication_service_syn2mas_synapse_database_socket_path_host: ""
+
 # Additional options passed to the syn2mas sub-command (e.g. `mas-cli syn2mas [OPTIONS] migrate|check`).
 # Also see: `matrix_authentication_service_syn2mas_subcommand_extra_options`
 #

roles/custom/matrix-authentication-service/tasks/install.yml

@@ -33,6 +33,25 @@
       loop_control:
         loop_var: private_key_definition
 
+    # We intentionally do a single fixup pass here (instead of in `prepare_key.yml`)
+    # so that we reconcile both newly generated keys and any pre-existing keys with
+    # incorrect ownership/mode in one place.
+    #
+    # This primarily protects against setups where `become_user` is effectively not
+    # honored (for example due to inventory misconfiguration such as `ansible_become=false`),
+    # which can lead to host-side key generation creating root-owned files.
+    #
+    # See: https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/5033
+    - name: Ensure Matrix Authentication Service private keys have correct ownership and mode
+      ansible.builtin.file:
+        path: "{{ matrix_authentication_service_data_keys_path }}/{{ item.key_file }}"
+        state: file
+        mode: '0600'
+        owner: "{{ matrix_user_name }}"
+        group: "{{ matrix_group_name }}"
+      with_items: "{{ matrix_authentication_service_key_management_list }}"
+      register: matrix_authentication_service_private_keys_result
+
 - name: Ensure Matrix Authentication Service configuration installed
   ansible.builtin.copy:
     content: "{{ matrix_authentication_service_configuration | to_nice_yaml(indent=2, width=999999) }}"
@@ -117,4 +136,5 @@
         or matrix_authentication_service_support_files_result.changed | default(false)
         or matrix_authentication_service_systemd_service_result.changed | default(false)
         or matrix_authentication_service_container_image_pull_result.changed | default(false)
+        or matrix_authentication_service_private_keys_result.changed | default(false)
       }}

roles/custom/matrix-authentication-service/tasks/mas_cli_syn2mas.yml

@@ -71,6 +71,12 @@
       --mount type=bind,src={{ matrix_authentication_service_config_path }}/config.yaml,dst=/config.yaml,ro
       --mount type=bind,src={{ matrix_authentication_service_data_keys_path }},dst=/keys,ro
       --mount type=bind,src={{ matrix_authentication_service_syn2mas_synapse_homeserver_config_path }},dst=/homeserver.yaml,ro
+      {% if matrix_authentication_service_config_database_socket_enabled %}
+      --mount type=bind,src={{ matrix_authentication_service_config_database_socket_path_host }},dst={{ matrix_authentication_service_config_database_socket_path }}
+      {% endif %}
+      {% if matrix_authentication_service_syn2mas_synapse_database_socket_enabled and (not matrix_authentication_service_config_database_socket_enabled or matrix_authentication_service_syn2mas_synapse_database_socket_path != matrix_authentication_service_config_database_socket_path) %}
+      --mount type=bind,src={{ matrix_authentication_service_syn2mas_synapse_database_socket_path_host }},dst={{ matrix_authentication_service_syn2mas_synapse_database_socket_path }}
+      {% endif %}
       {{ matrix_authentication_service_container_image }}
       syn2mas
       --synapse-config=/homeserver.yaml

roles/custom/matrix-authentication-service/tasks/validate_config.yml

@@ -14,7 +14,8 @@
     - {'name': 'matrix_authentication_service_hostname', when: true}
     - {'name': 'matrix_authentication_service_config_database_username', when: true}
     - {'name': 'matrix_authentication_service_config_database_password', when: true}
-    - {'name': 'matrix_authentication_service_config_database_host', when: true}
+    - {'name': 'matrix_authentication_service_config_database_host', when: "{{ not matrix_authentication_service_config_database_socket_enabled }}"}
+    - {'name': 'matrix_authentication_service_config_database_socket_path_host', when: "{{ matrix_authentication_service_config_database_socket_enabled }}"}
     - {'name': 'matrix_authentication_service_config_database_database', when: true}
     - {'name': 'matrix_authentication_service_config_secrets_encryption', when: true}
     - {'name': 'matrix_authentication_service_config_matrix_homeserver', when: true}

roles/custom/matrix-authentication-service/templates/systemd/matrix-authentication-service.service.j2

@@ -28,6 +28,9 @@ ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
 			--label-file={{ matrix_authentication_service_config_path }}/labels \
 			--mount type=bind,src={{ matrix_authentication_service_config_path }}/config.yaml,dst=/config.yaml,ro \
 			--mount type=bind,src={{ matrix_authentication_service_data_keys_path }},dst=/keys,ro \
+			{% if matrix_authentication_service_config_database_socket_enabled %}
+			--mount type=bind,src={{ matrix_authentication_service_config_database_socket_path_host }},dst={{ matrix_authentication_service_config_database_socket_path }} \
+			{% endif %}
 			{% for arg in matrix_authentication_service_container_extra_arguments %}
 			{{ arg }} \
 			{% endfor %}

roles/custom/matrix-base/defaults/main.yml

@@ -116,6 +116,9 @@ matrix_server_fqn_hydrogen: "hydrogen.{{ matrix_domain }}"
 # This is where you access the Cinny web client from (if enabled via cinny_enabled; disabled by default).
 matrix_server_fqn_cinny: "cinny.{{ matrix_domain }}"
 
+# This is where you access the Sable web client from (if enabled via sable_enabled; disabled by default).
+matrix_server_fqn_sable: "sable.{{ matrix_domain }}"
+
 # This is where you access the SchildiChat Web from (if enabled via matrix_client_schildichat_enabled; disabled by default).
 matrix_server_fqn_schildichat: "schildichat.{{ matrix_domain }}"
 
@@ -243,6 +246,21 @@ matrix_integration_manager_ui_url: ~
 matrix_homeserver_container_extra_arguments_auto: []
 matrix_homeserver_app_service_config_files_auto: []
 
+# These playbook-level helpers describe which managed services Synapse should be wired to.
+# They are meant for orchestration concerns like container networking and systemd ordering,
+# while `matrix_synapse_*` variables stay focused on actual connection parameters.
+# These likely get overridden elsewhere.
+matrix_playbook_synapse_uses_managed_postgres: false
+matrix_playbook_synapse_uses_managed_valkey: false
+matrix_playbook_synapse_auto_compressor_uses_managed_postgres: false
+
+# This playbook-level helper describes whether Matrix Authentication Service should be wired
+# to the playbook-managed Postgres instance.
+# It is meant for orchestration concerns like container networking, systemd ordering, and database creation,
+# while `matrix_authentication_service_*` variables stay focused on actual connection parameters.
+# This likely gets overridden elsewhere.
+matrix_playbook_matrix_authentication_service_uses_managed_postgres: false
+
 # Controls whether various services should expose metrics publicly.
 # If Prometheus is operating on the same machine, exposing metrics publicly is not necessary.
 matrix_metrics_exposure_enabled: false

roles/custom/matrix-bot-baibot/defaults/main.yml

@@ -17,7 +17,7 @@ matrix_bot_baibot_container_repo_version: "{{ 'main' if matrix_bot_baibot_versio
 matrix_bot_baibot_container_src_files_path: "{{ matrix_base_data_path }}/baibot/container-src"
 
 # renovate: datasource=docker depName=ghcr.io/etkecc/baibot
-matrix_bot_baibot_version: v1.14.3
+matrix_bot_baibot_version: v1.16.0
 matrix_bot_baibot_container_image: "{{ matrix_bot_baibot_container_image_registry_prefix }}etkecc/baibot:{{ matrix_bot_baibot_version }}"
 matrix_bot_baibot_container_image_registry_prefix: "{{ 'localhost/' if matrix_bot_baibot_container_image_self_build else matrix_bot_baibot_container_image_registry_prefix_upstream }}"
 matrix_bot_baibot_container_image_registry_prefix_upstream: "{{ matrix_bot_baibot_container_image_registry_prefix_upstream_default }}"
@@ -59,8 +59,28 @@ matrix_bot_baibot_config_homeserver_url: ""
 # so it can start fresh.
 matrix_bot_baibot_config_user_mxid_localpart: baibot
 
+# Authentication settings (`user.*` configuration keys).
+#
+# baibot supports 2 mutually-exclusive authentication modes.
+# Set EITHER:
+# - password authentication: `matrix_bot_baibot_config_user_password`
+# OR:
+# - access-token authentication: `matrix_bot_baibot_config_user_access_token` + `matrix_bot_baibot_config_user_device_id`
+#
+# Password authentication is recommended for most playbook-managed deployments,
+# because it integrates with the `matrix-user-creator` role and can auto-create
+# the bot account (via the `ensure-matrix-users-created` playbook tag).
+# This remains true even on many MAS-enabled deployments where the bot account
+# is local and playbook-managed.
+
 # Controls the `user.password` configuration setting.
-matrix_bot_baibot_config_user_password: ''
+matrix_bot_baibot_config_user_password: null
+
+# Controls the `user.access_token` configuration setting.
+matrix_bot_baibot_config_user_access_token: null
+
+# Controls the `user.device_id` configuration setting.
+matrix_bot_baibot_config_user_device_id: null
 
 # Controls the `user.name` configuration setting.
 #
@@ -385,7 +405,7 @@ matrix_bot_baibot_config_agents_static_definitions_openai_config_api_key: ""
 
 matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_enabled: true
 # For valid model choices, see: https://platform.openai.com/docs/models
-matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_model_id: gpt-5.2
+matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_model_id: gpt-5.4
 # The prompt text to use (can be null or empty to not use a prompt).
 # See: https://huggingface.co/docs/transformers/en/tasks/prompting
 matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"

roles/custom/matrix-bot-baibot/tasks/validate_config.yml

@@ -12,7 +12,6 @@
   when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0"
   with_items:
     - {'name': 'matrix_bot_baibot_config_user_mxid_localpart', when: true}
-    - {'name': 'matrix_bot_baibot_config_user_password', when: true}
     - {'name': 'matrix_bot_baibot_container_network', when: true}
     - {'name': 'matrix_bot_baibot_config_homeserver_url', when: true}
 
@@ -26,6 +25,58 @@
 
     - {'name': 'matrix_bot_baibot_config_agents_static_definitions_openai_config_api_key', when: "{{ matrix_bot_baibot_config_agents_static_definitions_openai_enabled }}"}
 
+- name: Fail if baibot authentication mode is not configured
+  ansible.builtin.fail:
+    msg: >-
+      You need to configure one baibot authentication mode:
+      either `matrix_bot_baibot_config_user_password`
+      or (`matrix_bot_baibot_config_user_access_token` + `matrix_bot_baibot_config_user_device_id`).
+  when: >-
+    (
+      matrix_bot_baibot_config_user_password | default('', true) | string | length == 0
+    )
+    and
+    (
+      matrix_bot_baibot_config_user_access_token | default('', true) | string | length == 0
+      and matrix_bot_baibot_config_user_device_id | default('', true) | string | length == 0
+    )
+
+- name: Fail if baibot authentication mode is configured ambiguously
+  ansible.builtin.fail:
+    msg: >-
+      You need to configure exactly one baibot authentication mode.
+      Set either `matrix_bot_baibot_config_user_password`,
+      or (`matrix_bot_baibot_config_user_access_token` + `matrix_bot_baibot_config_user_device_id`) but not both.
+  when: >-
+    (
+      matrix_bot_baibot_config_user_password | default('', true) | string | length > 0
+    )
+    and
+    (
+      matrix_bot_baibot_config_user_access_token | default('', true) | string | length > 0
+      or matrix_bot_baibot_config_user_device_id | default('', true) | string | length > 0
+    )
+
+- name: Fail if baibot access token authentication is incomplete
+  ansible.builtin.fail:
+    msg: >-
+      Access-token authentication requires both
+      `matrix_bot_baibot_config_user_access_token` and `matrix_bot_baibot_config_user_device_id`.
+  when: >-
+    (
+      matrix_bot_baibot_config_user_password | default('', true) | string | length == 0
+    )
+    and
+    (
+      matrix_bot_baibot_config_user_access_token | default('', true) | string | length > 0
+      or matrix_bot_baibot_config_user_device_id | default('', true) | string | length > 0
+    )
+    and
+    (
+      matrix_bot_baibot_config_user_access_token | default('', true) | string | length == 0
+      or matrix_bot_baibot_config_user_device_id | default('', true) | string | length == 0
+    )
+
 - name: Fail if admin patterns list is empty
   ansible.builtin.fail:
     msg: >-

roles/custom/matrix-bot-baibot/templates/config.yaml.j2

@@ -15,7 +15,11 @@ homeserver:
 
 user:
   mxid_localpart: {{ matrix_bot_baibot_config_user_mxid_localpart | to_json }}
+
+  # Authentication: set EITHER password OR access_token + device_id.
   password: {{ matrix_bot_baibot_config_user_password | to_json }}
+  access_token: {{ matrix_bot_baibot_config_user_access_token | to_json }}
+  device_id: {{ matrix_bot_baibot_config_user_device_id | to_json }}
 
   # The name the bot uses as a display name and when it refers to itself.
   # Leave empty to use the default (baibot).

roles/custom/matrix-bot-draupnir/defaults/main.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2023 - 2024 MDAD project contributors
-# SPDX-FileCopyrightText: 2023 - 2025 Catalan Lover <catalanlover@protonmail.com>
+# SPDX-FileCopyrightText: 2023 - 2026 Catalan Lover <catalanlover@protonmail.com>
 # SPDX-FileCopyrightText: 2023 Samuel Meenzen
 # SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
 #
@@ -17,7 +17,8 @@ matrix_bot_draupnir_version: "v2.9.0"
 matrix_bot_draupnir_container_image_self_build: false
 matrix_bot_draupnir_container_image_self_build_repo: "https://github.com/the-draupnir-project/Draupnir.git"
 
-matrix_bot_draupnir_container_image: "{{ matrix_bot_draupnir_container_image_registry_prefix }}gnuxie/draupnir:{{ matrix_bot_draupnir_version }}"
+matrix_bot_draupnir_container_image: "{{ matrix_bot_draupnir_container_image_registry_prefix }}{{ matrix_bot_draupnir_container_image_registry_namespace_identifier }}:{{ matrix_bot_draupnir_version }}"
+matrix_bot_draupnir_container_image_registry_namespace_identifier: "gnuxie/draupnir"
 matrix_bot_draupnir_container_image_registry_prefix: "{{ 'localhost/' if matrix_bot_draupnir_container_image_self_build else matrix_bot_draupnir_container_image_registry_prefix_upstream }}"
 matrix_bot_draupnir_container_image_registry_prefix_upstream: "{{ matrix_bot_draupnir_container_image_registry_prefix_upstream_default }}"
 matrix_bot_draupnir_container_image_registry_prefix_upstream_default: "docker.io/"

roles/custom/matrix-bot-honoroit/defaults/main.yml

@@ -30,7 +30,7 @@ matrix_bot_honoroit_container_repo_version: "{{ matrix_bot_honoroit_version }}"
 matrix_bot_honoroit_container_src_files_path: "{{ matrix_base_data_path }}/honoroit/docker-src"
 
 # renovate: datasource=docker depName=ghcr.io/etkecc/honoroit
-matrix_bot_honoroit_version: v0.9.29
+matrix_bot_honoroit_version: v0.9.30
 matrix_bot_honoroit_container_image: "{{ matrix_bot_honoroit_container_image_registry_prefix }}etkecc/honoroit:{{ matrix_bot_honoroit_version }}"
 matrix_bot_honoroit_container_image_registry_prefix: "{{ 'localhost/' if matrix_bot_honoroit_container_image_self_build else matrix_bot_honoroit_container_image_registry_prefix_upstream }}"
 matrix_bot_honoroit_container_image_registry_prefix_upstream: "{{ matrix_bot_honoroit_container_image_registry_prefix_upstream_default }}"

roles/custom/matrix-bot-mjolnir/defaults/main.yml

@@ -17,7 +17,7 @@
 matrix_bot_mjolnir_enabled: true
 
 # renovate: datasource=docker depName=matrixdotorg/mjolnir
-matrix_bot_mjolnir_version: "v1.12.0"
+matrix_bot_mjolnir_version: "v1.12.1"
 
 matrix_bot_mjolnir_container_image_self_build: false
 matrix_bot_mjolnir_container_image_self_build_repo: "https://github.com/matrix-org/mjolnir.git"

roles/custom/matrix-bridge-appservice-kakaotalk/defaults/main.yml

@@ -225,3 +225,13 @@ matrix_appservice_kakaotalk_registration_yaml: |
   rate_limited: false
 
 matrix_appservice_kakaotalk_registration: "{{ matrix_appservice_kakaotalk_registration_yaml | from_yaml }}"
+
+# matrix_appservice_kakaotalk_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_appservice_kakaotalk_restart_necessary: false

roles/custom/matrix-bridge-appservice-kakaotalk/tasks/setup_install.yml

@@ -13,10 +13,10 @@
     force_source: "{{ matrix_appservice_kakaotalk_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_appservice_kakaotalk_container_image_force_pull }}"
   when: not matrix_appservice_kakaotalk_container_image_self_build
-  register: result
+  register: matrix_appservice_kakaotalk_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_appservice_kakaotalk_container_image_pull_result is not failed
 
 - name: Ensure matrix-appservice-kakaotalk-node image is pulled
   community.docker.docker_image:
@@ -25,10 +25,10 @@
     force_source: "{{ matrix_appservice_kakaotalk_node_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_appservice_kakaotalk_node_container_image_force_pull }}"
   when: not matrix_appservice_kakaotalk_container_image_self_build
-  register: result
+  register: matrix_appservice_kakaotalk_node_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_appservice_kakaotalk_node_container_image_pull_result is not failed
 
 - name: Ensure matrix-appservice-kakaotalk paths exist
   ansible.builtin.file:
@@ -86,6 +86,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_appservice_kakaotalk_node_config_result
 
 - name: Ensure matrix-appservice-kakaotalk config.yaml installed
   ansible.builtin.copy:
@@ -94,6 +95,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_appservice_kakaotalk_config_result
 
 - name: Ensure matrix-appservice-kakaotalk registration.yaml installed
   ansible.builtin.copy:
@@ -102,6 +104,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_appservice_kakaotalk_registration_result
 
 - name: Ensure matrix-appservice-kakaotalk container network is created
   community.general.docker_network:
@@ -122,3 +125,17 @@
     src: "{{ role_path }}/templates/systemd/matrix-appservice-kakaotalk.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-appservice-kakaotalk.service"
     mode: '0644'
+  register: matrix_appservice_kakaotalk_systemd_service_result
+
+- name: Determine whether matrix-appservice-kakaotalk needs a restart
+  ansible.builtin.set_fact:
+    matrix_appservice_kakaotalk_restart_necessary: >-
+      {{
+        matrix_appservice_kakaotalk_node_config_result.changed | default(false)
+        or matrix_appservice_kakaotalk_config_result.changed | default(false)
+        or matrix_appservice_kakaotalk_registration_result.changed | default(false)
+        or matrix_appservice_kakaotalk_node_systemd_service_result.changed | default(false)
+        or matrix_appservice_kakaotalk_systemd_service_result.changed | default(false)
+        or matrix_appservice_kakaotalk_container_image_pull_result.changed | default(false)
+        or matrix_appservice_kakaotalk_node_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-bridge-hookshot/tasks/setup_install.yml

@@ -76,6 +76,20 @@
   become_user: "{{ matrix_user_name }}"
   when: "not hookshot_passkey_file.stat.exists"
 
+# We intentionally reconcile the passkey ownership/mode after generation,
+# because some setups can end up creating host-side files as the SSH user
+# instead of `matrix` when `become_user` is effectively not honored.
+#
+# See: https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/5033
+- name: Ensure hookshot passkey has correct ownership and mode
+  ansible.builtin.file:
+    path: "{{ matrix_hookshot_base_path }}/passkey.pem"
+    state: file
+    mode: '0600'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  register: matrix_hookshot_passkey_result
+
 - name: Ensure hookshot config.yml installed if provided
   ansible.builtin.copy:
     content: "{{ matrix_hookshot_configuration | to_nice_yaml(indent=2, width=999999) }}"
@@ -154,6 +168,7 @@
         matrix_hookshot_config_result.changed | default(false)
         or matrix_hookshot_registration_result.changed | default(false)
         or matrix_hookshot_github_key_result.changed | default(false)
+        or matrix_hookshot_passkey_result.changed | default(false)
         or matrix_hookshot_support_files_result.changed | default(false)
         or matrix_hookshot_systemd_service_result.changed | default(false)
         or matrix_hookshot_container_image_pull_result.changed | default(false)

roles/custom/matrix-bridge-mautrix-signal/defaults/main.yml

@@ -25,7 +25,7 @@ matrix_mautrix_signal_container_image_self_build_repo: "https://mau.dev/mautrix/
 matrix_mautrix_signal_container_image_self_build_branch: "{{ 'main' if matrix_mautrix_signal_version == 'latest' else matrix_mautrix_signal_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/signal
-matrix_mautrix_signal_version: v0.2602.0
+matrix_mautrix_signal_version: v26.02.2
 
 # See: https://mau.dev/mautrix/signal/container_registry
 matrix_mautrix_signal_container_image: "{{ matrix_mautrix_signal_container_image_registry_prefix }}mautrix/signal:{{ matrix_mautrix_signal_container_image_tag }}"

roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml

@@ -17,7 +17,7 @@ matrix_mautrix_slack_container_image_self_build_repo: "https://mau.dev/mautrix/s
 matrix_mautrix_slack_container_image_self_build_branch: "{{ 'main' if matrix_mautrix_slack_version == 'latest' else matrix_mautrix_slack_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/slack
-matrix_mautrix_slack_version: v0.2602.0
+matrix_mautrix_slack_version: v0.2603.0
 # See: https://mau.dev/mautrix/slack/container_registry
 matrix_mautrix_slack_container_image: "{{ matrix_mautrix_slack_container_image_registry_prefix }}mautrix/slack:{{ matrix_mautrix_slack_version }}"
 matrix_mautrix_slack_container_image_registry_prefix: "{{ 'localhost/' if matrix_mautrix_slack_container_image_self_build else matrix_mautrix_slack_container_image_registry_prefix_upstream }}"

roles/custom/matrix-bridge-mautrix-twitter/defaults/main.yml

@@ -22,7 +22,7 @@ matrix_mautrix_twitter_container_image_self_build_repo: "https://github.com/maut
 matrix_mautrix_twitter_container_image_self_build_repo_version: "{{ 'master' if matrix_mautrix_twitter_version == 'latest' else matrix_mautrix_twitter_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/twitter
-matrix_mautrix_twitter_version: v0.2511.0
+matrix_mautrix_twitter_version: v0.2603.0
 # See: https://mau.dev/tulir/mautrix-twitter/container_registry
 matrix_mautrix_twitter_container_image: "{{ matrix_mautrix_twitter_container_image_registry_prefix }}mautrix/twitter:{{ matrix_mautrix_twitter_version }}"
 matrix_mautrix_twitter_container_image_registry_prefix: "{{ 'localhost/' if matrix_mautrix_twitter_container_image_self_build else matrix_mautrix_twitter_container_image_registry_prefix_upstream }}"

roles/custom/matrix-bridge-mautrix-whatsapp/defaults/main.yml

@@ -28,7 +28,7 @@ matrix_mautrix_whatsapp_container_image_self_build_repo: "https://mau.dev/mautri
 matrix_mautrix_whatsapp_container_image_self_build_branch: "{{ 'master' if matrix_mautrix_whatsapp_version == 'latest' else matrix_mautrix_whatsapp_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/whatsapp
-matrix_mautrix_whatsapp_version: v0.2602.0
+matrix_mautrix_whatsapp_version: v0.2603.0
 
 # See: https://mau.dev/mautrix/whatsapp/container_registry
 matrix_mautrix_whatsapp_container_image: "{{ matrix_mautrix_whatsapp_container_image_registry_prefix }}mautrix/whatsapp:{{ matrix_mautrix_whatsapp_version }}"

roles/custom/matrix-bridge-postmoogle/defaults/main.yml

@@ -18,7 +18,7 @@ matrix_postmoogle_container_repo_version: "{{ 'main' if matrix_postmoogle_versio
 matrix_postmoogle_container_src_files_path: "{{ matrix_base_data_path }}/postmoogle/docker-src"
 
 # renovate: datasource=docker depName=ghcr.io/etkecc/postmoogle
-matrix_postmoogle_version: v0.9.28
+matrix_postmoogle_version: v0.9.29
 matrix_postmoogle_container_image: "{{ matrix_postmoogle_container_image_registry_prefix }}etkecc/postmoogle:{{ matrix_postmoogle_version }}"
 matrix_postmoogle_container_image_registry_prefix: "{{ 'localhost/' if matrix_postmoogle_container_image_self_build else matrix_postmoogle_container_image_registry_prefix_upstream }}"
 matrix_postmoogle_container_image_registry_prefix_upstream: "{{ matrix_postmoogle_container_image_registry_prefix_upstream_default }}"

roles/custom/matrix-bridge-wechat/defaults/main.yml

@@ -163,3 +163,13 @@ matrix_wechat_agent_service_secret: "{{ matrix_wechat_bridge_listen_secret }}"
 matrix_wechat_agent_configuration_yaml: "{{ lookup('template', 'templates/agent-config.yaml.j2') }}"
 
 matrix_wechat_agent_configuration: "{{ matrix_wechat_agent_configuration_yaml | from_yaml }}"
+
+# matrix_wechat_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_wechat_restart_necessary: false

roles/custom/matrix-bridge-wechat/tasks/install.yml

@@ -27,10 +27,10 @@
     force_source: "{{ matrix_wechat_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_wechat_container_image_force_pull }}"
   when: not matrix_wechat_container_image_self_build
-  register: result
+  register: matrix_wechat_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_wechat_container_image_pull_result is not failed
 
 - when: matrix_wechat_container_image_self_build | bool
   block:
@@ -62,10 +62,10 @@
     force_source: "{{ matrix_wechat_agent_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_wechat_agent_container_image_force_pull }}"
   when: not matrix_wechat_agent_container_image_self_build
-  register: result
+  register: matrix_wechat_agent_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_wechat_agent_container_image_pull_result is not failed
 
 - when: matrix_wechat_agent_container_image_self_build | bool
   block:
@@ -97,6 +97,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_wechat_config_result
 
 - name: Ensure WeChat registration.yaml installed
   ansible.builtin.copy:
@@ -105,6 +106,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_wechat_registration_result
 
 - name: Ensure Wechat Agent configuration installed
   ansible.builtin.copy:
@@ -113,6 +115,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_wechat_agent_config_result
 
 - name: Ensure matrix-wechat container network is created
   community.general.docker_network:
@@ -134,3 +137,16 @@
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-wechat-agent.service"
     mode: '0644'
   register: matrix_wechat_agent_systemd_service_result
+
+- name: Determine whether WeChat Bridge needs a restart
+  ansible.builtin.set_fact:
+    matrix_wechat_restart_necessary: >-
+      {{
+        matrix_wechat_config_result.changed | default(false)
+        or matrix_wechat_registration_result.changed | default(false)
+        or matrix_wechat_agent_config_result.changed | default(false)
+        or matrix_wechat_systemd_service_result.changed | default(false)
+        or matrix_wechat_agent_systemd_service_result.changed | default(false)
+        or matrix_wechat_container_image_pull_result.changed | default(false)
+        or matrix_wechat_agent_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-client-commet/defaults/main.yml

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+# Project source code URL: https://github.com/commetchat/commet
+
+matrix_client_commet_enabled: true
+
+# The git branch, tag, or SHA to build from
+matrix_client_commet_version: "main"
+
+# The hostname at which Commet is served (e.g. commet.example.com)
+matrix_client_commet_hostname: ""
+
+# The path at which Commet is exposed.
+# This value must either be `/` or not end with a slash (e.g. `/commet`).
+matrix_client_commet_path_prefix: /
+
+matrix_client_commet_base_path: "{{ matrix_base_data_path }}/client-commet"
+matrix_client_commet_container_src_path: "{{ matrix_client_commet_base_path }}/container-src"
+matrix_client_commet_config_path: "{{ matrix_client_commet_base_path }}/config"
+
+# Set to false to pull a pre-built image from a registry instead of building on the server.
+matrix_client_commet_container_image_self_build: true
+
+# Self-build settings (used when matrix_client_commet_container_image_self_build: true)
+matrix_client_commet_container_image_self_build_repo: "https://github.com/commetchat/commet.git"
+# Populated automatically after git clone in setup_install.yml
+matrix_client_commet_container_image_self_build_git_hash: ""
+matrix_client_commet_container_image_self_build_version_tag: "{{ matrix_client_commet_version }}"
+matrix_client_commet_container_image: "localhost/matrix-client-commet:{{ matrix_client_commet_version }}"
+
+# The in-container port nginx listens on
+matrix_client_commet_container_port: 8080
+
+# Optionally expose the container port on the host.
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8765"), or empty string to not expose.
+matrix_client_commet_container_http_host_bind_port: ""
+
+# The base container network
+matrix_client_commet_container_network: ""
+
+# Additional container networks the container is connected to.
+# The role does not create these networks, so make sure they already exist.
+matrix_client_commet_container_additional_networks: []
+
+# Runtime configuration — mounted into the container, not baked into the image
+matrix_client_commet_default_homeserver: "matrix.org"
+
+# ---------------------------------------------------------------------------
+# Traefik labels
+# ---------------------------------------------------------------------------
+matrix_client_commet_container_labels_traefik_enabled: true
+matrix_client_commet_container_labels_traefik_docker_network: "{{ matrix_client_commet_container_network }}"
+matrix_client_commet_container_labels_traefik_hostname: "{{ matrix_client_commet_hostname }}"
+# The path prefix must either be `/` or not end with a slash (e.g. `/commet`).
+matrix_client_commet_container_labels_traefik_path_prefix: "{{ matrix_client_commet_path_prefix }}"
+matrix_client_commet_container_labels_traefik_rule: "Host(`{{ matrix_client_commet_container_labels_traefik_hostname }}`){% if matrix_client_commet_container_labels_traefik_path_prefix != '/' %} && PathPrefix(`{{ matrix_client_commet_container_labels_traefik_path_prefix }}`){% endif %}"
+matrix_client_commet_container_labels_traefik_priority: 0
+matrix_client_commet_container_labels_traefik_entrypoints: web-secure
+matrix_client_commet_container_labels_traefik_tls: "{{ matrix_client_commet_container_labels_traefik_entrypoints != 'web' }}"
+matrix_client_commet_container_labels_traefik_tls_certResolver: default  # noqa var-naming
+
+# Controls whether a compression middleware will be injected into the middlewares list.
+matrix_client_commet_container_labels_traefik_compression_middleware_enabled: false
+matrix_client_commet_container_labels_traefik_compression_middleware_name: ""
+
+# Additional response headers (auto-built from security header variables below)
+matrix_client_commet_container_labels_traefik_additional_response_headers: "{{ matrix_client_commet_container_labels_traefik_additional_response_headers_auto | combine(matrix_client_commet_container_labels_traefik_additional_response_headers_custom) }}"
+matrix_client_commet_container_labels_traefik_additional_response_headers_auto: |
+  {{
+    {}
+    | combine({'X-XSS-Protection': matrix_client_commet_http_header_xss_protection} if matrix_client_commet_http_header_xss_protection else {})
+    | combine({'X-Content-Type-Options': matrix_client_commet_http_header_content_type_options} if matrix_client_commet_http_header_content_type_options else {})
+    | combine({'Content-Security-Policy': matrix_client_commet_http_header_content_security_policy} if matrix_client_commet_http_header_content_security_policy else {})
+    | combine({'Strict-Transport-Security': matrix_client_commet_http_header_strict_transport_security} if matrix_client_commet_http_header_strict_transport_security and matrix_client_commet_container_labels_traefik_tls else {})
+  }}
+matrix_client_commet_container_labels_traefik_additional_response_headers_custom: {}
+
+# Additional container labels (multiline string)
+matrix_client_commet_container_labels_additional_labels: ""
+
+# Extra arguments to pass to docker create
+matrix_client_commet_container_extra_arguments: []
+
+# ---------------------------------------------------------------------------
+# HTTP security headers
+# ---------------------------------------------------------------------------
+matrix_client_commet_http_header_xss_protection: "1; mode=block"
+matrix_client_commet_http_header_content_type_options: nosniff
+matrix_client_commet_http_header_content_security_policy: "frame-ancestors 'self'"
+matrix_client_commet_http_header_strict_transport_security: "max-age=31536000; includeSubDomains"
+
+# ---------------------------------------------------------------------------
+# Systemd
+# ---------------------------------------------------------------------------
+matrix_client_commet_systemd_required_services_list: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
+
+# matrix_client_commet_restart_necessary is automatically set during installation
+# to signal whether the service should be restarted after setup.
+matrix_client_commet_restart_necessary: false

roles/custom/matrix-client-commet/tasks/main.yml

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- tags:
+    - setup-all
+    - setup-client-commet
+    - install-all
+    - install-client-commet
+  block:
+    - when: matrix_client_commet_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
+
+- tags:
+    - setup-all
+    - setup-client-commet
+  block:
+    - when: not matrix_client_commet_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+
+- tags:
+    - self-check
+  block:
+    - when: matrix_client_commet_enabled | bool
+      ansible.builtin.debug:
+        msg: >-
+          Commet is running at
+          https://{{ matrix_client_commet_hostname }}{{ matrix_client_commet_path_prefix }}

roles/custom/matrix-client-commet/tasks/setup_install.yml

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2025 Nikita Chernyi
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Ensure Commet paths exist
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+    mode: "0750"
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - "{{ matrix_client_commet_base_path }}"
+    - "{{ matrix_client_commet_config_path }}"
+
+- name: Ensure Commet container image is pulled
+  community.docker.docker_image:
+    name: "{{ matrix_client_commet_container_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_client_commet_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_client_commet_container_image_force_pull }}"
+  when: "not matrix_client_commet_container_image_self_build | bool"
+  register: matrix_client_commet_image_pull_result
+  retries: "{{ devture_playbook_help_container_retries_count }}"
+  delay: "{{ devture_playbook_help_container_retries_delay }}"
+  until: matrix_client_commet_image_pull_result is not failed
+
+- when: "matrix_client_commet_container_image_self_build | bool"
+  block:
+    - name: Check Commet git repository metadata exists
+      ansible.builtin.stat:
+        path: "{{ matrix_client_commet_container_src_path }}/.git/config"
+      register: matrix_client_commet_git_config_file_stat
+
+    - name: Remove Commet source directory if git remote is misconfigured
+      ansible.builtin.file:
+        path: "{{ matrix_client_commet_container_src_path }}"
+        state: absent
+      when: not matrix_client_commet_git_config_file_stat.stat.exists
+      become: true
+
+    - name: Ensure Commet repository is present on self-build
+      ansible.builtin.git:
+        repo: "{{ matrix_client_commet_container_image_self_build_repo }}"
+        dest: "{{ matrix_client_commet_container_src_path }}"
+        version: "{{ matrix_client_commet_version }}"
+        force: "yes"
+      become: true
+      become_user: "{{ matrix_user_name }}"
+      register: matrix_client_commet_git_pull_results
+
+    - name: Set git hash fact
+      ansible.builtin.set_fact:
+        matrix_client_commet_container_image_self_build_git_hash: "{{ matrix_client_commet_git_pull_results.after }}"
+
+    - name: Ensure Commet container image is built
+      ansible.builtin.command:
+        cmd: |-
+          {{ devture_systemd_docker_base_host_command_docker }} buildx build
+          --tag={{ matrix_client_commet_container_image }}
+          --build-arg GIT_HASH={{ matrix_client_commet_container_image_self_build_git_hash }}
+          --build-arg VERSION_TAG={{ matrix_client_commet_container_image_self_build_version_tag }}
+          --build-arg BUILD_DATE={{ ansible_date_time.epoch }}
+          --file={{ matrix_client_commet_container_src_path }}/Dockerfile
+          {{ matrix_client_commet_container_src_path }}
+      changed_when: true
+      register: matrix_client_commet_image_build_result
+
+- name: Ensure Commet global_config.json is installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/global_config.json.j2"
+    dest: "{{ matrix_client_commet_config_path }}/global_config.json"
+    mode: "0644"
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  register: matrix_client_commet_config_result
+
+- name: Ensure Commet support files are installed
+  ansible.builtin.template:
+    src: "{{ item.src }}"
+    dest: "{{ matrix_client_commet_base_path }}/{{ item.name }}"
+    mode: "0644"
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - {src: "{{ role_path }}/templates/labels.j2", name: "labels"}
+    - {src: "{{ role_path }}/templates/env.j2", name: "env"}
+  register: matrix_client_commet_support_files_result
+
+- name: Ensure Commet container network is created
+  community.general.docker_network:
+    enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
+    name: "{{ matrix_client_commet_container_network }}"
+    driver: bridge
+    driver_options: "{{ devture_systemd_docker_base_container_networks_driver_options }}"
+
+- name: Ensure matrix-client-commet.service is installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-client-commet.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-client-commet.service"
+    mode: "0644"
+  register: matrix_client_commet_systemd_service_result
+
+- name: Determine whether Commet needs a restart
+  ansible.builtin.set_fact:
+    matrix_client_commet_restart_necessary: >-
+      {{
+        matrix_client_commet_config_result.changed | default(false)
+        or matrix_client_commet_support_files_result.changed | default(false)
+        or matrix_client_commet_systemd_service_result.changed | default(false)
+        or matrix_client_commet_image_build_result.changed | default(false)
+        or matrix_client_commet_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-client-commet/tasks/setup_uninstall.yml

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check existence of matrix-client-commet.service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-client-commet.service"
+  register: matrix_client_commet_service_stat
+
+- when: matrix_client_commet_service_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-client-commet is stopped
+      ansible.builtin.service:
+        name: matrix-client-commet
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure matrix-client-commet.service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-client-commet.service"
+        state: absent
+
+    - name: Ensure Commet path doesn't exist
+      ansible.builtin.file:
+        path: "{{ matrix_client_commet_base_path }}"
+        state: absent

roles/custom/matrix-client-commet/templates/env.j2

@@ -0,0 +1,12 @@
+{#
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+{#
+Environment variables for the matrix-client-commet container.
+Add custom variables by appending to matrix_client_commet_environment_variables_extension.
+#}
+
+{{ matrix_client_commet_environment_variables_extension | default('') }}

roles/custom/matrix-client-commet/templates/global_config.json.j2

@@ -0,0 +1,3 @@
+{
+  "default_homeserver": "{{ matrix_client_commet_default_homeserver }}"
+}

roles/custom/matrix-client-commet/templates/global_config.json.j2.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later

roles/custom/matrix-client-commet/templates/labels.j2

@@ -0,0 +1,60 @@
+{#
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+{#
+Traefik labels for matrix-client-commet.
+#}
+
+{% if matrix_client_commet_container_labels_traefik_enabled %}
+traefik.enable=true
+
+{% if matrix_client_commet_container_labels_traefik_docker_network %}
+traefik.docker.network={{ matrix_client_commet_container_labels_traefik_docker_network }}
+{% endif %}
+
+traefik.http.services.matrix-client-commet.loadbalancer.server.port={{ matrix_client_commet_container_port }}
+
+{% set middlewares = [] %}
+
+{% if matrix_client_commet_container_labels_traefik_compression_middleware_enabled %}
+{% set middlewares = middlewares + [matrix_client_commet_container_labels_traefik_compression_middleware_name] %}
+{% endif %}
+
+{% if matrix_client_commet_container_labels_traefik_path_prefix != '/' %}
+traefik.http.middlewares.matrix-client-commet-slashless-redirect.redirectregex.regex=({{ matrix_client_commet_container_labels_traefik_path_prefix | quote }})$
+traefik.http.middlewares.matrix-client-commet-slashless-redirect.redirectregex.replacement=${1}/
+{% set middlewares = middlewares + ['matrix-client-commet-slashless-redirect'] %}
+{% endif %}
+
+{% if matrix_client_commet_container_labels_traefik_path_prefix != '/' %}
+traefik.http.middlewares.matrix-client-commet-strip-prefix.stripprefix.prefixes={{ matrix_client_commet_container_labels_traefik_path_prefix }}
+{% set middlewares = middlewares + ['matrix-client-commet-strip-prefix'] %}
+{% endif %}
+
+{% if matrix_client_commet_container_labels_traefik_additional_response_headers.keys() | length > 0 %}
+{% for name, value in matrix_client_commet_container_labels_traefik_additional_response_headers.items() %}
+traefik.http.middlewares.matrix-client-commet-add-headers.headers.customresponseheaders.{{ name }}={{ value }}
+{% endfor %}
+{% set middlewares = middlewares + ['matrix-client-commet-add-headers'] %}
+{% endif %}
+
+traefik.http.routers.matrix-client-commet.rule={{ matrix_client_commet_container_labels_traefik_rule }}
+{% if matrix_client_commet_container_labels_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-client-commet.priority={{ matrix_client_commet_container_labels_traefik_priority }}
+{% endif %}
+traefik.http.routers.matrix-client-commet.service=matrix-client-commet
+{% if middlewares | length > 0 %}
+traefik.http.routers.matrix-client-commet.middlewares={{ middlewares | join(',') }}
+{% endif %}
+traefik.http.routers.matrix-client-commet.entrypoints={{ matrix_client_commet_container_labels_traefik_entrypoints }}
+traefik.http.routers.matrix-client-commet.tls={{ matrix_client_commet_container_labels_traefik_tls | to_json }}
+{% if matrix_client_commet_container_labels_traefik_tls %}
+traefik.http.routers.matrix-client-commet.tls.certResolver={{ matrix_client_commet_container_labels_traefik_tls_certResolver }}
+{% endif %}
+
+{% endif %}
+
+{{ matrix_client_commet_container_labels_additional_labels }}

roles/custom/matrix-client-commet/templates/systemd/matrix-client-commet.service.j2

@@ -0,0 +1,58 @@
+{#
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+#}
+
+#jinja2: lstrip_blocks: True
+[Unit]
+Description=Matrix Commet web client
+{% for service in matrix_client_commet_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-client-commet 2>/dev/null || true'
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-client-commet 2>/dev/null || true'
+
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
+			--rm \
+			--name=matrix-client-commet \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--network={{ matrix_client_commet_container_network }} \
+			{% if matrix_client_commet_container_http_host_bind_port %}
+			-p {{ matrix_client_commet_container_http_host_bind_port }}:{{ matrix_client_commet_container_port }} \
+			{% endif %}
+			--label-file={{ matrix_client_commet_base_path }}/labels \
+			--env-file={{ matrix_client_commet_base_path }}/env \
+			--tmpfs=/tmp:rw,noexec,nosuid,size=10m \
+			--tmpfs=/var/cache/nginx:rw,mode=777 \
+			--tmpfs=/var/run:rw,mode=777 \
+			--mount type=bind,src={{ matrix_client_commet_config_path }}/global_config.json,dst=/usr/share/nginx/html/assets/assets/config/global_config.json,ro \
+			{% for arg in matrix_client_commet_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_client_commet_container_image }}
+
+{% for network in matrix_client_commet_container_additional_networks %}
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-client-commet
+{% endfor %}
+
+ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-client-commet
+
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-client-commet 2>/dev/null || true'
+ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-client-commet 2>/dev/null || true'
+
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-client-commet
+
+[Install]
+WantedBy=multi-user.target

roles/custom/matrix-client-element/defaults/main.yml

@@ -29,7 +29,7 @@ matrix_client_element_container_image_self_build_repo: "https://github.com/eleme
 matrix_client_element_container_image_self_build_low_memory_system_patch_enabled: "{{ ansible_facts['memtotal_mb'] < 4096 }}"
 
 # renovate: datasource=docker depName=ghcr.io/element-hq/element-web
-matrix_client_element_version: v1.12.11
+matrix_client_element_version: v1.12.12
 
 matrix_client_element_container_image: "{{ matrix_client_element_container_image_registry_prefix }}element-hq/element-web:{{ matrix_client_element_version }}"
 matrix_client_element_container_image_registry_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else matrix_client_element_container_image_registry_prefix_upstream }}"

roles/custom/matrix-client-element/tasks/self_check.yml

@@ -5,9 +5,6 @@
 
 ---
 
-- ansible.builtin.set_fact:
-    matrix_client_element_url_endpoint_public: "{{ matrix_client_element_scheme }}://{{ matrix_client_element_hostname }}/config.json"
-
 - name: Check Element Web
   ansible.builtin.uri:
     url: "{{ matrix_client_element_url_endpoint_public }}"

roles/custom/matrix-client-element/templates/config.json.j2

@@ -3,10 +3,12 @@
 		"m.homeserver": {
 			"base_url": {{ matrix_client_element_default_hs_url | string | to_json }},
 			"server_name": {{ matrix_client_element_default_server_name | string | to_json }}
-		},
+		}
+		{% if matrix_client_element_default_is_url %},
 		"m.identity_server": {
 			"base_url": {{ matrix_client_element_default_is_url | string | to_json }}
 		}
+		{% endif %}
 	},
 	"setting_defaults": {
 		"custom_themes": {{ matrix_client_element_setting_defaults_custom_themes | to_json }}

roles/custom/matrix-client-element/vars/main.yml

@@ -5,3 +5,5 @@
 ---
 
 matrix_client_element_embedded_pages_home_url: "{{ ('' if matrix_client_element_embedded_pages_home_path is none else 'home.html') }}"
+
+matrix_client_element_url_endpoint_public: "{{ matrix_client_element_scheme }}://{{ matrix_client_element_hostname }}{{ matrix_client_element_path_prefix }}{% if matrix_client_element_path_prefix != '/' %}/{% endif %}config.json"

roles/custom/matrix-client-fluffychat/defaults/main.yml

@@ -151,7 +151,7 @@ matrix_client_fluffychat_path_prefix: /
 matrix_client_fluffychat_self_check_validate_certificates: true
 
 # Controls the default homeserver domain (not URL) used in the FluffyChat Web configuration.
-matrix_client_fluffychat_config_defaultHomeserver: ~
+matrix_client_fluffychat_config_defaultHomeserver: ~  # noqa var-naming
 
 # matrix_client_fluffychat_restart_necessary controls whether the service
 # will be restarted (when true) or merely started (when false) by the

roles/custom/matrix-client-fluffychat/tasks/self_check.yml

@@ -4,9 +4,6 @@
 
 ---
 
-- ansible.builtin.set_fact:
-    matrix_client_fluffychat_url_endpoint_public: "{{ matrix_client_fluffychat_scheme }}://{{ matrix_client_fluffychat_hostname }}/"
-
 - name: Check FluffyChat Web
   ansible.builtin.uri:
     url: "{{ matrix_client_fluffychat_url_endpoint_public }}"

roles/custom/matrix-client-fluffychat/vars/main.yml

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+matrix_client_fluffychat_url_endpoint_public: "{{ matrix_client_fluffychat_scheme }}://{{ matrix_client_fluffychat_hostname }}{{ matrix_client_fluffychat_path_prefix }}{% if matrix_client_fluffychat_path_prefix != '/' %}/{% endif %}"

roles/custom/matrix-client-schildichat/tasks/self_check.yml

@@ -6,9 +6,6 @@
 
 ---
 
-- ansible.builtin.set_fact:
-    matrix_client_schildichat_url_endpoint_public: "{{ matrix_client_schildichat_scheme }}://{{ matrix_client_schildichat_hostname }}/config.json"
-
 - name: Check SchildiChat Web
   ansible.builtin.uri:
     url: "{{ matrix_client_schildichat_url_endpoint_public }}"

roles/custom/matrix-client-schildichat/vars/main.yml

@@ -5,3 +5,5 @@
 ---
 
 matrix_client_schildichat_embedded_pages_home_url: "{{ ('' if matrix_client_schildichat_embedded_pages_home_path is none else 'home.html') }}"
+
+matrix_client_schildichat_url_endpoint_public: "{{ matrix_client_schildichat_scheme }}://{{ matrix_client_schildichat_hostname }}{{ matrix_client_schildichat_path_prefix }}{% if matrix_client_schildichat_path_prefix != '/' %}/{% endif %}config.json"

roles/custom/matrix-conduit/defaults/main.yml

@@ -154,3 +154,13 @@ matrix_conduit_turn_uris: []
 matrix_conduit_turn_secret: ''
 matrix_conduit_turn_username: ''
 matrix_conduit_turn_password: ''
+
+# matrix_conduit_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_conduit_restart_necessary: false

roles/custom/matrix-conduit/tasks/setup_install.yml

@@ -31,6 +31,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_conduit_config_result
 
 - name: Ensure Conduit support files installed
   ansible.builtin.template:
@@ -41,6 +42,7 @@
     group: "{{ matrix_group_name }}"
   with_items:
     - labels
+  register: matrix_conduit_support_files_result
 
 - name: Ensure Conduit container network is created
   community.general.docker_network:
@@ -55,13 +57,24 @@
     source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
     force_source: "{{ matrix_conduit_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_conduit_container_image_force_pull }}"
-  register: result
+  register: matrix_conduit_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_conduit_container_image_pull_result is not failed
 
 - name: Ensure matrix-conduit.service installed
   ansible.builtin.template:
     src: "{{ role_path }}/templates/systemd/matrix-conduit.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-conduit.service"
     mode: '0644'
+  register: matrix_conduit_systemd_service_result
+
+- name: Determine whether Conduit needs a restart
+  ansible.builtin.set_fact:
+    matrix_conduit_restart_necessary: >-
+      {{
+        matrix_conduit_config_result.changed | default(false)
+        or matrix_conduit_support_files_result.changed | default(false)
+        or matrix_conduit_systemd_service_result.changed | default(false)
+        or matrix_conduit_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-continuwuity/defaults/main.yml

@@ -13,7 +13,7 @@ matrix_continuwuity_enabled: true
 matrix_continuwuity_hostname: ''
 
 # renovate: datasource=docker depName=forgejo.ellis.link/continuwuation/continuwuity
-matrix_continuwuity_version: v0.5.5
+matrix_continuwuity_version: v0.5.6
 
 matrix_continuwuity_container_image: "{{ matrix_continuwuity_container_image_registry_prefix }}/continuwuation/continuwuity:{{ matrix_continuwuity_container_image_tag }}"
 matrix_continuwuity_container_image_tag: "{{ matrix_continuwuity_version }}"
@@ -208,3 +208,13 @@ matrix_continuwuity_config_url_preview_domain_contains_allowlist: []
 #   CONTINUWUITY_MAX_REQUEST_SIZE=50000000
 #   CONTINUWUITY_REQUEST_TIMEOUT=60
 matrix_continuwuity_environment_variables_extension: ''
+
+# matrix_continuwuity_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_continuwuity_restart_necessary: false

roles/custom/matrix-continuwuity/tasks/install.yml

@@ -27,6 +27,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_continuwuity_config_result
 
 - name: Ensure continuwuity support files installed
   ansible.builtin.template:
@@ -38,6 +39,7 @@
   with_items:
     - labels
     - env
+  register: matrix_continuwuity_support_files_result
 
 - name: Ensure continuwuity container network is created
   community.general.docker_network:
@@ -52,13 +54,24 @@
     source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
     force_source: "{{ matrix_continuwuity_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_continuwuity_container_image_force_pull }}"
-  register: result
+  register: matrix_continuwuity_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_continuwuity_container_image_pull_result is not failed
 
 - name: Ensure matrix-continuwuity.service installed
   ansible.builtin.template:
     src: "{{ role_path }}/templates/systemd/matrix-continuwuity.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-continuwuity.service"
     mode: '0644'
+  register: matrix_continuwuity_systemd_service_result
+
+- name: Determine whether continuwuity needs a restart
+  ansible.builtin.set_fact:
+    matrix_continuwuity_restart_necessary: >-
+      {{
+        matrix_continuwuity_config_result.changed | default(false)
+        or matrix_continuwuity_support_files_result.changed | default(false)
+        or matrix_continuwuity_systemd_service_result.changed | default(false)
+        or matrix_continuwuity_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-dendrite/defaults/main.yml

@@ -361,3 +361,13 @@ matrix_dendrite_media_api_max_thumbnail_generators: 10
 
 # Controls whether the full-text search engine is enabled
 matrix_dendrite_sync_api_search_enabled: false
+
+# matrix_dendrite_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_dendrite_restart_necessary: false

roles/custom/matrix-dendrite/tasks/setup_install.yml

@@ -55,10 +55,10 @@
     force_source: "{{ matrix_dendrite_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_dendrite_container_image_force_pull }}"
   when: "not matrix_dendrite_container_image_self_build | bool"
-  register: result
+  register: matrix_dendrite_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_dendrite_container_image_pull_result is not failed
 
 # We do this so that the signing key would get generated.
 # We don't use the `docker_container` module, because using it with `cap_drop` requires
@@ -89,6 +89,7 @@
     mode: '0644'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_dendrite_config_result
 
 - when: "matrix_dendrite_container_image_self_build | bool"
   block:
@@ -139,6 +140,21 @@
     - src: bin/create-account.j2
       dest: "{{ matrix_dendrite_bin_path }}/create-account"
       mode: "0750"
-    - src: systemd/matrix-dendrite.service.j2
+  register: matrix_dendrite_support_files_result
-      dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-dendrite.service"
+
-      mode: "0644"
+- name: Ensure matrix-dendrite.service installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-dendrite.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-dendrite.service"
+    mode: '0644'
+  register: matrix_dendrite_systemd_service_result
+
+- name: Determine whether Dendrite needs a restart
+  ansible.builtin.set_fact:
+    matrix_dendrite_restart_necessary: >-
+      {{
+        matrix_dendrite_config_result.changed | default(false)
+        or matrix_dendrite_support_files_result.changed | default(false)
+        or matrix_dendrite_systemd_service_result.changed | default(false)
+        or matrix_dendrite_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-element-admin/defaults/main.yml

@@ -11,7 +11,7 @@
 matrix_element_admin_enabled: true
 
 # renovate: datasource=docker depName=oci.element.io/element-admin
-matrix_element_admin_version: 0.1.10
+matrix_element_admin_version: 0.1.11
 
 matrix_element_admin_scheme: https
 

roles/custom/matrix-element-call/defaults/main.yml

@@ -21,7 +21,7 @@ matrix_element_call_enabled: false
 matrix_rtc_enabled: "{{ matrix_element_call_enabled }}"
 
 # renovate: datasource=docker depName=ghcr.io/element-hq/element-call
-matrix_element_call_version: v0.17.0
+matrix_element_call_version: v0.18.0
 
 matrix_element_call_scheme: https
 
@@ -153,3 +153,13 @@ matrix_element_call_config_default_server_config_m_homeserver_server_name: "{{ m
 
 # Controls the livekit/livekit_service_url property in the config.json file.
 matrix_element_call_config_livekit_livekit_service_url: ""
+
+# matrix_element_call_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_element_call_restart_necessary: false

roles/custom/matrix-element-call/tasks/install.yml

@@ -23,6 +23,7 @@
     mode: '0640'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_element_call_config_result
 
 - name: Ensure Element Call container labels file is in place
   ansible.builtin.template:
@@ -31,16 +32,17 @@
     mode: '0640'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_element_call_support_files_result
 
 - name: Ensure Element Call container image is pulled
   community.docker.docker_image:
     name: "{{ matrix_element_call_container_image }}"
     source: pull
     force_source: "{{ matrix_element_call_container_image_force_pull }}"
-  register: element_call_image_result
+  register: matrix_element_call_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: element_call_image_result is not failed
+  until: matrix_element_call_container_image_pull_result is not failed
 
 - name: Ensure Element Call container network is created
   community.general.docker_network:
@@ -54,3 +56,14 @@
     src: "{{ role_path }}/templates/systemd/matrix-element-call.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-element-call.service"
     mode: '0644'
+  register: matrix_element_call_systemd_service_result
+
+- name: Determine whether Element Call needs a restart
+  ansible.builtin.set_fact:
+    matrix_element_call_restart_necessary: >-
+      {{
+        matrix_element_call_config_result.changed | default(false)
+        or matrix_element_call_support_files_result.changed | default(false)
+        or matrix_element_call_systemd_service_result.changed | default(false)
+        or matrix_element_call_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-ldap-registration-proxy/tasks/setup_install.yml

@@ -40,6 +40,7 @@
       path: "{{ matrix_ldap_registration_proxy_container_src_files_path }}"
       pull: true
   when: true
+  register: matrix_ldap_registration_proxy_container_image_build_result
 
 - name: Ensure matrix_ldap_registration_proxy config installed
   ansible.builtin.template:
@@ -82,4 +83,5 @@
         matrix_ldap_registration_proxy_config_result.changed | default(false)
         or matrix_ldap_registration_proxy_support_files_result.changed | default(false)
         or matrix_ldap_registration_proxy_systemd_service_result.changed | default(false)
+        or matrix_ldap_registration_proxy_container_image_build_result.changed | default(false)
       }}

roles/custom/matrix-matrixto/tasks/install.yml

@@ -45,6 +45,7 @@
       path: "{{ matrix_matrixto_container_image_self_build_src_files_path }}"
       pull: true
       args:
+  register: matrix_matrixto_container_image_build_result
 
 - name: Ensure Matrix.to container network is created via community.docker.docker_network
   when: devture_systemd_docker_base_container_network_creation_method == 'ansible-module'
@@ -79,4 +80,5 @@
       {{
         matrix_matrixto_support_files_result.changed | default(false)
         or matrix_matrixto_systemd_service_result.changed | default(false)
+        or matrix_matrixto_container_image_build_result.changed | default(false)
       }}

roles/custom/matrix-media-repo/defaults/main.yml

@@ -939,3 +939,13 @@ matrix_media_repo_pgo_submit_key: "INSERT_VALUE_HERE"
 
 # Specifies whether the homeserver supports federation
 matrix_media_repo_homeserver_federation_enabled: true
+
+# matrix_media_repo_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_media_repo_restart_necessary: false

roles/custom/matrix-media-repo/tasks/setup_install.yml

@@ -35,6 +35,7 @@
   with_items:
     - env
     - labels
+  register: matrix_media_repo_support_files_result
 
 - name: Ensure media-repo configuration installed
   ansible.builtin.template:
@@ -43,6 +44,7 @@
     mode: '0640'
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
+  register: matrix_media_repo_config_result
 
 - name: Ensure media-repo Docker image is pulled
   community.docker.docker_image:
@@ -51,10 +53,10 @@
     force_source: "{{ matrix_media_repo_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_media_repo_container_image_force_pull }}"
   when: "not matrix_media_repo_container_image_self_build | bool"
-  register: result
+  register: matrix_media_repo_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_media_repo_container_image_pull_result is not failed
 
 - when: "matrix_media_repo_container_image_self_build | bool"
   block:
@@ -153,3 +155,14 @@
     src: "{{ role_path }}/templates/media-repo/systemd/matrix-media-repo.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/{{ matrix_media_repo_identifier }}.service"
     mode: '0640'
+  register: matrix_media_repo_systemd_service_result
+
+- name: Determine whether media-repo needs a restart
+  ansible.builtin.set_fact:
+    matrix_media_repo_restart_necessary: >-
+      {{
+        matrix_media_repo_config_result.changed | default(false)
+        or matrix_media_repo_support_files_result.changed | default(false)
+        or matrix_media_repo_systemd_service_result.changed | default(false)
+        or matrix_media_repo_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-synapse-admin/defaults/main.yml

@@ -28,7 +28,7 @@ matrix_synapse_admin_container_image_self_build: false
 matrix_synapse_admin_container_image_self_build_repo: "https://github.com/etkecc/synapse-admin.git"
 
 # renovate: datasource=docker depName=ghcr.io/etkecc/synapse-admin
-matrix_synapse_admin_version: v0.11.1-etke53
+matrix_synapse_admin_version: v0.11.4-etke54
 matrix_synapse_admin_container_image: "{{ matrix_synapse_admin_container_image_registry_prefix }}etkecc/synapse-admin:{{ matrix_synapse_admin_version }}"
 matrix_synapse_admin_container_image_registry_prefix: "{{ 'localhost/' if matrix_synapse_admin_container_image_self_build else matrix_synapse_admin_container_image_registry_prefix_upstream }}"
 matrix_synapse_admin_container_image_registry_prefix_upstream: "{{ matrix_synapse_admin_container_image_registry_prefix_upstream_default }}"

roles/custom/matrix-synapse-admin/tasks/validate_config.yml

@@ -6,6 +6,16 @@
 
 ---
 
+- name: Fail if matrix-synapse-admin is enabled for a non-Synapse homeserver
+  ansible.builtin.fail:
+    msg: >-
+      matrix-synapse-admin can only be used with the Synapse homeserver implementation.
+      Your configuration has `matrix_synapse_admin_enabled: true`, but `matrix_homeserver_implementation` is set to `{{ matrix_homeserver_implementation }}`.
+      Disable matrix-synapse-admin or switch to Synapse.
+  when:
+    - matrix_synapse_admin_enabled | bool
+    - matrix_homeserver_implementation != 'synapse'
+
 - name: (Deprecation) Catch and report renamed matrix-synapse-admin settings
   ansible.builtin.fail:
     msg: >-

roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml

@@ -1,373 +0,0 @@
-# SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
-# SPDX-FileCopyrightText: 2023 - 2024 Nikita Chernyi
-# SPDX-FileCopyrightText: 2023 Dan Arnfield
-# SPDX-FileCopyrightText: 2023 Samuel Meenzen
-# SPDX-FileCopyrightText: 2024 Charles Wright
-# SPDX-FileCopyrightText: 2024 David Mehren
-# SPDX-FileCopyrightText: 2024 Michael Hollister
-# SPDX-FileCopyrightText: 2024 - 2025 Catalan Lover <catalanlover@protonmail.com>
-#
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
----
-
-# matrix-synapse-reverse-proxy-companion is a role which brings up a containerized nginx webserver which helps with reverse-proxying to Synapse when workers are enabled.
-#
-# When Synapse is NOT running in worker-mode, reverse-proxying is relatively simple (everything goes to `matrix-synapse:XXXX`).
-# In such cases, using this reverse-proxy companion is possible, but unnecessary - it's one more service in the stack, which also impacts performance a bit.
-#
-# When Synapse workers are enabled, however, the reverse-proxying configuration is much more complicated - certain requests need to go to certain workers, etc.
-# matrix-synapse-reverse-proxy-companion is the central place services that need to reach Synapse could be pointed to.
-#
-# Project source code URL: https://github.com/nginx/nginx
-
-matrix_synapse_reverse_proxy_companion_enabled: true
-
-# renovate: datasource=docker depName=nginx
-matrix_synapse_reverse_proxy_companion_version: 1.29.5-alpine
-
-matrix_synapse_reverse_proxy_companion_base_path: "{{ matrix_synapse_base_path }}/reverse-proxy-companion"
-matrix_synapse_reverse_proxy_companion_confd_path: "{{ matrix_synapse_reverse_proxy_companion_base_path }}/conf.d"
-matrix_synapse_reverse_proxy_companion_njs_path: "{{ matrix_synapse_reverse_proxy_companion_base_path }}/njs"
-
-# List of systemd services that matrix-synapse-reverse-proxy-companion.service depends on
-matrix_synapse_reverse_proxy_companion_systemd_required_services_list: "{{ matrix_synapse_reverse_proxy_companion_systemd_required_services_list_default + matrix_synapse_reverse_proxy_companion_systemd_required_services_list_auto + matrix_synapse_reverse_proxy_companion_systemd_required_services_list_custom }}"
-matrix_synapse_reverse_proxy_companion_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
-matrix_synapse_reverse_proxy_companion_systemd_required_services_list_auto: []
-matrix_synapse_reverse_proxy_companion_systemd_required_services_list_custom: []
-
-# List of systemd services that matrix-synapse-reverse-proxy-companion.service wants
-matrix_synapse_reverse_proxy_companion_systemd_wanted_services_list: ['matrix-synapse.service']
-
-# We use an official nginx image, which we fix-up to run unprivileged.
-# An alternative would be an `nginxinc/nginx-unprivileged` image, but
-# that is frequently out of date.
-matrix_synapse_reverse_proxy_companion_container_image: "{{ matrix_synapse_reverse_proxy_companion_container_image_registry_prefix }}nginx:{{ matrix_synapse_reverse_proxy_companion_container_image_tag }}"
-matrix_synapse_reverse_proxy_companion_container_image_registry_prefix: "{{ matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream }}"
-matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream: "{{ matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream_default }}"
-matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream_default: "docker.io/"
-matrix_synapse_reverse_proxy_companion_container_image_tag: "{{ matrix_synapse_reverse_proxy_companion_version }}"
-matrix_synapse_reverse_proxy_companion_container_image_force_pull: "{{ matrix_synapse_reverse_proxy_companion_container_image.endswith(':latest') }}"
-
-matrix_synapse_reverse_proxy_companion_container_network: ""
-
-# A list of additional container networks that matrix-synapse-reverse-proxy-companion would be connected to.
-# The playbook does not create these networks, so make sure they already exist.
-matrix_synapse_reverse_proxy_companion_container_additional_networks: "{{ matrix_synapse_reverse_proxy_companion_container_additional_networks_auto + matrix_synapse_reverse_proxy_companion_container_additional_networks_custom }}"
-matrix_synapse_reverse_proxy_companion_container_additional_networks_auto: []
-matrix_synapse_reverse_proxy_companion_container_additional_networks_custom: []
-
-# Controls whether the matrix-synapse-reverse-proxy-companion container exposes its HTTP Client-Server API port (tcp/8008 in the container).
-#
-# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8008"), or empty string to not expose.
-matrix_synapse_reverse_proxy_companion_container_client_api_host_bind_port: ''
-
-# Controls whether the matrix-synapse-reverse-proxy-companion container exposes its HTTP Federation (Server-Server) API port (tcp/8048 in the container).
-#
-# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8048"), or empty string to not expose.
-matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port: ''
-
-# matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
-# See `../templates/labels.j2` for details.
-#
-# To inject your own other container labels, see `matrix_synapse_reverse_proxy_companion_container_labels_additional_labels`.
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled: true
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_docker_network: "{{ matrix_synapse_reverse_proxy_companion_container_network }}"
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints: web-secure
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver: default  # noqa var-naming
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname: ''
-
-# Controls whether a compression middleware will be injected into the middlewares list.
-# This compression middleware is supposed to be defined elsewhere (using labels or a File provider, etc.) and is merely referenced by this router.
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_enabled: false
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_name: ""
-
-# Controls whether labels will be added that expose the Client-Server API on a public Traefik entrypoint.
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_enabled: true
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_path_prefix: /_matrix
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_path_prefix }}`)"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_priority: 0
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_entrypoints: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_tls: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_entrypoints != 'web' }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
-
-# Controls whether labels will be added that expose the Client-Server API on the internal Traefik entrypoint.
-# This is similar to `matrix_synapse_container_labels_public_client_api_enabled`, but the entrypoint and intent is different.
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_enabled: false
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_path_prefix: "{{ matrix_synapse_container_labels_public_client_api_traefik_path_prefix }}"
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_rule: "PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_path_prefix }}`)"
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_priority: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_priority }}"
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_entrypoints: ""
-
-# Controls whether labels will be added that expose the /_synapse/client paths
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_enabled: true
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_path_prefix: /_synapse/client
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_path_prefix }}`)"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_priority: 0
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_entrypoints: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_tls: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_entrypoints != 'web' }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
-
-# Controls whether labels will be added that expose the /_synapse/admin paths
-# Following these recommendations (https://github.com/element-hq/synapse/blob/master/docs/reverse_proxy.md), by default, we don't.
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_enabled: false
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_path_prefix: /_synapse/admin
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_path_prefix }}`)"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_priority: 0
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_entrypoints: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_tls: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_entrypoints != 'web' }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
-
-# Controls whether labels will be added that expose the /_synapse/admin paths on the internal Traefik entrypoint.
-# This is similar to `matrix_synapse_container_labels_public_client_api_enabled`, but the entrypoint and intent is different.
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_enabled: false
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_path_prefix: "{{ matrix_synapse_container_labels_internal_client_synapse_admin_api_traefik_path_prefix }}"
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_rule: "PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_path_prefix }}`)"
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_priority: 0
-matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_entrypoints: ""
-
-# Controls whether labels will be added that expose the Server-Server API (Federation API).
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_enabled: "{{ matrix_synapse_reverse_proxy_companion_federation_api_enabled }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_path_prefix: /_matrix
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_path_prefix }}`)"
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_priority: 0
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_entrypoints: ''
-# TLS is force-enabled here, because the spec (https://spec.matrix.org/v1.9/server-server-api/#tls) says that the federation API must use HTTPS.
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_tls: true
-matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
-
-# matrix_synapse_reverse_proxy_companion_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
-# See `../templates/labels.j2` for details.
-#
-# Example:
-# matrix_synapse_reverse_proxy_companion_container_labels_additional_labels: |
-#   my.label=1
-#   another.label="here"
-matrix_synapse_reverse_proxy_companion_container_labels_additional_labels: ''
-
-# A list of extra arguments to pass to the container
-# Also see `matrix_synapse_reverse_proxy_companion_container_arguments`
-matrix_synapse_reverse_proxy_companion_container_extra_arguments: []
-
-# matrix_synapse_reverse_proxy_companion_container_extra_arguments_auto is a list of extra arguments to pass to the container.
-# This list is managed by the playbook. You're not meant to override this variable.
-# If you'd like to inject your own arguments, see `matrix_synapse_reverse_proxy_companion_container_extra_arguments`.
-matrix_synapse_reverse_proxy_companion_container_extra_arguments_auto: []
-
-# matrix_synapse_reverse_proxy_companion_container_arguments holds the final list of extra arguments to pass to the container.
-# You're not meant to override this variable.
-# If you'd like to inject your own arguments, see `matrix_synapse_reverse_proxy_companion_container_extra_arguments`.
-matrix_synapse_reverse_proxy_companion_container_arguments: "{{ matrix_synapse_reverse_proxy_companion_container_extra_arguments + matrix_synapse_reverse_proxy_companion_container_extra_arguments_auto }}"
-
-# The amount of worker processes and connections
-# Consider increasing these when you are expecting high amounts of traffic
-# http://nginx.org/en/docs/ngx_core_module.html#worker_connections
-matrix_synapse_reverse_proxy_companion_worker_processes: auto
-matrix_synapse_reverse_proxy_companion_worker_connections: 1024
-
-# Option to disable the access log
-matrix_synapse_reverse_proxy_companion_access_log_enabled: true
-
-# Controls whether to send access logs to a remote syslog-compatible server
-matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_enabled: false
-matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_server_port: ''
-# This is intentionally different. The maximum allowed length is 32 characters and dashes are not allowed.
-matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_tag: matrix_synapse_rev_proxy_comp
-
-# The tmpfs at /tmp needs to be large enough to handle multiple concurrent file uploads.
-matrix_synapse_reverse_proxy_companion_tmp_directory_size_mb: "{{ (matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb | int) * 50 }}"
-matrix_synapse_reverse_proxy_companion_tmp_cache_directory_size_mb: "{{ (matrix_synapse_reverse_proxy_companion_synapse_cache_max_size_mb | int) * 2 }}"
-
-# A list of strings containing additional configuration blocks to add to the nginx server configuration (nginx.conf).
-# for big matrixservers to enlarge the number of open files to prevent timeouts
-# matrix_synapse_reverse_proxy_companion_additional_configuration_blocks:
-#  - 'worker_rlimit_nofile 30000;'
-matrix_synapse_reverse_proxy_companion_additional_configuration_blocks: []
-
-# A list of strings containing additional configuration blocks to add to the nginx event server configuration (nginx.conf).
-matrix_synapse_reverse_proxy_companion_event_additional_configuration_blocks: []
-
-# A list of strings containing additional configuration blocks to add to the nginx http's server configuration (nginx-http.conf).
-matrix_synapse_reverse_proxy_companion_http_additional_server_configuration_blocks: []
-
-# To increase request timeout in NGINX using proxy_read_timeout, proxy_connect_timeout, proxy_send_timeout, send_timeout directives
-# Nginx Default: proxy_connect_timeout 60s;   #Defines a timeout for establishing a connection with a proxied server
-# Nginx Default: proxy_send_timeout 60s;      #Sets a timeout for transmitting a request to the proxied server.
-# Nginx Default: proxy_read_timeout 60s;      #Defines a timeout for reading a response from the proxied server.
-# Nginx Default: send_timeout 60s;            #Sets a timeout for transmitting a response to the client.
-#
-# For more information visit:
-# http://nginx.org/en/docs/http/ngx_http_proxy_module.html
-# http://nginx.org/en/docs/http/ngx_http_core_module.html#send_timeout
-# https://www.nginx.com/resources/wiki/start/topics/examples/fullexample2/
-#
-# Here we are sticking with nginx default values change this value carefully.
-matrix_synapse_reverse_proxy_companion_proxy_connect_timeout: 60
-matrix_synapse_reverse_proxy_companion_proxy_send_timeout: 60
-matrix_synapse_reverse_proxy_companion_proxy_read_timeout: 60
-matrix_synapse_reverse_proxy_companion_send_timeout: 60
-
-# For OCSP purposes, we need to define a resolver at the `server{}` level or `http{}` level (we do the latter).
-#
-# Otherwise, we get warnings like this:
-# > [warn] 22#22: no resolver defined to resolve r3.o.lencr.org while requesting certificate status, responder: r3.o.lencr.org, certificate: "/matrix/ssl/config/live/…/fullchain.pem"
-#
-# We point it to the internal Docker resolver, which likely delegates to nameservers defined in `/etc/resolv.conf`.
-matrix_synapse_reverse_proxy_companion_http_level_resolver: 127.0.0.11
-
-matrix_synapse_reverse_proxy_companion_hostname: "matrix-synapse-reverse-proxy-companion"
-
-# matrix_synapse_reverse_proxy_companion_client_api_addr specifies the address where the Client-Server API is
-matrix_synapse_reverse_proxy_companion_client_api_addr: 'matrix-synapse:{{ matrix_synapse_container_client_api_port }}'
-
-# The maximum body size for client requests to any of the endpoints on the Client-Server API.
-# This needs to be equal or higher than the maximum upload size accepted by Synapse.
-matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb: 100
-
-# The buffer size for client requests to any of the endpoints on the Client-Server API.
-matrix_synapse_reverse_proxy_companion_client_api_client_body_buffer_size_mb: "{{ matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb }}"
-
-# matrix_synapse_reverse_proxy_companion_federation_api_enabled specifies whether reverse proxying for the Federation (Server-Server) API should be done
-matrix_synapse_reverse_proxy_companion_federation_api_enabled: true
-# matrix_synapse_reverse_proxy_companion_federation_api_addr specifies the address where the Federation (Server-Server) API is
-matrix_synapse_reverse_proxy_companion_federation_api_addr: 'matrix-synapse:{{ matrix_synapse_container_federation_api_plain_port }}'
-
-# The maximum body size for client requests to any of the endpoints on the Federation API.
-# We auto-calculate this based on the Client-Server API's maximum body size, but use a minimum value to ensure we don't go to low.
-matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb: "{{ [matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb_minimum, (matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb | int) * 3] | max }}"
-matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb_minimum: 100
-
-# The buffer size for client requests to any of the endpoints on the Federation API.
-matrix_synapse_reverse_proxy_companion_federation_api_client_body_buffer_size_mb: "{{ matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb }}"
-
-# A list of strings containing additional configuration blocks to add to the nginx vhost handling the Synapse Client-Server API
-matrix_synapse_reverse_proxy_companion_synapse_client_api_additional_server_configuration_blocks: []
-
-# A list of strings containing additional configuration blocks to add to the nginx vhost handling the Synapse Federation (Server-Server) API
-matrix_synapse_reverse_proxy_companion_synapse_federation_api_additional_server_configuration_blocks: []
-
-
-# synapse worker activation and endpoint mappings.
-# These are all populated via Ansible group variables.
-matrix_synapse_reverse_proxy_companion_synapse_workers_enabled: false
-matrix_synapse_reverse_proxy_companion_synapse_workers_list: []
-matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_room_worker_federation_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_federation_reader_federation_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_to_device_stream_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_account_data_stream_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_receipts_stream_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations: []
-matrix_synapse_reverse_proxy_companion_synapse_user_dir_locations: []
-matrix_synapse_reverse_proxy_companion_client_server_main_override_locations_regex: ^/_matrix/client/(api/v1|r0|v3|unstable)/(account/3pid/|directory/list/room/|pushrules/|rooms/[^/]+/(forget|upgrade|report)|login/sso/redirect/|register)
-matrix_synapse_reverse_proxy_companion_client_server_sso_override_locations_regex: ^(/_matrix/client/(api/v1|r0|v3|unstable)/login/sso/redirect|/_synapse/client/(pick_username|(new_user_consent|oidc/callback|pick_idp|sso_register)$))
-# Related to MSC4108 (https://github.com/matrix-org/matrix-spec-proposals/pull/4108)
-matrix_synapse_reverse_proxy_companion_client_server_qr_code_login_locations_regex: ^(/_matrix/client/(unstable|v1)/org.matrix.msc4108/rendezvous|/_synapse/client/rendezvous)$
-
-matrix_synapse_reverse_proxy_companion_federation_override_locations_regex: ^/_matrix/federation/v1/openid/userinfo$
-
-# synapse content caching
-matrix_synapse_reverse_proxy_companion_synapse_cache_enabled: false
-matrix_synapse_reverse_proxy_companion_synapse_cache_path: /tmp/synapse-cache
-matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_name: "STATIC"
-matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_size: "10m"
-matrix_synapse_reverse_proxy_companion_synapse_cache_inactive_time: "48h"
-matrix_synapse_reverse_proxy_companion_synapse_cache_max_size_mb: 1024
-matrix_synapse_reverse_proxy_companion_synapse_cache_proxy_cache_valid_time: "24h"
-
-
-# Controls whether matrix-synapse-reverse-proxy-companion trusts an upstream server's X-Forwarded-Proto header.
-# The `matrix-synapse-reverse-proxy-companion` does not terminate SSL and always expects to be fronted by another reverse-proxy server.
-# As such, it trusts the protocol scheme forwarded by the upstream proxy.
-matrix_synapse_reverse_proxy_companion_trust_forwarded_proto: true
-matrix_synapse_reverse_proxy_companion_x_forwarded_proto_value: "{{ '$http_x_forwarded_proto' if matrix_synapse_reverse_proxy_companion_trust_forwarded_proto else '$scheme' }}"
-
-
-########################################################################################
-#                                                                                      #
-# njs module                                                                           #
-#                                                                                      #
-########################################################################################
-
-# Controls whether the njs module is loaded.
-matrix_synapse_reverse_proxy_companion_njs_enabled: "{{ matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_enabled }}"
-
-########################################################################################
-#                                                                                      #
-# /njs module                                                                          #
-#                                                                                      #
-########################################################################################
-
-
-########################################################################################
-#                                                                                      #
-# Whoami-based sync worker routing                                                     #
-#                                                                                      #
-########################################################################################
-
-# Controls whether the whoami-based sync worker router is enabled.
-# When enabled, the reverse proxy will call Synapse's /_matrix/client/v3/account/whoami endpoint
-# to resolve access tokens to usernames, allowing consistent routing of requests from the same user
-# to the same sync worker regardless of which device or token they use.
-#
-# This works with any authentication system (native Synapse auth, MAS, etc.) because Synapse
-# handles the token validation internally.
-#
-# Enabled by default when there are sync workers, because sync workers benefit from user-level
-# stickiness due to their per-user in-memory caches.
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_enabled: "{{ matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'sync_worker') | list | length > 0 }}"
-
-# The whoami endpoint path (Matrix spec endpoint).
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_endpoint: /_matrix/client/v3/account/whoami
-
-# The full URL to the whoami endpoint.
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_url: "http://{{ matrix_synapse_reverse_proxy_companion_client_api_addr }}{{ matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_endpoint }}"
-
-# Cache duration (in seconds) for whoami lookup results.
-# Token -> username mappings are cached to avoid repeated whoami calls.
-# A longer TTL reduces load on Synapse but means username changes take longer to take effect.
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_cache_ttl_seconds: 3600
-
-# Size of the shared memory zone for caching whoami results (in megabytes).
-# Each cached entry is approximately 100-200 bytes.
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_cache_size_mb: 1
-
-# Controls whether verbose logging is enabled for the whoami sync worker router.
-# When enabled, logs cache hits/misses and routing decisions.
-# Useful for debugging, but should be disabled in production.
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_logging_enabled: false
-
-# The length of the access token to show in logs when logging is enabled.
-# Keeping this short is a good idea from a security perspective.
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_logging_token_length: 12
-
-# Controls whether debug response headers are added to sync requests.
-# When enabled, adds X-Sync-Worker-Router-User-Identifier and X-Sync-Worker-Router-Upstream headers.
-# Useful for debugging routing behavior, but should be disabled in production.
-matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_debug_headers_enabled: false
-
-########################################################################################
-#                                                                                      #
-# /Whoami-based sync worker routing                                                    #
-#                                                                                      #
-########################################################################################
-
-# matrix_synapse_reverse_proxy_companion_restart_necessary controls whether the service
-# will be restarted (when true) or merely started (when false) by the
-# systemd service manager role (when conditional restart is enabled).
-#
-# This value is automatically computed during installation based on whether
-# any configuration files, the systemd service file, or the container image changed.
-# The default of `false` means "no restart needed" — appropriate when the role's
-# installation tasks haven't run (e.g., due to --tags skipping them).
-matrix_synapse_reverse_proxy_companion_restart_necessary: false

roles/custom/matrix-synapse/defaults/main.yml

@@ -16,7 +16,7 @@ matrix_synapse_enabled: true
 matrix_synapse_github_org_and_repo: element-hq/synapse
 
 # renovate: datasource=docker depName=ghcr.io/element-hq/synapse
-matrix_synapse_version: v1.148.0
+matrix_synapse_version: v1.149.1
 
 matrix_synapse_username: ''
 matrix_synapse_uid: ''
@@ -125,6 +125,17 @@ matrix_synapse_ext_s3_storage_provider_data_path: "{{ matrix_synapse_ext_s3_stor
 # extra arguments to pass to s3-storage-provider script when starting Synapse container
 matrix_synapse_ext_s3_storage_provider_container_arguments: []
 
+# matrix_synapse_s3_storage_provider_restart_necessary controls whether the
+# s3-storage-provider migrate timer will be restarted (when true) or merely
+# started (when false) by the systemd service manager role (when conditional
+# restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files or the systemd service/timer files changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_synapse_s3_storage_provider_restart_necessary: false
+
 matrix_synapse_container_client_api_port: 8008
 
 # Controls the `x_forwarded` setting for the "Insecure HTTP listener (Client API)".
@@ -934,6 +945,11 @@ matrix_synapse_workers_presets:
     stream_writer_account_data_stream_workers_count: 0
     stream_writer_receipts_stream_workers_count: 0
     stream_writer_presence_stream_workers_count: 0
+    stream_writer_push_rules_stream_workers_count: 0
+    stream_writer_device_lists_stream_workers_count: 0
+    # Keep disabled by default: MSC4306/4308 thread subscriptions are unstable
+    # and disabled in upstream Synapse unless explicitly opted in.
+    stream_writer_thread_subscriptions_stream_workers_count: 0
   one-of-each:
     room_workers_count: 0
     sync_workers_count: 0
@@ -952,6 +968,11 @@ matrix_synapse_workers_presets:
     stream_writer_account_data_stream_workers_count: 1
     stream_writer_receipts_stream_workers_count: 1
     stream_writer_presence_stream_workers_count: 1
+    stream_writer_push_rules_stream_workers_count: 1
+    stream_writer_device_lists_stream_workers_count: 1
+    # Keep disabled by default: MSC4306/4308 thread subscriptions are unstable
+    # and disabled in upstream Synapse unless explicitly opted in.
+    stream_writer_thread_subscriptions_stream_workers_count: 0
   specialized-workers:
     room_workers_count: 1
     sync_workers_count: 1
@@ -970,6 +991,11 @@ matrix_synapse_workers_presets:
     stream_writer_account_data_stream_workers_count: 1
     stream_writer_receipts_stream_workers_count: 1
     stream_writer_presence_stream_workers_count: 1
+    stream_writer_push_rules_stream_workers_count: 1
+    stream_writer_device_lists_stream_workers_count: 1
+    # Keep disabled by default: MSC4306/4308 thread subscriptions are unstable
+    # and disabled in upstream Synapse unless explicitly opted in.
+    stream_writer_thread_subscriptions_stream_workers_count: 0
 
 # Controls whether the matrix-synapse container exposes the various worker ports
 # (see `port` and `metrics_port` in `matrix_synapse_workers_enabled_list`) outside of the container.
@@ -1064,6 +1090,18 @@ matrix_synapse_workers_stream_writer_receipts_stream_workers_count: "{{ matrix_s
 # The count of these workers can only be 0 or 1.
 matrix_synapse_workers_stream_writer_presence_stream_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['stream_writer_presence_stream_workers_count'] }}"
 
+# matrix_synapse_workers_stream_writer_push_rules_stream_workers_count controls how many stream writers that handle the `push_rules` stream to spawn.
+# The count of these workers can only be 0 or 1.
+matrix_synapse_workers_stream_writer_push_rules_stream_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['stream_writer_push_rules_stream_workers_count'] }}"
+
+# matrix_synapse_workers_stream_writer_device_lists_stream_workers_count controls how many stream writers that handle the `device_lists` stream to spawn.
+# More than 1 worker is also supported of this type.
+matrix_synapse_workers_stream_writer_device_lists_stream_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['stream_writer_device_lists_stream_workers_count'] }}"
+
+# matrix_synapse_workers_stream_writer_thread_subscriptions_stream_workers_count controls how many stream writers that handle the `thread_subscriptions` stream to spawn.
+# More than 1 worker is also supported of this type.
+matrix_synapse_workers_stream_writer_thread_subscriptions_stream_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['stream_writer_thread_subscriptions_stream_workers_count'] }}"
+
 # A list of stream writer workers to enable. This list is built automatically based on other variables.
 # You're encouraged to enable/disable stream writer workers by setting `matrix_synapse_workers_stream_writer_*_stream_workers_count` variables, instead of adjusting this list manually.
 matrix_synapse_workers_stream_writers: |
@@ -1081,6 +1119,12 @@ matrix_synapse_workers_stream_writers: |
     ([{'stream': 'receipts'}] * matrix_synapse_workers_stream_writer_receipts_stream_workers_count | int)
     +
     ([{'stream': 'presence'}] * matrix_synapse_workers_stream_writer_presence_stream_workers_count | int)
+    +
+    ([{'stream': 'push_rules'}] * matrix_synapse_workers_stream_writer_push_rules_stream_workers_count | int)
+    +
+    ([{'stream': 'device_lists'}] * matrix_synapse_workers_stream_writer_device_lists_stream_workers_count | int)
+    +
+    ([{'stream': 'thread_subscriptions'}] * matrix_synapse_workers_stream_writer_thread_subscriptions_stream_workers_count | int)
   }}
 
 matrix_synapse_workers_stream_writers_container_arguments: []
@@ -1241,11 +1285,21 @@ matrix_synapse_instance_map: |
 
 # Redis information
 matrix_synapse_redis_enabled: false
-matrix_synapse_redis_host: ""
-matrix_synapse_redis_port: 6379
 matrix_synapse_redis_password: ""
 matrix_synapse_redis_dbid: 0
 matrix_synapse_redis_use_tls: false
+# Connection option 1: TCP
+matrix_synapse_redis_host: ""
+matrix_synapse_redis_port: 6379
+# Connection option 2: Unix socket (takes precedence over TCP if `matrix_synapse_redis_path` is set)
+# disabled by default
+matrix_synapse_redis_path_enabled: false
+# the path to the redis socket's parent dir (/tmp, not /tmp/redis.sock file) inside the container, Synapse default's is "/tmp/redis.sock"
+matrix_synapse_redis_path: "/tmp"
+# the filename of the redis socket, inside the container, Synapse default's is "redis.sock"
+matrix_synapse_redis_path_socket: "/redis.sock"
+# the path to the redis socket on the host, e.g., "/matrix/valkey/run" (parent dir, not the socket file itself).
+matrix_synapse_redis_path_host: ""
 
 # Controls whether Synapse starts a replication listener necessary for workers.
 #
@@ -1267,6 +1321,10 @@ matrix_synapse_sentry_dsn: ""
 
 # Postgres database information
 matrix_synapse_database_txn_limit: 0
+#
+# Use this hostname for TCP-based Postgres connections.
+# When `matrix_synapse_database_socket_enabled` is true, this is ignored and
+# `matrix_synapse_database_socket_path` is used instead.
 matrix_synapse_database_host: ''
 matrix_synapse_database_port: 5432
 matrix_synapse_database_cp_min: 5
@@ -1274,6 +1332,13 @@ matrix_synapse_database_cp_max: 10
 matrix_synapse_database_user: "synapse"
 matrix_synapse_database_password: ""
 matrix_synapse_database_database: "synapse"
+# Connection option 2: Unix socket (takes precedence over TCP if enabled)
+# disabled by default
+matrix_synapse_database_socket_enabled: false
+# the path to the postgres socket's parent dir inside the container (not the socket file itself).
+matrix_synapse_database_socket_path: "/tmp/postgres"
+# the path to the postgres socket on the host, e.g., "/matrix/postgres/run" (parent dir, not the socket file itself).
+matrix_synapse_database_socket_path_host: ""
 
 matrix_synapse_turn_uris: []
 matrix_synapse_turn_shared_secret: ""
@@ -1373,6 +1438,23 @@ matrix_synapse_max_event_delay_duration: 24h
 # See https://github.com/matrix-org/matrix-spec-proposals/pull/4222
 matrix_synapse_experimental_features_msc4222_enabled: false
 
+# Controls whether to enable the MSC4306 experimental feature ("thread subscriptions").
+#
+# In current Synapse, this also enables the MSC4308 thread-subscriptions extension
+# to Sliding Sync under the same upstream feature flag.
+#
+# See:
+# - https://github.com/matrix-org/matrix-spec-proposals/pull/4306
+# - https://github.com/matrix-org/matrix-spec-proposals/pull/4308
+matrix_synapse_experimental_features_msc4306_enabled: false
+
+# Controls whether to enable the MSC4354 experimental feature (sticky events).
+#
+# This is implemented since Synapse v1.148.0 and can be used by element-call v0.17.0+
+#
+# See https://github.com/matrix-org/matrix-spec-proposals/pull/4354
+matrix_synapse_experimental_features_msc4354_enabled: false
+
 # Enable this to activate the REST auth password provider module.
 # See: https://github.com/ma1uta/matrix-synapse-rest-password-provider
 matrix_synapse_ext_password_provider_rest_auth_enabled: false
@@ -1410,6 +1492,7 @@ matrix_synapse_ext_password_provider_ldap_filter: ""
 matrix_synapse_ext_password_provider_ldap_active_directory: false
 matrix_synapse_ext_password_provider_ldap_default_domain: ""
 matrix_synapse_ext_password_provider_ldap_tls_options_validate: true
+matrix_synapse_ext_password_provider_ldap_tls_options_ca_certs_file: ""
 
 # Enable this to activate the Synapse Antispam spam-checker module.
 # See: https://github.com/t2bot/synapse-simple-antispam
@@ -1423,7 +1506,7 @@ matrix_synapse_ext_spam_checker_synapse_simple_antispam_config_blocked_homeserve
 matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: false
 matrix_synapse_ext_spam_checker_mjolnir_antispam_git_repository_url: "https://github.com/matrix-org/mjolnir"
 # renovate: datasource=docker depName=matrixdotorg/mjolnir
-matrix_synapse_ext_spam_checker_mjolnir_antispam_git_version: "v1.12.0"
+matrix_synapse_ext_spam_checker_mjolnir_antispam_git_version: "v1.12.1"
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_invites: true
 # Flag messages sent by servers/users in the ban lists as spam. Currently
 # this means that spammy messages will appear as empty to users. Default
@@ -1576,6 +1659,16 @@ matrix_s3_media_store_aws_secret_key: "your-aws-secret-key"
 matrix_s3_media_store_region: "eu-central-1"
 matrix_s3_media_store_path: "{{ matrix_synapse_media_store_path }}"
 
+# matrix_goofys_restart_necessary controls whether the Goofys service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_goofys_restart_necessary: false
+
 # Controls whether the self-check feature should validate SSL certificates.
 matrix_synapse_self_check_validate_certificates: true
 
@@ -1589,6 +1682,12 @@ matrix_synapse_server_notices_system_mxid_display_name: "Server Notices"
 matrix_synapse_server_notices_system_mxid_avatar_url: ~
 # The name of the room where server notices will be sent, this room will be created if it doesn't exist.
 matrix_synapse_server_notices_room_name: "Server Notices"
+# Optional avatar URL for the server notices room, example: mxc://example.com/abc123
+matrix_synapse_server_notices_room_avatar_url: ~
+# Optional topic for the server notices room.
+matrix_synapse_server_notices_room_topic: ~
+# If true, users will be automatically joined to the server notices room instead of being invited.
+matrix_synapse_server_notices_auto_join: false
 
 # Controls whether searching the public room list is enabled.
 matrix_synapse_enable_room_list_search: true
@@ -1710,3 +1809,399 @@ matrix_synapse_configuration: "{{ matrix_synapse_configuration_yaml | from_yaml
 # When the Matrix Authentication Service is enabled, the register-user script from this role cannot be used
 # and users will be pointed to the one provided by Matrix Authentication Service.
 matrix_synapse_register_user_script_matrix_authentication_service_path: ""
+
+
+########################################################################################
+#                                                                                      #
+# Synapse reverse-proxy companion                                                      #
+#                                                                                      #
+########################################################################################
+
+# matrix-synapse-reverse-proxy-companion is a role which brings up a containerized nginx webserver which helps with reverse-proxying to Synapse when workers are enabled.
+#
+# When Synapse is NOT running in worker-mode, reverse-proxying is relatively simple (everything goes to `matrix-synapse:XXXX`).
+# In such cases, using this reverse-proxy companion is possible, but unnecessary - it's one more service in the stack, which also impacts performance a bit.
+#
+# When Synapse workers are enabled, however, the reverse-proxying configuration is much more complicated - certain requests need to go to certain workers, etc.
+# matrix-synapse-reverse-proxy-companion is the central place services that need to reach Synapse could be pointed to.
+
+matrix_synapse_reverse_proxy_companion_enabled: "{{ matrix_synapse_enabled and matrix_synapse_workers_enabled }}"
+
+# renovate: datasource=docker depName=nginx
+matrix_synapse_reverse_proxy_companion_version: 1.29.6-alpine
+
+matrix_synapse_reverse_proxy_companion_base_path: "{{ matrix_synapse_base_path }}/reverse-proxy-companion"
+matrix_synapse_reverse_proxy_companion_confd_path: "{{ matrix_synapse_reverse_proxy_companion_base_path }}/conf.d"
+matrix_synapse_reverse_proxy_companion_njs_path: "{{ matrix_synapse_reverse_proxy_companion_base_path }}/njs"
+
+# List of systemd services that matrix-synapse-reverse-proxy-companion.service depends on
+matrix_synapse_reverse_proxy_companion_systemd_required_services_list: "{{ matrix_synapse_reverse_proxy_companion_systemd_required_services_list_default + matrix_synapse_reverse_proxy_companion_systemd_required_services_list_auto + matrix_synapse_reverse_proxy_companion_systemd_required_services_list_custom }}"
+matrix_synapse_reverse_proxy_companion_systemd_required_services_list_default: []
+matrix_synapse_reverse_proxy_companion_systemd_required_services_list_auto: []
+matrix_synapse_reverse_proxy_companion_systemd_required_services_list_custom: []
+
+# List of systemd services that matrix-synapse-reverse-proxy-companion.service wants
+matrix_synapse_reverse_proxy_companion_systemd_wanted_services_list: ['matrix-synapse.service']
+
+# We use an official nginx image, which we fix-up to run unprivileged.
+# An alternative would be an `nginxinc/nginx-unprivileged` image, but
+# that is frequently out of date.
+matrix_synapse_reverse_proxy_companion_container_image: "{{ matrix_synapse_reverse_proxy_companion_container_image_registry_prefix }}nginx:{{ matrix_synapse_reverse_proxy_companion_container_image_tag }}"
+matrix_synapse_reverse_proxy_companion_container_image_registry_prefix: "{{ matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream }}"
+matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream: "{{ matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream_default }}"
+matrix_synapse_reverse_proxy_companion_container_image_registry_prefix_upstream_default: "docker.io/"
+matrix_synapse_reverse_proxy_companion_container_image_tag: "{{ matrix_synapse_reverse_proxy_companion_version }}"
+matrix_synapse_reverse_proxy_companion_container_image_force_pull: "{{ matrix_synapse_reverse_proxy_companion_container_image.endswith(':latest') }}"
+
+matrix_synapse_reverse_proxy_companion_container_network: "{{ matrix_synapse_container_network }}"
+
+# A list of additional container networks that matrix-synapse-reverse-proxy-companion would be connected to.
+# The playbook does not create these networks, so make sure they already exist.
+matrix_synapse_reverse_proxy_companion_container_additional_networks: "{{ matrix_synapse_reverse_proxy_companion_container_additional_networks_auto + matrix_synapse_reverse_proxy_companion_container_additional_networks_custom }}"
+matrix_synapse_reverse_proxy_companion_container_additional_networks_auto: []
+matrix_synapse_reverse_proxy_companion_container_additional_networks_custom: []
+
+# Controls whether the matrix-synapse-reverse-proxy-companion container exposes its HTTP Client-Server API port (tcp/8008 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8008"), or empty string to not expose.
+matrix_synapse_reverse_proxy_companion_container_client_api_host_bind_port: ''
+
+# Controls whether the matrix-synapse-reverse-proxy-companion container exposes its HTTP Federation (Server-Server) API port (tcp/8048 in the container).
+#
+# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8048"), or empty string to not expose.
+matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port: ''
+
+# matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
+# See `../templates/labels.j2` for details.
+#
+# To inject your own other container labels, see `matrix_synapse_reverse_proxy_companion_container_labels_additional_labels`.
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_enabled: true
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_docker_network: "{{ matrix_synapse_reverse_proxy_companion_container_network }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints: web-secure
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver: default  # noqa var-naming
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname: ''
+
+# Controls whether a compression middleware will be injected into the middlewares list.
+# This compression middleware is supposed to be defined elsewhere (using labels or a File provider, etc.) and is merely referenced by this router.
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_enabled: false
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_name: ""
+
+# Controls whether labels will be added that expose the Client-Server API on a public Traefik entrypoint.
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_enabled: true
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_path_prefix: /_matrix
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_path_prefix }}`)"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_priority: 0
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_entrypoints: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_tls: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_entrypoints != 'web' }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# Controls whether labels will be added that expose the Client-Server API on the internal Traefik entrypoint.
+# This is similar to `matrix_synapse_container_labels_public_client_api_enabled`, but the entrypoint and intent is different.
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_enabled: "{{ matrix_synapse_container_labels_internal_client_api_enabled }}"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_path_prefix: "{{ matrix_synapse_container_labels_public_client_api_traefik_path_prefix }}"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_rule: "PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_path_prefix }}`)"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_priority: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_api_traefik_priority }}"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_traefik_entrypoints: "{{ matrix_synapse_container_labels_internal_client_api_traefik_entrypoints }}"
+
+# Controls whether labels will be added that expose the /_synapse/client paths
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_enabled: "{{ matrix_synapse_container_labels_public_client_synapse_client_api_enabled }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_path_prefix: /_synapse/client
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_path_prefix }}`)"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_priority: 0
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_entrypoints: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_tls: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_entrypoints != 'web' }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# Controls whether labels will be added that expose the /_synapse/admin paths
+# Following these recommendations (https://github.com/element-hq/synapse/blob/master/docs/reverse_proxy.md), by default, we don't.
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_enabled: "{{ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_path_prefix: /_synapse/admin
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_path_prefix }}`)"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_priority: 0
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_entrypoints: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_tls: "{{ matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_entrypoints != 'web' }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# Controls whether labels will be added that expose the /_synapse/admin paths on the internal Traefik entrypoint.
+# This is similar to `matrix_synapse_container_labels_public_client_api_enabled`, but the entrypoint and intent is different.
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_enabled: "{{ matrix_synapse_container_labels_internal_client_synapse_admin_api_enabled }}"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_path_prefix: "{{ matrix_synapse_container_labels_internal_client_synapse_admin_api_traefik_path_prefix }}"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_rule: "PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_path_prefix }}`)"
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_priority: 0
+matrix_synapse_reverse_proxy_companion_container_labels_internal_client_synapse_admin_api_traefik_entrypoints: ""
+
+# Controls whether labels will be added that expose the Server-Server API (Federation API).
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_enabled: "{{ matrix_synapse_reverse_proxy_companion_federation_api_enabled }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_hostname: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_path_prefix: /_matrix
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_rule: "Host(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_path_prefix }}`)"
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_priority: 0
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_entrypoints: "{{ matrix_synapse_container_labels_public_federation_api_traefik_entrypoints }}"
+# TLS is force-enabled here, because the spec (https://spec.matrix.org/v1.9/server-server-api/#tls) says that the federation API must use HTTPS.
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_tls: "{{ matrix_synapse_container_labels_public_federation_api_traefik_tls }}"
+matrix_synapse_reverse_proxy_companion_container_labels_public_federation_api_traefik_tls_certResolver: "{{ matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# matrix_synapse_reverse_proxy_companion_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
+# See `../templates/labels.j2` for details.
+#
+# Example:
+# matrix_synapse_reverse_proxy_companion_container_labels_additional_labels: |
+#   my.label=1
+#   another.label="here"
+matrix_synapse_reverse_proxy_companion_container_labels_additional_labels: ''
+
+# A list of extra arguments to pass to the container
+# Also see `matrix_synapse_reverse_proxy_companion_container_arguments`
+matrix_synapse_reverse_proxy_companion_container_extra_arguments: []
+
+# matrix_synapse_reverse_proxy_companion_container_extra_arguments_auto is a list of extra arguments to pass to the container.
+# This list is managed by the playbook. You're not meant to override this variable.
+# If you'd like to inject your own arguments, see `matrix_synapse_reverse_proxy_companion_container_extra_arguments`.
+matrix_synapse_reverse_proxy_companion_container_extra_arguments_auto: []
+
+# matrix_synapse_reverse_proxy_companion_container_arguments holds the final list of extra arguments to pass to the container.
+# You're not meant to override this variable.
+# If you'd like to inject your own arguments, see `matrix_synapse_reverse_proxy_companion_container_extra_arguments`.
+matrix_synapse_reverse_proxy_companion_container_arguments: "{{ matrix_synapse_reverse_proxy_companion_container_extra_arguments + matrix_synapse_reverse_proxy_companion_container_extra_arguments_auto }}"
+
+# The amount of worker processes and connections
+# Consider increasing these when you are expecting high amounts of traffic
+# http://nginx.org/en/docs/ngx_core_module.html#worker_connections
+matrix_synapse_reverse_proxy_companion_worker_processes: auto
+matrix_synapse_reverse_proxy_companion_worker_connections: 1024
+
+# Option to disable the access log
+matrix_synapse_reverse_proxy_companion_access_log_enabled: true
+
+# Controls the regular nginx access log format used for `/var/log/nginx/access.log`.
+# `routing_debug` is the default because it includes the chosen upstream label,
+# the resolved backend address, and timing data, which makes it much easier to
+# verify request routing in worker deployments.
+# This does not affect the separate syslog integration format used by prometheus-nginxlog-exporter.
+matrix_synapse_reverse_proxy_companion_access_log_format: routing_debug
+
+# The available values for `matrix_synapse_reverse_proxy_companion_access_log_format`.
+# You can override this map to define custom formats, but that is fragile and discouraged.
+matrix_synapse_reverse_proxy_companion_access_log_format_presets:
+  main:
+    - '$remote_addr - $remote_user [$time_local] "$request"'
+    - '$status $body_bytes_sent "$http_referer"'
+    - ' "$http_user_agent" "$http_x_forwarded_for"'
+  routing_debug:
+    - '$remote_addr - $remote_user [$time_local] "$request"'
+    - '$status $body_bytes_sent "$http_referer"'
+    - ' "$http_user_agent" "$http_x_forwarded_for"'
+    - ' "$host" "$matrix_upstream_label" "$upstream_addr" "$upstream_status" "$request_time" "$upstream_response_time"'
+
+# Controls whether to send access logs to a remote syslog-compatible server
+matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_enabled: false
+matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_server_port: ''
+# This is intentionally different. The maximum allowed length is 32 characters and dashes are not allowed.
+matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_tag: matrix_synapse_rev_proxy_comp
+
+# The tmpfs at /tmp needs to be large enough to handle multiple concurrent file uploads.
+matrix_synapse_reverse_proxy_companion_tmp_directory_size_mb: "{{ (matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb | int) * 50 }}"
+matrix_synapse_reverse_proxy_companion_tmp_cache_directory_size_mb: "{{ (matrix_synapse_reverse_proxy_companion_synapse_cache_max_size_mb | int) * 2 }}"
+
+# A list of strings containing additional configuration blocks to add to the nginx server configuration (nginx.conf).
+# for big matrixservers to enlarge the number of open files to prevent timeouts
+# matrix_synapse_reverse_proxy_companion_additional_configuration_blocks:
+#  - 'worker_rlimit_nofile 30000;'
+matrix_synapse_reverse_proxy_companion_additional_configuration_blocks: []
+
+# A list of strings containing additional configuration blocks to add to the nginx event server configuration (nginx.conf).
+matrix_synapse_reverse_proxy_companion_event_additional_configuration_blocks: []
+
+# A list of strings containing additional configuration blocks to add to the nginx http's server configuration (nginx-http.conf).
+matrix_synapse_reverse_proxy_companion_http_additional_server_configuration_blocks: []
+
+# To increase request timeout in NGINX using proxy_read_timeout, proxy_connect_timeout, proxy_send_timeout, send_timeout directives
+# Nginx Default: proxy_connect_timeout 60s;   #Defines a timeout for establishing a connection with a proxied server
+# Nginx Default: proxy_send_timeout 60s;      #Sets a timeout for transmitting a request to the proxied server.
+# Nginx Default: proxy_read_timeout 60s;      #Defines a timeout for reading a response from the proxied server.
+# Nginx Default: send_timeout 60s;            #Sets a timeout for transmitting a response to the client.
+#
+# For more information visit:
+# http://nginx.org/en/docs/http/ngx_http_proxy_module.html
+# http://nginx.org/en/docs/http/ngx_http_core_module.html#send_timeout
+# https://www.nginx.com/resources/wiki/start/topics/examples/fullexample2/
+#
+# Here we are sticking with nginx default values change this value carefully.
+matrix_synapse_reverse_proxy_companion_proxy_connect_timeout: 60
+matrix_synapse_reverse_proxy_companion_proxy_send_timeout: 60
+matrix_synapse_reverse_proxy_companion_proxy_read_timeout: 60
+matrix_synapse_reverse_proxy_companion_send_timeout: 60
+
+# For OCSP purposes, we need to define a resolver at the `server{}` level or `http{}` level (we do the latter).
+#
+# Otherwise, we get warnings like this:
+# > [warn] 22#22: no resolver defined to resolve r3.o.lencr.org while requesting certificate status, responder: r3.o.lencr.org, certificate: "/matrix/ssl/config/live/…/fullchain.pem"
+#
+# We point it to the internal Docker resolver, which likely delegates to nameservers defined in `/etc/resolv.conf`.
+matrix_synapse_reverse_proxy_companion_http_level_resolver: 127.0.0.11
+
+matrix_synapse_reverse_proxy_companion_hostname: "matrix-synapse-reverse-proxy-companion"
+
+# matrix_synapse_reverse_proxy_companion_client_api_addr specifies the address where the Client-Server API is
+matrix_synapse_reverse_proxy_companion_client_api_addr: 'matrix-synapse:{{ matrix_synapse_container_client_api_port }}'
+
+# The maximum body size for client requests to any of the endpoints on the Client-Server API.
+# This needs to be equal or higher than the maximum upload size accepted by Synapse.
+matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb: "{{ matrix_synapse_max_upload_size_mb }}"
+
+# The buffer size for client requests to any of the endpoints on the Client-Server API.
+matrix_synapse_reverse_proxy_companion_client_api_client_body_buffer_size_mb: "{{ matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb }}"
+
+# matrix_synapse_reverse_proxy_companion_federation_api_enabled specifies whether reverse proxying for the Federation (Server-Server) API should be done
+matrix_synapse_reverse_proxy_companion_federation_api_enabled: true
+# matrix_synapse_reverse_proxy_companion_federation_api_addr specifies the address where the Federation (Server-Server) API is
+matrix_synapse_reverse_proxy_companion_federation_api_addr: 'matrix-synapse:{{ matrix_synapse_container_federation_api_plain_port }}'
+
+# The maximum body size for client requests to any of the endpoints on the Federation API.
+# We auto-calculate this based on the Client-Server API's maximum body size, but use a minimum value to ensure we don't go to low.
+matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb: "{{ [matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb_minimum, (matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb | int) * 3] | max }}"
+matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb_minimum: 100
+
+# The buffer size for client requests to any of the endpoints on the Federation API.
+matrix_synapse_reverse_proxy_companion_federation_api_client_body_buffer_size_mb: "{{ matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb }}"
+
+# A list of strings containing additional configuration blocks to add to the nginx vhost handling the Synapse Client-Server API
+matrix_synapse_reverse_proxy_companion_synapse_client_api_additional_server_configuration_blocks: []
+
+# A list of strings containing additional configuration blocks to add to the nginx vhost handling the Synapse Federation (Server-Server) API
+matrix_synapse_reverse_proxy_companion_synapse_federation_api_additional_server_configuration_blocks: []
+
+
+# synapse worker activation and endpoint mappings.
+# These are all populated via Ansible group variables.
+# (or fall back to role-level Synapse worker defaults when not overridden)
+matrix_synapse_reverse_proxy_companion_synapse_workers_enabled: "{{ matrix_synapse_workers_enabled }}"
+matrix_synapse_reverse_proxy_companion_synapse_workers_list: "{{ matrix_synapse_workers_enabled_list }}"
+matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations: "{{ matrix_synapse_workers_room_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_room_worker_federation_locations: "{{ matrix_synapse_workers_room_worker_federation_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations: "{{ matrix_synapse_workers_sync_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations: "{{ matrix_synapse_workers_client_reader_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_federation_reader_federation_locations: "{{ matrix_synapse_workers_federation_reader_federation_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations: "{{ matrix_synapse_workers_generic_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations: "{{ matrix_synapse_workers_generic_worker_federation_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_typing_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_to_device_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_to_device_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_account_data_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_account_data_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_receipts_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_receipts_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_presence_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_push_rules_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_push_rules_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_device_lists_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_device_lists_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_stream_writer_thread_subscriptions_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_thread_subscriptions_stream_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations: "{{ matrix_synapse_workers_media_repository_endpoints | default([]) }}"
+matrix_synapse_reverse_proxy_companion_synapse_user_dir_locations: "{{ matrix_synapse_workers_user_dir_worker_client_server_endpoints | default([]) }}"
+matrix_synapse_reverse_proxy_companion_client_server_main_override_locations_regex: ^/_matrix/client/(api/v1|r0|v3|unstable)/(account/3pid/|directory/list/room/|rooms/[^/]+/(forget|upgrade|report)|register)
+matrix_synapse_reverse_proxy_companion_client_server_sso_override_locations_regex: ^/_matrix/client/(api/v1|r0|v3|unstable)/login/sso/redirect(/|$)
+# Related to MSC4108 (https://github.com/matrix-org/matrix-spec-proposals/pull/4108)
+matrix_synapse_reverse_proxy_companion_client_server_qr_code_login_locations_regex: ^(/_matrix/client/(unstable|v1)/org.matrix.msc4108/rendezvous|/_synapse/client/rendezvous)$
+
+matrix_synapse_reverse_proxy_companion_federation_override_locations_regex: ^/_matrix/federation/v1/openid/userinfo$
+
+# synapse content caching
+matrix_synapse_reverse_proxy_companion_synapse_cache_enabled: false
+matrix_synapse_reverse_proxy_companion_synapse_cache_path: /tmp/synapse-cache
+matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_name: "STATIC"
+matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_size: "10m"
+matrix_synapse_reverse_proxy_companion_synapse_cache_inactive_time: "48h"
+matrix_synapse_reverse_proxy_companion_synapse_cache_max_size_mb: 1024
+matrix_synapse_reverse_proxy_companion_synapse_cache_proxy_cache_valid_time: "24h"
+
+
+# Controls whether matrix-synapse-reverse-proxy-companion trusts an upstream server's X-Forwarded-Proto header.
+# The `matrix-synapse-reverse-proxy-companion` does not terminate SSL and always expects to be fronted by another reverse-proxy server.
+# As such, it trusts the protocol scheme forwarded by the upstream proxy.
+matrix_synapse_reverse_proxy_companion_trust_forwarded_proto: true
+matrix_synapse_reverse_proxy_companion_x_forwarded_proto_value: "{{ '$http_x_forwarded_proto' if matrix_synapse_reverse_proxy_companion_trust_forwarded_proto else '$scheme' }}"
+
+########################################################################################
+#                                                                                      #
+# /Synapse reverse-proxy companion core settings                                       #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# njs module                                                                           #
+#                                                                                      #
+########################################################################################
+
+# Controls whether the njs module is loaded.
+matrix_synapse_reverse_proxy_companion_njs_enabled: "{{ matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_enabled }}"
+
+########################################################################################
+#                                                                                      #
+# /njs module                                                                          #
+#                                                                                      #
+########################################################################################
+
+
+########################################################################################
+#                                                                                      #
+# Whoami-based sync worker routing                                                     #
+#                                                                                      #
+########################################################################################
+
+# Controls whether the whoami-based sync worker router is enabled.
+# When enabled, the reverse proxy will call Synapse's /_matrix/client/v3/account/whoami endpoint
+# to resolve access tokens to usernames, allowing consistent routing of requests from the same user
+# to the same sync worker regardless of which device or token they use.
+#
+# This works with any authentication system (native Synapse auth, MAS, etc.) because Synapse
+# handles the token validation internally.
+#
+# Enabled by default when there are sync workers, because sync workers benefit from user-level
+# stickiness due to their per-user in-memory caches.
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_enabled: "{{ matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'sync_worker') | list | length > 0 }}"
+
+# The whoami endpoint path (Matrix spec endpoint).
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_endpoint: /_matrix/client/v3/account/whoami
+
+# The full URL to the whoami endpoint.
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_url: "http://{{ matrix_synapse_reverse_proxy_companion_client_api_addr }}{{ matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_endpoint }}"
+
+# Cache duration (in seconds) for whoami lookup results.
+# Token -> username mappings are cached to avoid repeated whoami calls.
+# A longer TTL reduces load on Synapse but means username changes take longer to take effect.
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_cache_ttl_seconds: 3600
+
+# Size of the shared memory zone for caching whoami results (in megabytes).
+# Each cached entry is approximately 100-200 bytes.
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_cache_size_mb: 1
+
+# Controls whether verbose logging is enabled for the whoami sync worker router.
+# When enabled, logs cache hits/misses and routing decisions.
+# Useful for debugging, but should be disabled in production.
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_logging_enabled: false
+
+# The length of the access token to show in logs when logging is enabled.
+# Keeping this short is a good idea from a security perspective.
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_logging_token_length: 12
+
+# Controls whether debug response headers are added to sync requests.
+# When enabled, adds X-Sync-Worker-Router-User-Identifier and X-Sync-Worker-Router-Upstream headers.
+# Useful for debugging routing behavior, but should be disabled in production.
+matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_debug_headers_enabled: false
+
+########################################################################################
+#                                                                                      #
+# /Whoami-based sync worker routing                                                    #
+#                                                                                      #
+########################################################################################
+
+# matrix_synapse_reverse_proxy_companion_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_synapse_reverse_proxy_companion_restart_necessary: false

roles/custom/matrix-synapse/defaults/main.yml.license

@@ -30,11 +30,13 @@ SPDX-FileCopyrightText: 2022 Quentin Young
 SPDX-FileCopyrightText: 2022 Shaleen Jain
 SPDX-FileCopyrightText: 2022 Yan Minagawa
 SPDX-FileCopyrightText: 2023 - 2024 Michael Hollister
+SPDX-FileCopyrightText: 2023 Dan Arnfield
 SPDX-FileCopyrightText: 2023 Aeris One
 SPDX-FileCopyrightText: 2023 Luke D Iremadze
 SPDX-FileCopyrightText: 2023 Samuel Meenzen
 SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 Charles Wright
-SPDX-FileCopyrightText: 2025 Catalan Lover <catalanlover@protonmail.com>
+SPDX-FileCopyrightText: 2024 David Mehren
+SPDX-FileCopyrightText: 2024 - 2025 Catalan Lover <catalanlover@protonmail.com>
 
 SPDX-License-Identifier: AGPL-3.0-or-later

roles/custom/matrix-synapse/tasks/ext/s3-storage-provider/setup_install.yml

@@ -27,12 +27,14 @@
     src: "{{ role_path }}/templates/synapse/ext/s3-storage-provider/env.j2"
     dest: "{{ matrix_synapse_ext_s3_storage_provider_base_path }}/env"
     mode: '0640'
+  register: matrix_synapse_s3_storage_provider_env_result
 
 - name: Ensure s3-storage-provider database.yaml file installed
   ansible.builtin.template:
     src: "{{ role_path }}/templates/synapse/ext/s3-storage-provider/database.yaml.j2"
     dest: "{{ matrix_synapse_ext_s3_storage_provider_data_path }}/database.yaml"
     mode: '0640'
+  register: matrix_synapse_s3_storage_provider_database_config_result
 
 - name: Ensure s3-storage-provider scripts installed
   ansible.builtin.template:
@@ -42,6 +44,7 @@
   with_items:
     - shell
     - migrate
+  register: matrix_synapse_s3_storage_provider_scripts_result
 
 - name: Ensure matrix-synapse-s3-storage-provider-migrate.service and timer are installed
   ansible.builtin.template:
@@ -52,3 +55,13 @@
     - matrix-synapse-s3-storage-provider-migrate.service
     - matrix-synapse-s3-storage-provider-migrate.timer
   register: matrix_synapse_s3_storage_provider_systemd_service_result
+
+- name: Determine whether s3-storage-provider migrate timer needs a restart
+  ansible.builtin.set_fact:
+    matrix_synapse_s3_storage_provider_restart_necessary: >-
+      {{
+        matrix_synapse_s3_storage_provider_env_result.changed | default(false)
+        or matrix_synapse_s3_storage_provider_database_config_result.changed | default(false)
+        or matrix_synapse_s3_storage_provider_scripts_result.changed | default(false)
+        or matrix_synapse_s3_storage_provider_systemd_service_result.changed | default(false)
+      }}

roles/custom/matrix-synapse/tasks/goofys/setup_install.yml

@@ -20,10 +20,10 @@
     source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
     force_source: "{{ matrix_s3_goofys_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
     force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_s3_goofys_container_image_force_pull }}"
-  register: result
+  register: matrix_goofys_container_image_pull_result
   retries: "{{ devture_playbook_help_container_retries_count }}"
   delay: "{{ devture_playbook_help_container_retries_delay }}"
-  until: result is not failed
+  until: matrix_goofys_container_image_pull_result is not failed
 
 # This will throw a Permission Denied error if already mounted
 - name: Check Matrix Goofys external storage mountpoint path
@@ -47,9 +47,20 @@
     dest: "{{ matrix_synapse_config_dir_path }}/env-goofys"
     owner: root
     mode: '0600'
+  register: matrix_goofys_env_result
 
 - name: Ensure matrix-goofys.service installed
   ansible.builtin.template:
     src: "{{ role_path }}/templates/goofys/systemd/matrix-goofys.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-goofys.service"
     mode: '0644'
+  register: matrix_goofys_systemd_service_result
+
+- name: Determine whether Goofys needs a restart
+  ansible.builtin.set_fact:
+    matrix_goofys_restart_necessary: >-
+      {{
+        matrix_goofys_env_result.changed | default(false)
+        or matrix_goofys_systemd_service_result.changed | default(false)
+        or matrix_goofys_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-synapse/tasks/main.yml

@@ -47,6 +47,16 @@
     # This always runs because it handles uninstallation for sub-components too.
     - ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
 
+- tags:
+    - setup-all
+    - setup-synapse-reverse-proxy-companion
+    - setup-synapse
+    - install-all
+    - install-synapse-reverse-proxy-companion
+    - install-synapse
+  block:
+    - ansible.builtin.include_tasks: "{{ role_path }}/tasks/reverse_proxy_companion/main.yml"
+
 - tags:
     - import-synapse-media-store
   block:

roles/custom/matrix-synapse/tasks/reverse_proxy_companion/main.yml

@@ -13,10 +13,10 @@
     - install-synapse
   block:
     - when: matrix_synapse_reverse_proxy_companion_enabled | bool
-      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/reverse_proxy_companion/validate_config.yml"
 
     - when: matrix_synapse_reverse_proxy_companion_enabled | bool
-      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/reverse_proxy_companion/setup_install.yml"
 
 - tags:
     - setup-all
@@ -24,4 +24,4 @@
     - setup-synapse
   block:
     - when: not matrix_synapse_reverse_proxy_companion_enabled | bool
-      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/reverse_proxy_companion/setup_uninstall.yml"

roles/custom/matrix-synapse/tasks/reverse_proxy_companion/setup_install.yml

@@ -26,19 +26,19 @@
     group: "{{ matrix_group_name }}"
     mode: '0644'
   with_items:
-    - src: "{{ role_path }}/templates/nginx/nginx.conf.j2"
+    - src: "{{ role_path }}/templates/reverse_proxy_companion/nginx/nginx.conf.j2"
       dest: "{{ matrix_synapse_reverse_proxy_companion_base_path }}/nginx.conf"
-    - src: "{{ role_path }}/templates/nginx/conf.d/nginx-http.conf.j2"
+    - src: "{{ role_path }}/templates/reverse_proxy_companion/nginx/conf.d/nginx-http.conf.j2"
       dest: "{{ matrix_synapse_reverse_proxy_companion_confd_path }}/nginx-http.conf"
-    - src: "{{ role_path }}/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2"
+    - src: "{{ role_path }}/templates/reverse_proxy_companion/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2"
       dest: "{{ matrix_synapse_reverse_proxy_companion_confd_path }}/matrix-synapse-reverse-proxy-companion.conf"
-    - src: "{{ role_path }}/templates/labels.j2"
+    - src: "{{ role_path }}/templates/reverse_proxy_companion/labels.j2"
       dest: "{{ matrix_synapse_reverse_proxy_companion_base_path }}/labels"
   register: matrix_synapse_reverse_proxy_companion_config_result
 
 - name: Ensure matrix-synapse-reverse-proxy-companion whoami sync worker router njs script is deployed
   ansible.builtin.template:
-    src: "{{ role_path }}/templates/nginx/njs/whoami_sync_worker_router.js.j2"
+    src: "{{ role_path }}/templates/reverse_proxy_companion/nginx/njs/whoami_sync_worker_router.js.j2"
     dest: "{{ matrix_synapse_reverse_proxy_companion_njs_path }}/whoami_sync_worker_router.js"
     owner: "{{ matrix_user_name }}"
     group: "{{ matrix_group_name }}"
@@ -71,7 +71,7 @@
 
 - name: Ensure matrix-synapse-reverse-proxy-companion.service installed
   ansible.builtin.template:
-    src: "{{ role_path }}/templates/systemd/matrix-synapse-reverse-proxy-companion.service.j2"
+    src: "{{ role_path }}/templates/reverse_proxy_companion/systemd/matrix-synapse-reverse-proxy-companion.service.j2"
     dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-synapse-reverse-proxy-companion.service"
     mode: '0644'
   register: matrix_synapse_reverse_proxy_companion_systemd_service_result

roles/custom/matrix-synapse/tasks/validate_config.yml

@@ -149,6 +149,14 @@
     - "matrix_synapse_workers_stream_writer_account_data_stream_workers_count"
     - "matrix_synapse_workers_stream_writer_receipts_stream_workers_count"
     - "matrix_synapse_workers_stream_writer_presence_stream_workers_count"
+    - "matrix_synapse_workers_stream_writer_push_rules_stream_workers_count"
+
+- name: Fail if matrix-synapse-reverse-proxy-companion access log format is invalid
+  ansible.builtin.fail:
+    msg: >-
+      `matrix_synapse_reverse_proxy_companion_access_log_format` must be one of:
+      {{ matrix_synapse_reverse_proxy_companion_access_log_format_presets.keys() | sort | join(', ') }}
+  when: "matrix_synapse_reverse_proxy_companion_access_log_format not in matrix_synapse_reverse_proxy_companion_access_log_format_presets"
 
 - name: Fail when mixing generic workers with new specialized workers
   ansible.builtin.fail:

roles/custom/matrix-synapse/templates/reverse_proxy_companion/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2

@@ -10,8 +10,61 @@
 {% set stream_writer_account_data_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'account_data') | list %}
 {% set stream_writer_receipts_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'receipts') | list %}
 {% set stream_writer_presence_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'presence') | list %}
+{% set stream_writer_push_rules_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'push_rules') | list %}
+{% set stream_writer_device_lists_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'device_lists') | list %}
+{% set stream_writer_thread_subscriptions_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'thread_subscriptions') | list %}
 {% set media_repository_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'media_repository') | list %}
 {% set user_dir_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'user_dir') | list %}
+{% set stream_writer_client_server_routes = [
+	{
+		'doc_url': 'https://matrix-org.github.io/synapse/latest/workers.html#the-typing-stream',
+		'workers': stream_writer_typing_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_typing_stream_workers_upstream',
+	},
+	{
+		'doc_url': 'https://matrix-org.github.io/synapse/latest/workers.html#the-to_device-stream',
+		'workers': stream_writer_to_device_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_to_device_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_to_device_stream_workers_upstream',
+	},
+	{
+		'doc_url': 'https://matrix-org.github.io/synapse/latest/workers.html#the-account_data-stream',
+		'workers': stream_writer_account_data_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_account_data_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_account_data_stream_workers_upstream',
+	},
+	{
+		'doc_url': 'https://matrix-org.github.io/synapse/latest/workers.html#the-receipts-stream',
+		'workers': stream_writer_receipts_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_receipts_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_receipts_stream_workers_upstream',
+	},
+	{
+		'doc_url': 'https://matrix-org.github.io/synapse/latest/workers.html#the-presence-stream',
+		'workers': stream_writer_presence_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_presence_stream_workers_upstream',
+	},
+	{
+		'doc_url': 'https://matrix-org.github.io/synapse/latest/workers.html#the-push_rules-stream',
+		'workers': stream_writer_push_rules_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_push_rules_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_push_rules_stream_workers_upstream',
+	},
+	{
+		'doc_url': 'https://matrix-org.github.io/synapse/latest/workers.html#the-device_lists-stream',
+		'workers': stream_writer_device_lists_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_device_lists_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_device_lists_stream_workers_upstream',
+	},
+	{
+		'doc_url': 'https://github.com/element-hq/synapse/blob/b99a58719b274fcbb327fd8d7649185792bfd12c/synapse/rest/client/thread_subscriptions.py#L38-L247',
+		'workers': stream_writer_thread_subscriptions_stream_workers,
+		'locations': matrix_synapse_reverse_proxy_companion_synapse_stream_writer_thread_subscriptions_stream_worker_client_server_locations,
+		'upstream': 'stream_writer_thread_subscriptions_stream_workers_upstream',
+	},
+] %}
 
 {% macro render_worker_upstream(name, workers, load_balance) %}
 	upstream {{ name }} {
@@ -34,6 +87,7 @@
 {% macro render_locations_to_upstream(locations, upstream_name) %}
 	{% for location in locations %}
 	location ~ {{ location }} {
+		set $matrix_upstream_label "{{ upstream_name }}";
 		proxy_pass http://{{ upstream_name }}$request_uri;
 		proxy_http_version 1.1;
 		proxy_set_header Connection "";
@@ -41,9 +95,28 @@
 	{% endfor %}
 {% endmacro %}
 
+{% macro render_locations_to_upstream_or_main(locations, workers, upstream_name) %}
+	{% for location in locations %}
+	location ~ {{ location }} {
+		{% if workers | length > 0 %}
+		set $matrix_upstream_label "{{ upstream_name }}";
+		proxy_pass http://{{ upstream_name }}$request_uri;
+		proxy_http_version 1.1;
+		proxy_set_header Connection "";
+		{% else %}
+		{# Use the embedded DNS resolver in Docker containers to discover the service #}
+		resolver {{ matrix_synapse_reverse_proxy_companion_http_level_resolver }} valid=5s;
+		set $backend "{{ matrix_synapse_reverse_proxy_companion_client_api_addr }}";
+		proxy_pass http://$backend;
+		{% endif %}
+	}
+	{% endfor %}
+{% endmacro %}
+
 {% macro render_locations_to_upstream_with_whoami_sync_worker_router(locations, upstream_name) %}
 	{% for location in locations %}
 	location ~ {{ location }} {
+		set $matrix_upstream_label "{{ upstream_name }}";
 		# Use auth_request to call the whoami sync worker router.
 		# The handler resolves the access token to a user identifier and returns it
 		# in the X-User-Identifier header, which is then used for upstream hashing.
@@ -52,6 +125,7 @@
 
 		{% if matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_debug_headers_enabled %}
 		add_header X-Sync-Worker-Router-User-Identifier $user_identifier always;
+		add_header X-Sync-Worker-Router-Upstream-Label $matrix_upstream_label always;
 		add_header X-Sync-Worker-Router-Upstream $upstream_addr always;
 		{% endif %}
 
@@ -100,25 +174,11 @@ map $request_uri $room_name {
 	{{- render_worker_upstream('generic_workers_upstream', generic_workers, 'hash $http_x_forwarded_for;') }}
 	{% endif %}
 
-	{% if stream_writer_typing_stream_workers | length > 0 %}
+	{% for stream_writer_client_server_route in stream_writer_client_server_routes %}
-	{{- render_worker_upstream('stream_writer_typing_stream_workers_upstream', stream_writer_typing_stream_workers, '') }}
+	{% if stream_writer_client_server_route.workers | length > 0 %}
-	{% endif %}
+	{{- render_worker_upstream(stream_writer_client_server_route.upstream, stream_writer_client_server_route.workers, '') }}
-
-	{% if stream_writer_to_device_stream_workers | length > 0 %}
-	{{- render_worker_upstream('stream_writer_to_device_stream_workers_upstream', stream_writer_to_device_stream_workers, '') }}
-	{% endif %}
-
-	{% if stream_writer_account_data_stream_workers | length > 0 %}
-	{{- render_worker_upstream('stream_writer_account_data_stream_workers_upstream', stream_writer_account_data_stream_workers, '') }}
-	{% endif %}
-
-	{% if stream_writer_receipts_stream_workers | length > 0 %}
-	{{- render_worker_upstream('stream_writer_receipts_stream_workers_upstream', stream_writer_receipts_stream_workers, '') }}
-	{% endif %}
-
-	{% if stream_writer_presence_stream_workers | length > 0 %}
-	{{- render_worker_upstream('stream_writer_presence_stream_workers_upstream', stream_writer_presence_stream_workers, '') }}
 	{% endif %}
+	{% endfor %}
 
 	{% if media_repository_workers | length > 0 %}
 	{{- render_worker_upstream('media_repository_workers_upstream', media_repository_workers, 'least_conn;') }}
@@ -142,6 +202,7 @@ server {
 	proxy_buffering on;
 	proxy_max_temp_file_size 0;
 	proxy_set_header Host $host;
+	set $matrix_upstream_label "synapse_main_client_api";
 
 	{% if matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_enabled %}
 	# Internal location for whoami-based sync worker routing.
@@ -186,36 +247,16 @@ server {
 
 		{# Workers redirects BEGIN #}
 
+		{% for stream_writer_client_server_route in stream_writer_client_server_routes %}
+			# {{ stream_writer_client_server_route.doc_url }}
+			{{ render_locations_to_upstream_or_main(stream_writer_client_server_route.locations, stream_writer_client_server_route.workers, stream_writer_client_server_route.upstream) }}
+		{% endfor %}
+
 		{% if generic_workers | length > 0 %}
 			# https://matrix-org.github.io/synapse/latest/workers.html#synapseappgeneric_worker
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations, 'generic_workers_upstream') }}
 		{% endif %}
 
-		{% if stream_writer_typing_stream_workers | length > 0 %}
-			# https://matrix-org.github.io/synapse/latest/workers.html#the-typing-stream
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations, 'stream_writer_typing_stream_workers_upstream') }}
-		{% endif %}
-
-		{% if stream_writer_to_device_stream_workers | length > 0 %}
-			# https://matrix-org.github.io/synapse/latest/workers.html#the-to_device-stream
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_stream_writer_to_device_stream_worker_client_server_locations, 'stream_writer_to_device_stream_workers_upstream') }}
-		{% endif %}
-
-		{% if stream_writer_account_data_stream_workers | length > 0 %}
-			# https://matrix-org.github.io/synapse/latest/workers.html#the-account_data-stream
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_stream_writer_account_data_stream_worker_client_server_locations, 'stream_writer_account_data_stream_workers_upstream') }}
-		{% endif %}
-
-		{% if stream_writer_receipts_stream_workers | length > 0 %}
-			# https://matrix-org.github.io/synapse/latest/workers.html#the-receipts-stream
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_stream_writer_receipts_stream_worker_client_server_locations, 'stream_writer_receipts_stream_workers_upstream') }}
-		{% endif %}
-
-		{% if stream_writer_presence_stream_workers | length > 0 %}
-			# https://matrix-org.github.io/synapse/latest/workers.html#the-presence-stream
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations, 'stream_writer_presence_stream_workers_upstream') }}
-		{% endif %}
-
 		{% if room_workers | length > 0 %}
 			# room workers
 			# https://tcpipuk.github.io/synapse/deployment/workers.html
@@ -237,13 +278,14 @@ server {
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations, 'client_reader_workers_upstream') }}
 		{% endif %}
 
-		{% if media_repository_workers | length > 0 %}
+			{% if media_repository_workers | length > 0 %}
-			# https://matrix-org.github.io/synapse/latest/workers.html#synapseappmedia_repository
+				# https://matrix-org.github.io/synapse/latest/workers.html#synapseappmedia_repository
-			{% for location in matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations %}
+				{% for location in matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations %}
-			location ~ {{ location }} {
+				location ~ {{ location }} {
-				proxy_pass http://media_repository_workers_upstream$request_uri;
+					set $matrix_upstream_label "media_repository_workers_upstream";
+					proxy_pass http://media_repository_workers_upstream$request_uri;
 
-				{% if matrix_synapse_reverse_proxy_companion_synapse_cache_enabled %}
+					{% if matrix_synapse_reverse_proxy_companion_synapse_cache_enabled %}
 					proxy_cache            {{ matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_name }};
 					proxy_cache_valid      any {{ matrix_synapse_reverse_proxy_companion_synapse_cache_proxy_cache_valid_time }};
 					proxy_force_ranges on;
@@ -287,6 +329,7 @@ server {
 	proxy_buffering on;
 	proxy_max_temp_file_size 0;
 	proxy_set_header Host $host;
+	set $matrix_upstream_label "synapse_main_federation_api";
 
 	{% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %}
 		# Federation overrides — These locations must go to the main Synapse process
@@ -308,11 +351,12 @@ server {
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations, 'generic_workers_upstream') }}
 		{% endif %}
 
-		{% if media_repository_workers | length > 0 %}
+			{% if media_repository_workers | length > 0 %}
-			# https://matrix-org.github.io/synapse/latest/workers.html#synapseappmedia_repository
+				# https://matrix-org.github.io/synapse/latest/workers.html#synapseappmedia_repository
-			{% for location in matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations %}
+				{% for location in matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations %}
-			location ~ {{ location }} {
+				location ~ {{ location }} {
-				proxy_pass http://media_repository_workers_upstream$request_uri;
+					set $matrix_upstream_label "media_repository_workers_upstream";
+					proxy_pass http://media_repository_workers_upstream$request_uri;
 
 				{% if matrix_synapse_reverse_proxy_companion_synapse_cache_enabled %}
 					proxy_buffering        on;