Automatic translations update

The previous image versions set ANSIBLE_WORKER_SESSION_ISOLATION=False in an
attempt to restore SSH prompts on Ansible 2.21. That setting does not bring
the prompts back — it makes Ansible hang silently at the first SSH connection
whenever a prompt would have been needed. See
https://github.com/devture/docker-ansible/issues/6

The new image auto-accepts the SSH host keys of previously unknown hosts
instead. The docs stop recommending ANSIBLE_WORKER_SESSION_ISOLATION=False
for direct (non-Docker) runs for the same reason, and now explain how to use
an ssh-agent for passphrase-protected SSH keys.

Co-Authored-By: Claude Fable 5 <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,Bloks

.devcontainer/Dockerfile

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 Jonah Aragon
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+FROM ghcr.io/devture/ansible:14.0.0-r0-3
+
+# Install additional packages
+RUN apk add --no-cache \
+	pwgen
+
+# Preserve command history across container restarts
+RUN SNIPPET="export HISTFILE=/commandhistory/.ash_history" \
+	&& echo "$SNIPPET" >> "/root/.profile"

.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+{
+	"name": "matrix-docker-ansible-deploy",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"context": ".."
+	},
+	"postCreateCommand": {
+		"Fix Volume Permissions": "chown -R $(whoami): /commandhistory"
+	},
+	"mounts": [
+		{
+			"source": "matrix-docker-ansible-deploy-bashhistory",
+			"target": "/commandhistory",
+			"type": "volume"
+		}
+	],
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"EditorConfig.EditorConfig",
+				"redhat.ansible",
+				"redhat.vscode-yaml",
+				"ms-python.python"
+			]
+		}
+	}
+}

.devcontainer/devcontainer.json.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2025 Jonah Aragon
+
+SPDX-License-Identifier: AGPL-3.0-or-later

.github/renovate.json

@@ -1,7 +1,8 @@
 {
 	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
 	"extends": [
-		"config:recommended"
+		"config:recommended",
+		"helpers:pinGitHubActionDigests"
 	],
 	"labels": [
 		"dependencies"
@@ -25,9 +26,34 @@
 				"https://github.com/devture/com.devture.ansible.role{/,}**",
 				"https://github.com/mother-of-all-self-hosting{/,}**"
 			]
+		},
+		{
+			"description": "mautrix images are dual-tagged (v0.YYMM.PATCH and vYY.MM[.PATCH]). Stick to the v0 scheme: it matches the git tags (needed for self-building) and has a consistent number of components (the calver tags do not, which makes Renovate stop offering updates).",
+			"matchPackageNames": [
+				"dock.mau.dev/mautrix/**"
+			],
+			"allowedVersions": "/^v0\\./"
+		},
+		{
+			"matchFileNames": [
+				".github/workflows/close-stale-issues.yml",
+				".github/workflows/lock-threads.yml",
+				".github/workflows/matrix.yml",
+				".github/workflows/update-translations.yml",
+				"flake.lock",
+				"i18n/requirements.txt",
+				"mise.toml"
+			],
+			"automerge": true
 		}
 	],
 	"pre-commit": {
 		"enabled": true
+	},
+	"nix": {
+		"enabled": true,
+		"lockFileMaintenance": {
+			"enabled": true
+		}
 	}
 }

.github/workflows/close-stale-issues.yml

@@ -19,7 +19,7 @@ jobs:
     if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v10
+      - uses: actions/stale@4391f3da665fdf50b6810c1a66712fb9ba21aa93 # v11
         with:
           ######################################################################
           # Issues/PRs

.github/workflows/lock-threads.yml

@@ -23,7 +23,7 @@ jobs:
     if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
     runs-on: ubuntu-latest
     steps:
-      - uses: dessant/lock-threads@v6
+      - uses: dessant/lock-threads@89ae32b08ed1a541efecbab17912962a5e38981c # v6
         with:
           add-issue-labels: 'outdated'
           process-only: 'issues, prs'

.github/workflows/matrix.yml

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

.github/workflows/update-translations.yml

@@ -24,23 +24,23 @@ jobs:
     name: Update translations
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
         with:
           python-version: '3.14'
 
       # Setting up recommended prerequisites
       # See: i18n/README.md
-      - uses: astral-sh/setup-uv@v7
-      - uses: extractions/setup-just@v3
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
 
       # TODO: optimize when we start publishing translations and integrate a Weblate instance
       - name: Update translation catalog templates (POT) files
         run: just --justfile i18n/justfile extract-translation-templates
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v8.1.0
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>  # Same as committer
           body: This is an automatic pull request to update translation files.

.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.3
     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.8.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

.yamllint

@@ -1,5 +1,16 @@
 ---
 extends: default
 
+# Keep this custom configuration compatible with ansible-lint's `yaml` rule.
+# See https://docs.ansible.com/projects/lint/rules/yaml/#yamllint-configuration
 rules:
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false
   line-length: disable
+  octal-values:
+    forbid-explicit-octal: true
+    forbid-implicit-octal: true

AGENTS.md

@@ -0,0 +1,39 @@
+<!--
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Guidance for AI agents
+
+This file gives AI coding agents the minimum context for working on this repository. Human contributors may find it a useful summary too.
+
+## What this is
+
+An Ansible playbook that installs and manages a Matrix homeserver and dozens of related services, each running as a Docker container wrapped in a systemd service.
+
+## Layout
+
+- `setup.yml`: the main playbook, listing all roles.
+- `roles/custom/`: roles maintained in this repository.
+- `roles/galaxy/`: external roles, downloaded according to `requirements.yml` via [agru](https://github.com/etkecc/agru) (preferred) or `ansible-galaxy`. Run `just roles` to install them (or `just update` to also pull the playbook itself). Editing these roles locally is fine while preparing or testing a fix, but the changes get wiped on the next roles update, so they must be synced back to the role's upstream repository, followed by a version pin update in `requirements.yml`.
+- `group_vars/matrix_servers`: wires roles together (feeding one role's variables into another). Values a role can construct by itself belong in the role's `defaults/main.yml`, not here.
+- `docs/`: user-facing documentation, one page per component.
+- `i18n/`: translation infrastructure. Do not edit locale files by hand; they are managed by automation.
+- `CHANGELOG.md`: user-facing announcements, newest first.
+
+## Conventions
+
+Follow the [style guide for playbook developers](docs/style-guide.md). In particular:
+
+- Variable prefixes match the role directory name.
+- Playbook-extensible list variables use the `_auto` + `_custom` split; `_custom` is reserved for users.
+- Renamed or removed variables get a validation entry, so stale user configuration produces an error instead of being silently ignored. Each role deprecates its own variables in its `validate_config.yml`; the `matrix_playbook_migration` role covers eliminated roles and very-early validation, and also gates breaking changes via `matrix_playbook_migration_expected_version` (see the style guide).
+- Every file carries SPDX license headers ([REUSE](https://reuse.software/) specification).
+- New components must be registered in `setup.yml`, `group_vars/matrix_servers`, `docs/README.md`, `README.md`, `docs/container-images.md`, and get a `CHANGELOG.md` entry.
+
+## Other notes
+
+- Documentation examples use `example.com`, `@alice:example.com`, and the other placeholder values listed in the style guide.
+- Write role tasks concurrency-safe: use `ansible.builtin.tempfile` for temporary files (removed in an `always` block), never fixed shared paths.
+- One logical change per commit.

CHANGELOG.md

@@ -1,3 +1,513 @@
+# 2026-08-20
+
+## MatrixRTC transports are advertised in the client well-known again
+
+This only affects you if you have the [Matrix RTC stack](docs/configuring-playbook-matrix-rtc.md) or [Element Call](docs/configuring-playbook-element-call.md) enabled.
+
+Yesterday's changelog entry announced that the `org.matrix.msc4143.rtc_foci` property was gone from the `/.well-known/matrix/client` file. That turned out to be premature and has been reverted, so the property is published again as it always was.
+
+The property is indeed dropped from [MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143) and [Element Call v0.24.0](https://github.com/element-hq/element-call/releases/tag/v0.24.0) no longer reads it, but Element Web (and likely other clients who move slowly or are otherwise outdated) does not ship that version of Element Call yet. Element Web v1.12.26 bundles Element Call v0.22.0, which still discovers your transport through the well-known property. It cannot use the homeserver's `/_matrix/client/unstable/org.matrix.msc4143/rtc/transports` API instead, because Element Call runs as a widget there and a widget holds no access token, while that API requires authentication. Newer Element Call versions ask their host client for the transports over the widget API ([MSC4515](https://github.com/matrix-org/matrix-spec-proposals/pull/4515)), which is what will eventually make the property unnecessary.
+
+Dropping the property therefore broke Element Call for Element Web and Element Desktop users, with a `MISSING_MATRIX_RTC_TRANSPORT` error when starting a call. Re-running the playbook (`just install-all`) brings the property back and fixes calls.
+
+If you worked around this by publishing the property yourself via `matrix_static_files_file_matrix_client_configuration_extension_json`, you can drop that from your `vars.yml` file now. The `matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_custom` variable and its companions are back as well.
+
+# 2026-08-13
+
+## The homeserver root path redirects to clients other than Element Web
+
+Visiting `https://matrix.example.com/` used to redirect you to [Element Web](docs/configuring-playbook-client-element-web.md), but only if Element Web was the client installed by the playbook. With any of the other web clients (Cinny, Commet, FluffyChat, Hydrogen, SchildiChat, Sable), you would land on a bare Synapse page.
+
+The redirection now follows whichever of these clients you have enabled. When several are enabled, Element Web wins, followed by the others in the order that [`group_vars/matrix_servers`](group_vars/matrix_servers) lists them.
+
+To send people somewhere else (or nowhere at all), define `matrix_playbook_public_client_root_redirection_url` in your `vars.yml` file. An empty value disables the redirection.
+
+## Support for Meowlnir
+
+The playbook can now install [Meowlnir](https://github.com/maunium/meowlnir), an opinionated Matrix moderation bot, optimized for Synapse.
+
+Meowlnir joins [Draupnir](docs/configuring-playbook-bot-draupnir.md) and [Mjolnir](docs/configuring-playbook-bot-mjolnir.md) as a 3rd moderation option, speaking the same [policy list](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists) protocol so that it can subscribe to the same community ban lists. Unlike the others, it can override individual policies coming from lists you do not control (by way of an unban policy in a list of your own which is ordered ahead of other policy lists).
+
+You can run it alongside Draupnir while evaluating it — see the documentation for the caveats, the main one being that both want the [synapse-http-antispam](https://github.com/maunium/synapse-http-antispam) module, which only reports to a single consumer.
+
+To get started, see the [Setting up Meowlnir](docs/configuring-playbook-bot-meowlnir.md) documentation page.
+
+
+# 2026-08-06
+
+## (Backward Compatibility Break) Jitsi no longer uses Colibri WebSockets
+
+This only affects you if you have [Jitsi](docs/configuring-playbook-jitsi.md) enabled.
+
+Jitsi has been updated to `stable-11146-1`, which [removes Colibri WebSocket support](https://github.com/jitsi/docker-jitsi-meet/pull/2285) in favour of SCTP data channels. The Jitsi Video Bridge no longer serves HTTP at all, so a few `jitsi_jvb_*` variables are gone. The playbook will tell you which ones, if your configuration still sets them.
+
+If you run [additional JVBs on other hosts](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md#set-up-additional-jvbs-for-more-video-conferences-optional), the Traefik configuration which routed `/colibri-ws/<server-id>/` to them is now dead and can be removed. Nothing will warn you about that one, as it lives in a free-form `traefik_provider_configuration_extension_yaml` block.
+
+# 2026-07-28
+
+## (Backward Compatibility Break) ntfy users are now declared with hashed passwords
+
+This only affects you if you have enabled authentication for [ntfy](docs/configuring-playbook-ntfy.md) via `ntfy_credentials`.
+
+The ntfy role used to create users by invoking `ntfy user` commands against the running container. Since v2.14.0, ntfy can provision users and access-control entries from its own configuration file, so the role now does that instead. Besides being a lot simpler, this fixes passwords containing spaces never arriving intact.
+
+Replace `ntfy_credentials` with `ntfy_auth_users_custom`, which takes bcrypt password hashes rather than plaintext passwords:
+
+```yaml
+ntfy_auth_users_custom:
+  - username: alice
+    password_hash: $2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C
+    role: admin
+```
+
+Generate a hash for each of your passwords by running the following command on any machine which has Docker installed. It asks for the password and prints its hash:
+
+```sh
+docker run --rm -it docker.io/binwiederhier/ntfy:latest user hash
+```
+
+The playbook will let you know if your configuration still uses `ntfy_credentials`.
+
+Your existing ntfy users are left alone and keep working until you declare them again this way. Note that ntfy manages declared users and access-control entries declaratively, so removing one from your configuration later deletes it from ntfy's user database.
+
+Users with the `admin` role get access to all topics. Others start with no access at all, and can be granted access to specific topics via `ntfy_auth_access_custom`. It is also now possible to control what unauthenticated visitors may do (`ntfy_auth_default_access`) and whether users may log in at all (`ntfy_enable_login`, which follows your authentication setup by default). See the role's [documentation on access control](https://github.com/mother-of-all-self-hosting/ansible-role-ntfy/blob/main/docs/configuring-ntfy.md#enable-access-control-with-authentication-optional) for details.
+
+## Support for bridging to LinkedIn via mautrix-linkedin
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook now supports bridging to [LinkedIn](https://www.linkedin.com/) via [mautrix-linkedin](https://github.com/mautrix/linkedin).
+
+Logging in requires copying a request out of your browser's developer tools, and only works with Chrome or another Chrome-based browser. To learn more, see our [Setting up Mautrix LinkedIn bridging](./docs/configuring-playbook-bridge-mautrix-linkedin.md) documentation page.
+
+This bridge supersedes [beeper-linkedin](./docs/configuring-playbook-bridge-beeper-linkedin.md), which is now considered unmaintained (its [upstream repository](https://github.com/beeper/linkedin) has been archived). The old bridge remains installable, but you may wish to switch. Both bridges claim the same appservice namespaces, so the playbook refuses to install mautrix-linkedin while beeper-linkedin is still enabled.
+
+## Support for bridging to LINE via beeper-line
+
+Thanks to [Co van Leeuwen](https://github.com/c00), the playbook can now bridge [LINE](https://line.me/) via [beeper-line](https://github.com/beeper/line), a bridge based on the modern mautrix bridge framework. It supports LINE accounts with Letter Sealing enabled or disabled and bridges messages, media, reactions, replies, receipts, and other common chat features.
+
+The bridge identifies itself as a LINE Chrome Extension client, so it cannot be used at the same time as the real LINE Chrome Extension. See [Setting up Beeper LINE bridging](docs/configuring-playbook-bridge-beeper-line.md) to get started.
+
+
+# 2026-07-19
+
+## Tuwunel now exposes its administration and /_tuwunel API paths
+
+The [Tuwunel](docs/configuring-playbook-tuwunel.md) role previously routed only the `/_matrix` path through the reverse proxy. It now also exposes the two other API paths that Tuwunel serves.
+
+The Synapse-compatible administration API (`/_synapse/admin`) powers administration dashboards and moderation bots. As with Synapse and Dendrite, the playbook now exposes it automatically when such a tool is installed: publicly for [Ketesa](docs/configuring-playbook-ketesa.md) or [Element Admin](docs/configuring-playbook-element-admin.md), and on the internal entrypoint for [Draupnir](docs/configuring-playbook-bot-draupnir.md). To expose it yourself, set `matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: true` (or the `internal_` variant).
+
+Tuwunel also serves first-party routes under `/_tuwunel`, including its native OpenID Connect provider endpoints, which the reverse proxy must route for OIDC login to work. This path is now routed on the public entrypoint by default. To keep it off the public entrypoint, set `matrix_tuwunel_container_labels_public_tuwunel_api_enabled: false`.
+
+
+# 2026-07-18
+
+## LiveKit Server port configuration must be unambiguous now
+
+This only affects you if you have configured a LiveKit Server RTC port range (`livekit_server_config_rtc_port_range_start` and `livekit_server_config_rtc_port_range_end`).
+
+LiveKit only uses one of the two port configuration mechanisms: when a port range is defined, the multiplexed UDP port (`livekit_server_config_rtc_udp_port`) is ignored entirely. Previously, the role would silently render its default UDP port (7882) into the configuration alongside your port range, misleadingly suggesting that both are in effect.
+
+The role now asks you to make the choice explicit: if you define a port range, unset the UDP port by adding `livekit_server_config_rtc_udp_port: ''` to your `vars.yml` file. A validation error will guide you, if your configuration is affected.
+
+
+# 2026-07-17
+
+## prometheus-nginxlog-exporter metric names have changed
+
+If you have enabled [metrics for nginx logs](docs/configuring-playbook-prometheus-grafana.md) (`prometheus_nginxlog_exporter_enabled: true`), note that the exporter's metric names have changed.
+
+The exporter's configuration used to ship a leftover `myprefix` placeholder as the metric name prefix, producing metrics like `myprefix_http_response_count_total`. The bundled Grafana dashboard queries unprefixed metric names (`http_response_count_total`), so it could never show any data (reported in [#3380](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3380)).
+
+Metric names are now unprefixed, matching the bundled dashboard, which should start working. Each metric carries a `namespace` label, whose value is now `nginx` (previously `matrix`); it is configurable via `prometheus_nginxlog_exporter_config_namespace_name`. If you have built custom dashboards or alerts on top of the old `myprefix_*` metric names, adjust them accordingly, or restore the old behavior by setting `prometheus_nginxlog_exporter_config_namespace_metrics_prefix: myprefix` in your `vars.yml` file.
+
+
+# 2026-07-16
+
+## (Backward Compatibility Break) Bridge variables have been renamed
+
+All bridge roles (`roles/custom/matrix-bridge-*`) now use a uniform variable naming scheme, where the variable prefix matches the role directory name. This adopts the naming policy proposed in [#4705](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/4705) and requested in [#5096](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/5096).
+
+Previously, bridge variable prefixes were all over the place (`matrix_mautrix_telegram_*`, `matrix_heisenbridge_*`, `matrix_steam_bridge_*`, etc.). Now, they all follow the same pattern that bot roles (`matrix_bot_<name>_*`) have been using for years: the `matrix-bridge-mautrix-telegram` role uses `matrix_bridge_mautrix_telegram_*` variables, the `matrix-bridge-steam` role uses `matrix_bridge_steam_*` variables, and so on.
+
+Only Ansible variables were renamed. Systemd service names, container names, `/matrix/*` directories, database names and usernames, and appservice registration contents (tokens, bot usernames) all remain the same. No data migration is necessary and bridges keep working as before, once you rename the variables in your `vars.yml` configuration file.
+
+The playbook will let you know if your configuration still uses old-style variable names.
+
+Here is the full rename map:
+
+| Old variable prefix | New variable prefix |
+|---------------------|---------------------|
+| `matrix_appservice_discord_` | `matrix_bridge_appservice_discord_` |
+| `matrix_appservice_irc_` | `matrix_bridge_appservice_irc_` |
+| `matrix_beeper_linkedin_` | `matrix_bridge_beeper_linkedin_` |
+| `matrix_heisenbridge_` | `matrix_bridge_heisenbridge_` |
+| `matrix_hookshot_` | `matrix_bridge_hookshot_` |
+| `matrix_mautrix_androidsms_` | `matrix_bridge_mautrix_wsproxy_androidsms_` |
+| `matrix_mautrix_bluesky_` | `matrix_bridge_mautrix_bluesky_` |
+| `matrix_mautrix_discord_` | `matrix_bridge_mautrix_discord_` |
+| `matrix_mautrix_gmessages_` | `matrix_bridge_mautrix_gmessages_` |
+| `matrix_mautrix_googlechat_` | `matrix_bridge_mautrix_googlechat_` |
+| `matrix_mautrix_gvoice_` | `matrix_bridge_mautrix_gvoice_` |
+| `matrix_mautrix_imessage_` | `matrix_bridge_mautrix_wsproxy_imessage_` |
+| `matrix_mautrix_meta_instagram_` | `matrix_bridge_mautrix_meta_instagram_` |
+| `matrix_mautrix_meta_messenger_` | `matrix_bridge_mautrix_meta_messenger_` |
+| `matrix_mautrix_signal_` | `matrix_bridge_mautrix_signal_` |
+| `matrix_mautrix_slack_` | `matrix_bridge_mautrix_slack_` |
+| `matrix_mautrix_telegram_` | `matrix_bridge_mautrix_telegram_` |
+| `matrix_mautrix_twitter_` | `matrix_bridge_mautrix_twitter_` |
+| `matrix_mautrix_whatsapp_` | `matrix_bridge_mautrix_whatsapp_` |
+| `matrix_mautrix_wsproxy_` | `matrix_bridge_mautrix_wsproxy_` |
+| `matrix_meshtastic_relay_` | `matrix_bridge_meshtastic_relay_` |
+| `matrix_mx_puppet_groupme_` | `matrix_bridge_mx_puppet_groupme_` |
+| `matrix_mx_puppet_steam_` | `matrix_bridge_mx_puppet_steam_` |
+| `matrix_postmoogle_` | `matrix_bridge_postmoogle_` |
+| `matrix_rustpush_bridge_` | `matrix_bridge_rustpush_` |
+| `matrix_sms_bridge_` | `matrix_bridge_sms_` |
+| `matrix_steam_bridge_` | `matrix_bridge_steam_` |
+| `matrix_wechat_` | `matrix_bridge_wechat_` |
+
+A few special cases beyond the prefix map:
+
+- `matrix_mautrix_signal_wsproxy_syncproxy_connection_string` (a variable of the mautrix-wsproxy role, despite its name) is now `matrix_bridge_mautrix_wsproxy_syncproxy_connection_string`
+- `matrix_playbook_migration_matrix_postmoogle_migration_validation_enabled` is now `matrix_playbook_migration_matrix_bridge_postmoogle_migration_validation_enabled`
+
+You can update your `vars.yml` file automatically with this `sed` command (on macOS, use `sed -i ''` instead of `sed -i`):
+
+```sh
+sed -i \
+  -e 's/matrix_appservice_discord_/matrix_bridge_appservice_discord_/g' \
+  -e 's/matrix_appservice_irc_/matrix_bridge_appservice_irc_/g' \
+  -e 's/matrix_beeper_linkedin_/matrix_bridge_beeper_linkedin_/g' \
+  -e 's/matrix_heisenbridge_/matrix_bridge_heisenbridge_/g' \
+  -e 's/matrix_hookshot_/matrix_bridge_hookshot_/g' \
+  -e 's/matrix_mautrix_androidsms_/matrix_bridge_mautrix_wsproxy_androidsms_/g' \
+  -e 's/matrix_mautrix_bluesky_/matrix_bridge_mautrix_bluesky_/g' \
+  -e 's/matrix_mautrix_discord_/matrix_bridge_mautrix_discord_/g' \
+  -e 's/matrix_mautrix_gmessages_/matrix_bridge_mautrix_gmessages_/g' \
+  -e 's/matrix_mautrix_googlechat_/matrix_bridge_mautrix_googlechat_/g' \
+  -e 's/matrix_mautrix_gvoice_/matrix_bridge_mautrix_gvoice_/g' \
+  -e 's/matrix_mautrix_imessage_/matrix_bridge_mautrix_wsproxy_imessage_/g' \
+  -e 's/matrix_mautrix_meta_instagram_/matrix_bridge_mautrix_meta_instagram_/g' \
+  -e 's/matrix_mautrix_meta_messenger_/matrix_bridge_mautrix_meta_messenger_/g' \
+  -e 's/matrix_mautrix_signal_wsproxy_syncproxy_connection_string/matrix_bridge_mautrix_wsproxy_syncproxy_connection_string/g' \
+  -e 's/matrix_mautrix_signal_/matrix_bridge_mautrix_signal_/g' \
+  -e 's/matrix_mautrix_slack_/matrix_bridge_mautrix_slack_/g' \
+  -e 's/matrix_mautrix_telegram_/matrix_bridge_mautrix_telegram_/g' \
+  -e 's/matrix_mautrix_twitter_/matrix_bridge_mautrix_twitter_/g' \
+  -e 's/matrix_mautrix_whatsapp_/matrix_bridge_mautrix_whatsapp_/g' \
+  -e 's/matrix_mautrix_wsproxy_/matrix_bridge_mautrix_wsproxy_/g' \
+  -e 's/matrix_meshtastic_relay_/matrix_bridge_meshtastic_relay_/g' \
+  -e 's/matrix_mx_puppet_groupme_/matrix_bridge_mx_puppet_groupme_/g' \
+  -e 's/matrix_mx_puppet_steam_/matrix_bridge_mx_puppet_steam_/g' \
+  -e 's/matrix_postmoogle_/matrix_bridge_postmoogle_/g' \
+  -e 's/matrix_rustpush_bridge_/matrix_bridge_rustpush_/g' \
+  -e 's/matrix_sms_bridge_/matrix_bridge_sms_/g' \
+  -e 's/matrix_steam_bridge_/matrix_bridge_steam_/g' \
+  -e 's/matrix_wechat_/matrix_bridge_wechat_/g' \
+  -e 's/matrix_playbook_migration_matrix_postmoogle_migration_validation_enabled/matrix_playbook_migration_matrix_bridge_postmoogle_migration_validation_enabled/g' \
+  vars.yml
+```
+
+The `sed` command only replaces prefixes followed by an underscore, so values that intentionally match old prefixes (like the default database names, e.g. `matrix_mautrix_telegram`) are not affected.
+
+**Note**: if you have defined your own custom variables whose names embed an old prefix (e.g. `vault_matrix_postmoogle_password` referencing a secret in an Ansible Vault file), the `sed` command renames such references too. Either rename your custom variables to match (including their definitions in encrypted vault files, which `sed` cannot reach), or revert those spots manually.
+
+# 2026-07-15
+
+## Google Voice bridging
+
+The playbook can now bridge [Google Voice](https://voice.google.com/) via the [mautrix-gvoice](https://github.com/mautrix/gvoice) bridge. Text and media flow both ways, and portal rooms build themselves for your recent conversations.
+
+Login is by cookie, not a paired phone: you copy the cookies from a browser signed in to voice.google.com and hand them to the bot. Google expires them on its own schedule, so expect to log in again every so often. See [Setting up Mautrix Google Voice bridging](./docs/configuring-playbook-bridge-mautrix-gvoice.md) to get started.
+
+## matrix-appservice-kakaotalk has been removed from the playbook
+
+The [matrix-appservice-kakaotalk](./docs/configuring-playbook-bridge-appservice-kakaotalk.md) bridge has been removed from the playbook. This component could only be installed by self-building its source code, and its upstream repository has become unreachable, which makes installation impossible. The bridge was also based on the unmaintained node-kakao library, and there have been reports that using it may get KakaoTalk accounts banned.
+
+The playbook will let you know if you're using any `matrix_appservice_kakaotalk_*` variables. You'll need to remove them from `vars.yml` and potentially [uninstall the component manually](./docs/configuring-playbook-bridge-appservice-kakaotalk.md#uninstalling-the-component-manually).
+
+## Dedicated CAPTCHA variables for Matrix Authentication Service
+
+[Matrix Authentication Service](./docs/configuring-playbook-matrix-authentication-service.md) can now be protected with CAPTCHA (ReCaptcha v2, Cloudflare Turnstile, or hCaptcha) via dedicated variables, instead of going through `matrix_authentication_service_configuration_extension_yaml`. See the [captcha documentation](./docs/configuring-captcha.md#matrix-authentication-service) for details.
+
+# 2026-07-14
+
+## The playbook no longer ships a custom welcome page for Element Web
+
+Element Web [redesigned its welcome page](https://github.com/element-hq/element-web/pull/33211) (the screen shown at `/#/welcome` before logging in) into a built-in component and no longer loads a custom `welcome.html` file by default. Since the playbook upgraded to an Element Web version containing that change (spring 2026), the custom welcome page the playbook installed (and the variables customizing it) had silently stopped having any effect.
+
+The playbook now embraces the new upstream behavior and no longer ships its own `welcome.html`. The following variables have been removed and the playbook will let you know if you're still using them: `matrix_client_element_welcome_headline`, `matrix_client_element_welcome_text`, `matrix_client_element_welcome_logo_link` and `matrix_client_element_page_template_welcome_path`.
+
+Most welcome page customizations keep working, because they go through Element Web's branding configuration, which the new welcome page still honors:
+
+- a custom logo, via `matrix_client_element_welcome_logo` (or `matrix_client_element_branding_auth_header_logo_url`)
+- a custom background, via `matrix_client_element_branding_welcome_background_url`
+
+If you need a fully custom welcome page, you can self-host an HTML page and point Element Web at it, like this:
+
+```yaml
+matrix_client_element_configuration_extension_json: |
+  {
+    "embedded_pages": {
+      "welcome_url": "https://example.com/my-welcome.html"
+    }
+  }
+```
+
+## BorgBackup now includes Synapse's local thumbnails
+
+For Synapse servers, the built-in [BorgBackup](./docs/configuring-playbook-backup-borg.md) integration no longer excludes the media store's `local_thumbnails` directory from backups.
+
+Synapse only generates thumbnails of local media at upload time (unless `dynamic_thumbnails` is enabled, which the playbook does not do), and there is no tooling to regenerate them. Restoring a backup made with the previous exclusion list therefore left all previously uploaded local images without thumbnails. The [official Synapse backup guide](https://element-hq.github.io/synapse/latest/usage/administration/backups.html) recommends backing this directory up, and the playbook now follows that recommendation.
+
+Expect your backups to grow somewhat, depending on how much image media your local users have uploaded. If you prefer the old behavior, you can redefine `backup_borg_location_exclude_patterns` in your `vars.yml`.
+
+# 2026-07-12
+
+## matrix-registration-bot has been removed from the playbook
+
+The [matrix-registration-bot](./docs/configuring-playbook-bot-matrix-registration-bot.md) service has been removed from the playbook, as it has been unmaintained.
+
+The playbook will let you know if you're using any `matrix_bot_matrix_registration_bot_*` variables. You'll need to remove them from `vars.yml` and potentially [uninstall the component manually](./docs/configuring-playbook-bot-matrix-registration-bot.md#uninstalling-the-component-manually).
+
+## Continuwuity v26 no longer supports LDAP
+
+The playbook now installs [Continuwuity](./docs/configuring-playbook-continuwuity.md) v26, a major upgrade from the v0.5.x series which **removes LDAP authentication support** (see the [v26.6.0 release notes](https://forgejo.ellis.link/continuwuation/continuwuity/releases/tag/v26.6.0)).
+
+The playbook never exposed dedicated variables for Continuwuity's LDAP support, so most people are unaffected. However, if you had enabled LDAP via `matrix_continuwuity_environment_variables_extension` or a custom configuration template, you'll need to migrate to another authentication method, such as the newly introduced [OpenID Connect support](https://continuwuity.org/guides/oidc).
+
+# 2026-06-29
+
+## Support for running on Synology DSM
+
+Thanks to [cksit](https://github.com/cksit), the playbook can now run on [Synology DSM](https://www.synology.com/dsm) 7 and later.
+
+Synology hosts are detected automatically (via `/etc/synoinfo.conf`), so other systems are unaffected. On DSM, the playbook uses the platform's native user management (`synouser`/`synogroup`), works around a Docker SDK incompatibility, and installs a small boot-fix service that handles a few DSM-specific boot quirks.
+
+To get started, see the new [Configuring Synology DSM](./docs/configuring-playbook-synology.md) documentation page.
+
+## Mautrix bridges now expose their API (for Mautrix Manager and similar tools)
+
+The playbook now exposes the HTTP API of each [mautrix](https://github.com/mautrix) bridge, so tools like [Mautrix Manager](https://github.com/mautrix/manager) can help you log into them. This is especially useful for [mautrix-gmessages](./docs/configuring-playbook-bridge-mautrix-gmessages.md): Google has removed its QR-code login, leaving a [manual cookie-extraction flow](https://docs.mau.fi/bridges/go/gmessages/authentication.html) that tools like Mautrix Manager can streamline.
+
+The API is exposed at `https://matrix.example.com/bridges/SERVICENAME` (for example, `https://matrix.example.com/bridges/gmessages`) and is advertised via a new `/.well-known/matrix/mautrix` file, so compatible tools can discover your bridges automatically. Such tools authenticate with your own Matrix access token, so no bridge secret needs to be shared with them.
+
+This affects all mautrix bridges based on the new bridge framework (bluesky, gmessages, meta-instagram, meta-messenger, signal, slack, telegram, twitter and whatsapp) and is enabled by default.
+
+To learn more (including how to turn it off), see the [Expose the bridge's API](./docs/configuring-playbook-bridge-mautrix-bridges.md#expose-the-bridges-api-for-mautrix-manager-and-similar-tools) section on our common mautrix bridges documentation page.
+
+# 2026-06-28
+
+## baibot now supports Venice, our recommended provider
+
+[baibot](./docs/configuring-playbook-bot-baibot.md) now ships a preset for the [Venice](./docs/configuring-playbook-bot-baibot.md#venice) provider, and it's the one we recommend. It's the most capable provider baibot supports (text generation with vision, file inputs and web search, speech-to-text, text-to-speech, and image generation and editing), and the only one that runs inference with no logging and no training on your data.
+
+Enabling it takes a preset toggle and an API key:
+
+```yaml
+matrix_bot_baibot_config_agents_static_definitions_venice_enabled: true
+
+matrix_bot_baibot_config_agents_static_definitions_venice_config_api_key: "YOUR_API_KEY_HERE"
+```
+
+[OpenAI](https://openai.com/) and baibot's other providers remain fully supported. To get started, see the [Setting up baibot](./docs/configuring-playbook-bot-baibot.md#venice) documentation page.
+
+# 2026-06-24
+
+## Support for bridging to iMessage via RustPush
+
+Thanks to [jasonlaguidice](https://github.com/jasonlaguidice), the playbook now supports bridging to [iMessage](https://support.apple.com/messages) via a new [RustPush](https://github.com/OpenBubbles/rustpush)-based bridge ([jasonlaguidice/imessage](https://github.com/jasonlaguidice/imessage)).
+
+Unlike the existing [mautrix-wsproxy](./docs/configuring-playbook-bridge-mautrix-wsproxy.md) iMessage bridge, this one talks directly to Apple's push notification service, so it needs neither a running Mac nor a wsproxy on the homeserver. Each user supplies a hardware key extracted from a Mac through the bridge bot's login flow.
+
+To learn more, see our [Setting up RustPush (iMessage) bridging](./docs/configuring-playbook-bridge-rustpush.md) documentation page.
+
+# 2026-05-24
+
+## matrix-ldap-registration-proxy has been removed from the playbook
+
+The [matrix-ldap-registration-proxy](./docs/configuring-playbook-matrix-ldap-registration-proxy.md) service has been removed from the playbook, as the source code and the container image have become unavailable.
+
+The playbook will let you know if you're using any `matrix_ldap_registration_proxy_*` variables. You'll need to remove them from `vars.yml` and potentially [uninstall the component manually](./docs/configuring-playbook-matrix-ldap-registration-proxy.md#uninstalling-the-component-manually).
+
+# 2026-05-23
+
+## Go-NEB has been removed from the playbook
+
+[Go-NEB](./docs/configuring-playbook-bot-go-neb.md) has been removed from the playbook, as it has been discontinued since June 2023.
+
+The playbook will let you know if you're using any `matrix_bot_go_neb_*` variables. You'll need to remove them from `vars.yml` and potentially [uninstall the bot manually](./docs/configuring-playbook-bot-go-neb.md#uninstalling-go-neb-manually).
+
+# 2026-05-19
+
+## matrix-registration has been removed from the playbook
+
+The [matrix-registration](./docs/configuring-playbook-matrix-registration.md) service has been removed from the playbook, as it has been unmaintained (archived) since November, 2025.
+
+The playbook will let you know if you're using any `matrix_registration_*` variables. You'll need to remove them from `vars.yml` and potentially [uninstall the component manually](./docs/configuring-playbook-matrix-registration.md#uninstalling-the-component-manually).
+
+# 2026-05-18
+
+## LiveKit Server has been upgraded to v1.12.0
+
+The playbook now ships [LiveKit Server](./docs/configuring-playbook-livekit-server.md) v1.12.0. See the [upstream release notes](https://github.com/livekit/livekit/releases/tag/v1.12.0) for details.
+
+This release tightens TURN security:
+
+- **TURN credentials now carry a TTL** (default: 300 seconds), exposed via `livekit_server_config_turn_ttl_seconds`.
+- **TURN no longer relays traffic to restricted peer CIDRs** (loopback, link-local, multicast, private, unspecified) by default. If your setup legitimately requires it, list the ranges in `livekit_server_config_turn_allow_restricted_peer_cidrs`.
+
+    For example, to allow TURN to reach the common [RFC1918](https://www.rfc-editor.org/rfc/rfc1918) private ranges, add to your `vars.yml`:
+    ```yaml
+    livekit_server_config_turn_allow_restricted_peer_cidrs:
+      - 10.0.0.0/8
+      - 172.16.0.0/12
+      - 192.168.0.0/16
+    ```
+
+    Adjust the ranges to match your network. To deny specific CIDRs (taking precedence over the allow list above), use `livekit_server_config_turn_deny_peer_cidrs` in the same shape.
+
+
+# 2026-05-07
+
+## Tuwunel support
+
+Thanks to [Jason Volk](https://github.com/jevolk), the playbook now supports the [Tuwunel](./docs/configuring-playbook-tuwunel.md) homeserver as an optional alternative to Synapse.
+
+Tuwunel is a fork of [conduwuit](./docs/configuring-playbook-conduwuit.md) written in Rust. The former conduwuit maintainer [endorses Tuwunel as conduwuit's successor](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/5200#issuecomment-4396211185). Like [Continuwuity](./docs/configuring-playbook-continuwuity.md), Tuwunel continues development on top of conduwuit's database format.
+
+Existing installations do **not** need to be updated. **Synapse is still the default homeserver implementation** installed by the playbook.
+
+People that used to run conduwuit may wish to [migrate from conduwuit to Tuwunel](./docs/configuring-playbook-tuwunel.md#migrating-from-conduwuit) via the new `tuwunel-migrate-from-conduwuit` tag, which performs an in-place binary-swap migration that reads the conduwuit database directly.
+
+**The homeserver implementation of an existing server cannot be changed** (e.g. from Synapse/Conduit/Dendrite/Continuwuity to Tuwunel) without data loss. The exception is conduwuit, due to the shared database format.
+
+
+# 2026-04-24
+
+## Support for bridging to Meshtastic via meshtastic-matrix-relay
+
+Thanks to [luschmar](https://github.com/luschmar), the playbook now supports bridging to [Meshtastic](https://meshtastic.org/) mesh networks via [meshtastic-matrix-relay](https://github.com/jeremiah-k/meshtastic-matrix-relay) (mmrelay).
+
+To learn more, see our [Setting up a Matrix <-> Meshtastic bridge](./docs/configuring-playbook-bridge-meshtastic-relay.md) documentation page.
+
+## (BC Break) mautrix-telegram has been rewritten in Go (bridgev2)
+
+The [mautrix-telegram](./docs/configuring-playbook-bridge-mautrix-telegram.md) bridge has been [rewritten in Go](https://mau.fi/blog/2026-04-mautrix-release/) on top of the [bridgev2](https://docs.mau.fi/bridges/go/) architecture. See the [upstream v26.04 release notes](https://github.com/mautrix/telegram/releases/tag/v0.2604.0) for what changed in the bridge itself (shared-portal behavior, management-room state, new features, etc.).
+
+**Most users won't have to do anything.** If you use the playbook's integrated Postgres (the default) and haven't customized telegram-bridge variables beyond `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash`, just re-run the playbook; the bridge will migrate itself on first start. Taking a backup beforehand is still a good idea.
+
+⚠️ **SQLite users: do not upgrade yet.** Upstream v0.2604.0 has a [known bug in the legacy SQLite migration](https://github.com/mautrix/telegram/releases/tag/v0.2604.0) that can corrupt your data. The playbook detects this case and will refuse to proceed. Either switch to Postgres first (set `matrix_mautrix_telegram_database_engine: postgres`; the playbook handles the pgloader migration), or wait for the next upstream release.
+
+Playbook-specific things to know. The playbook will fail loudly if you're affected:
+
+- Many `matrix_mautrix_telegram_*` variables have been **removed** (web-login endpoint, lottieconverter, username/alias/displayname templates, filter-mode, bot-token relaybot, Shared-Secret-Auth map). The deprecation check will tell you exactly what to rename or drop when you run the playbook.
+- **Old-style relaybot users** (`matrix_mautrix_telegram_bot_token`): switch to the common [mautrix bridge relay mode](./docs/configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional) via `matrix_mautrix_telegram_bridge_relay_enabled: true`.
+- **Shared-Secret-Auth double-puppeting users**: switch to [Appservice Double Puppet](./docs/configuring-playbook-appservice-double-puppet.md); the playbook wires it up automatically.
+- **Custom `matrix_mautrix_telegram_bridge_permissions`**: map `relaybot` to `relay`, `puppeting` to `user`, `full` to `user`. Validated at playbook time.
+
+# 2026-04-03
+
+## (BC Break) Synapse Admin (fork by etke.cc) is now Ketesa
+
+Synapse Admin has been rebranded to **[Ketesa](https://github.com/etkecc/ketesa)** — a landmark release that introduces a new identity, a full UI redesign, mobile-first layout, and deep Matrix Authentication Service (MAS) integration. For the full story behind the rename and a tour of what's new, see the [Ketesa v1.0.0 announcement](https://etke.cc/blog/introducing-ketesa/).
+
+Ketesa is a zero-configuration drop-in replacement for Synapse Admin: no server-side changes required, just update the role variables.
+
+The `matrix-synapse-admin` role has been **renamed** to `matrix-ketesa`. All `matrix_synapse_admin_*` variables must be **renamed** to `matrix_ketesa_*` in your `vars.yml`.
+
+Additionally, the **Docker image** changed from `ghcr.io/etkecc/synapse-admin` to `ghcr.io/etkecc/ketesa`. The default path prefix remains `/synapse-admin` for backward compatibility — updating to `/ketesa` is recommended but not required.
+
+The playbook will automatically detect leftover `matrix_synapse_admin_*` variables and fail with a helpful message listing what needs to be renamed.
+
+The playbook handles reverse-proxy routing for subpath deployments (e.g. `/ketesa`), including MAS-enabled setups — though OIDC auth flows on real servers still have some rough edges. Feedback is appreciated in [#ketesa:etke.cc](https://matrix.to/#/#ketesa:etke.cc).
+
+See the [Ketesa documentation](docs/configuring-playbook-ketesa.md) for details.
+
+# 2026-04-02
+
+## (BC Break) Draupnir for all Self Service Provisioning is now disabled by default
+
+💡 If you don't use [Draupnir for all](./docs/configuring-playbook-appservice-draupnir-for-all.md), then this breaking change does not concern you..
+
+[Draupnir for all](./docs/configuring-playbook-appservice-draupnir-for-all.md) now ships with `allowSelfServiceProvisioning: false` as default upstream and in this playbook.
+
+This means users can no longer provision Draupnir instances by inviting the appservice bot unless you explicitly opt in.
+
+Manual provisioning by administrators is now the recommended approach. You do not want to enable Self Service Provisioning unless you have additional custom safeguards like those used by asgard.chat in place.
+
+If you want to enable Self Service Provisioning, add the following to your `vars.yml`:
+
+```yaml
+matrix_appservice_draupnir_for_all_configuration_extension_yaml: |
+  allowSelfServiceProvisioning: true
+```
+
+# 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

Makefile

@@ -2,11 +2,14 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-.PHONY: roles lint
+.PHONY: roles lint add-inventory-host
 
 help: ## Show this help.
 	@grep -F -h "##" $(MAKEFILE_LIST) | grep -v grep | sed -e 's/\\$$//' | sed -e 's/##//'
 
+add-inventory-host: ## Adds a new host to the inventory, creating the inventory files if necessary (e.g. `make add-inventory-host domain=example.com ip=1.2.3.4`)
+	@./bin/add-inventory-host.sh "$(domain)" "$(ip)"
+
 roles: ## Pull roles
 	rm -rf roles/galaxy
 	ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force

README.md

@@ -4,7 +4,7 @@
 
 ## 🎯 Purpose
 
-This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#supported-services) related to that.
+This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#-supported-services) related to that.
 
 That is, it lets you join the Matrix network using your own user ID like `@alice:example.com`, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
 
@@ -53,6 +53,7 @@ The homeserver is the backbone of your Matrix system. Choose one from the follow
 | [Synapse](https://github.com/element-hq/synapse) | ✅ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network | [Link](docs/configuring-playbook-synapse.md) |
 | [Conduit](https://conduit.rs) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements | [Link](docs/configuring-playbook-conduit.md) |
 | [continuwuity](https://continuwuity.org) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. | [Link](docs/configuring-playbook-continuwuity.md) |
+| [Tuwunel](https://matrix-construct.github.io/tuwunel/) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Tuwunel is the official successor to conduwuit. | [Link](docs/configuring-playbook-tuwunel.md) |
 | [Dendrite](https://github.com/element-hq/dendrite) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse. | [Link](docs/configuring-playbook-dendrite.md) |
 
 ### Clients
@@ -64,8 +65,10 @@ 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/SableClient/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) |
+| [Commet](https://github.com/commetchat/commet) | ❌ | Matrix web client | [Link](docs/configuring-playbook-client-commet.md) |
 
 ### Server Components
 
@@ -90,8 +93,6 @@ Extend and modify how users are authenticated on your homeserver.
 | [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) (advanced) | ❌ | REST authentication password provider module | [Link](docs/configuring-playbook-rest-auth.md) |
 |[matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) (advanced) | ❌ | Password provider module | [Link](docs/configuring-playbook-shared-secret-auth.md) |
 | [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) (advanced) | ❌ | LDAP Auth password provider module | [Link](docs/configuring-playbook-ldap-auth.md) |
-| [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | ❌ | Proxy that handles Matrix registration requests and forwards them to LDAP | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
-| [matrix-registration](https://github.com/ZerataX/matrix-registration) | ❌ | Simple python application to have a token based Matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
 | [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
 | [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | Spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
 
@@ -115,22 +116,25 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [mautrix-slack](https://github.com/mautrix/slack) | ❌ | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-mautrix-slack.md) |
 | [mautrix-telegram](https://github.com/mautrix/telegram) | ❌ | Bridge to [Telegram](https://telegram.org/) | [Link](docs/configuring-playbook-bridge-mautrix-telegram.md) |
 | [mautrix-gmessages](https://github.com/mautrix/gmessages) | ❌ | Bridge to [Google Messages](https://messages.google.com/) | [Link](docs/configuring-playbook-bridge-mautrix-gmessages.md) |
+| [mautrix-gvoice](https://github.com/mautrix/gvoice) | ❌ | Bridge to [Google Voice](https://voice.google.com/) | [Link](docs/configuring-playbook-bridge-mautrix-gvoice.md) |
+| [mautrix-linkedin](https://github.com/mautrix/linkedin) | ❌ | Bridge to [LinkedIn](https://www.linkedin.com/) | [Link](docs/configuring-playbook-bridge-mautrix-linkedin.md) |
 | [mautrix-whatsapp](https://github.com/mautrix/whatsapp) | ❌ | Bridge to [WhatsApp](https://www.whatsapp.com/) | [Link](docs/configuring-playbook-bridge-mautrix-whatsapp.md) |
 | [mautrix-wsproxy](https://github.com/mautrix/wsproxy) | ❌ | Bridge to Android SMS or Apple iMessage | [Link](docs/configuring-playbook-bridge-mautrix-wsproxy.md) |
+| [matrix-rustpush-bridge](https://github.com/jasonlaguidice/imessage) | ❌ | Bridge to [iMessage](https://support.apple.com/messages) via Apple Push Notification service | [Link](docs/configuring-playbook-bridge-rustpush.md) |
 | [mautrix-bluesky](https://github.com/mautrix/bluesky) | ❌ | Bridge to [Bluesky](https://bsky.social/) | [Link](docs/configuring-playbook-bridge-mautrix-bluesky.md) |
 | [mautrix-twitter](https://github.com/mautrix/twitter) | ❌ | Bridge to [Twitter](https://twitter.com/) | [Link](docs/configuring-playbook-bridge-mautrix-twitter.md) |
 | [mautrix-googlechat](https://github.com/mautrix/googlechat) | ❌ | Bridge to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) | [Link](docs/configuring-playbook-bridge-mautrix-googlechat.md) |
-| [mautrix-meta](https://github.com/mautrix/instagram) | ❌ | Bridge to [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) | Link for [Messenger](docs/configuring-playbook-bridge-mautrix-meta-messenger.md) / [Instagram](docs/configuring-playbook-bridge-mautrix-meta-instagram.md) |
+| [mautrix-meta](https://github.com/mautrix/meta) | ❌ | Bridge to [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) | Link for [Messenger](docs/configuring-playbook-bridge-mautrix-meta-messenger.md) / [Instagram](docs/configuring-playbook-bridge-mautrix-meta-instagram.md) |
 | [mautrix-signal](https://github.com/mautrix/signal) | ❌ | Bridge to [Signal](https://www.signal.org/) | [Link](docs/configuring-playbook-bridge-mautrix-signal.md) |
-| [beeper-linkedin](https://github.com/beeper/linkedin) | ❌ | Bridge to [LinkedIn](https://www.linkedin.com/) | [Link](docs/configuring-playbook-bridge-beeper-linkedin.md) |
+| [beeper-line](https://github.com/beeper/line) | ❌ | Bridge to [LINE](https://line.me/) | [Link](docs/configuring-playbook-bridge-beeper-line.md) |
 | [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) | ❌ | Bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-appservice-irc.md) |
-| [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) | ❌ | Bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) | [Link](docs/configuring-playbook-bridge-appservice-kakaotalk.md) |
 | [matrix-appservice-discord](https://github.com/matrix-org/matrix-appservice-discord) | ❌ | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-appservice-discord.md) |
 | [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) | ❌ | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | [Link](docs/configuring-playbook-bridge-hookshot.md) |
 | [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | ❌ | Bridge to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) |
 | [matrix-steam-bridge](https://github.com/jasonlaguidice/matrix-steam-bridge) | ❌ | Bridge to [Steam](https://steampowered.com/) | [Link](docs/configuring-playbook-bridge-steam.md) |
 | [matrix-wechat](https://github.com/duo/matrix-wechat) | ❌ | Bridge to [WeChat](https://www.wechat.com/) | [Link](docs/configuring-playbook-bridge-wechat.md) |
 | [Heisenbridge](https://github.com/hifi/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-heisenbridge.md) |
+| [meshtastic-matrix-relay](https://github.com/jeremiah-k/meshtastic-matrix-relay) | ❌ | Bridge to [Meshtastic](https://meshtastic.org/) mesh networks | [Link](docs/configuring-playbook-bridge-meshtastic-relay.md) |
 | [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | ❌ | Bridge to [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) |
 | [mx-puppet-steam](https://codeberg.org/icewind/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) |
 | [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) |
@@ -143,11 +147,11 @@ Bots provide various additional functionality to your installation.
 | ---- | -------- | ----------- | ------------- |
 | [baibot](https://github.com/etkecc/baibot) | ❌ | Bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you | [Link](docs/configuring-playbook-bot-baibot.md) |
 | [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) | ❌ | Bot for scheduling one-off & recurring reminders and alarms | [Link](docs/configuring-playbook-bot-matrix-reminder-bot.md) |
-| [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) | ❌ | Bot for invitations by creating and managing registration tokens | [Link](docs/configuring-playbook-bot-matrix-registration-bot.md) |
 | [maubot](https://github.com/maubot/maubot) | ❌ | Plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
 | [Honoroit](https://github.com/etkecc/honoroit) | ❌ | Helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
 | [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | Moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
 | [Draupnir](https://github.com/the-draupnir-project/Draupnir) | ❌ | Moderation tool for Matrix (Fork of Mjolnir) | [Link](docs/configuring-playbook-bot-draupnir.md) (for [appservice mode](docs/configuring-playbook-appservice-draupnir-for-all.md))|
+| [Meowlnir](https://github.com/maunium/meowlnir) | ❌ | Moderation tool for Matrix, running in appservice mode | [Link](docs/configuring-playbook-bot-meowlnir.md) |
 | [Buscarron](https://github.com/etkecc/buscarron) | ❌ | Web forms (HTTP POST) to Matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
 
 ### Administration
@@ -158,7 +162,7 @@ Services that help you in administrating and monitoring your Matrix installation
 | ---- | -------- | ----------- | ------------- |
 | [matrix-alertmanager-receiver](https://github.com/metio/matrix-alertmanager-receiver) | ❌ | Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) client | [Link](docs/configuring-playbook-alertmanager-receiver.md) |
 | [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) | ❌ | OAuth 2.0 and OpenID Provider server | [Link](docs/configuring-playbook-matrix-authentication-service.md) |
-| [synapse-admin](https://github.com/etkecc/synapse-admin) | ❌ | Web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
+| [Ketesa](https://github.com/etkecc/ketesa) | ❌ | Fully-featured web UI for administrating your Matrix homeserver — users, rooms, media, sessions, and more | [Link](docs/configuring-playbook-ketesa.md) |
 | Metrics and Graphs | ❌ | Consists of the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI, with [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) being available too | [Link](docs/configuring-playbook-prometheus-grafana.md) (for [prometheus-nginxlog-exporter](docs/configuring-playbook-prometheus-grafana.md#enable-metrics-and-graphs-for-nginx-logs-optional)) |
 | [Borg](https://borgbackup.org) | ❌ | Backups | [Link](docs/configuring-playbook-backup-borg.md) |
 | [rageshake](https://github.com/matrix-org/rageshake) | ❌ | Bug report server | [Link](docs/configuring-playbook-rageshake.md) |

bin/add-inventory-host.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Adds a new host to the inventory, based on the example files in `examples/`:
+# - creates `inventory/hosts` (or adds the host to it, if it already exists)
+# - creates `inventory/host_vars/matrix.DOMAIN/vars.yml` with strong secrets generated automatically
+#
+# Existing configuration for the same host is never overwritten - the script refuses to run instead.
+#
+# Usage: bin/add-inventory-host.sh <base-domain> <server-address>
+#
+# - <base-domain> is the base domain (`example.com`), not the Matrix server hostname (`matrix.example.com`)
+# - <server-address> is the server's external IP address or domain name
+
+set -euo pipefail
+
+base_path="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if [ $# -ne 2 ]; then
+	echo "Usage: $0 <base-domain> <server-address>" >&2
+	echo "Example: $0 example.com 1.2.3.4" >&2
+	exit 1
+fi
+
+domain="$1"
+server_address="$2"
+
+if ! printf '%s' "${domain}" | grep -Eq '^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)+$'; then
+	echo "Error: '${domain}' does not look like a valid domain name" >&2
+	exit 1
+fi
+
+if ! printf '%s' "${server_address}" | grep -Eq '^[A-Za-z0-9.:_-]+$'; then
+	echo "Error: '${server_address}' does not look like a valid server address (IP address or domain name)" >&2
+	exit 1
+fi
+
+case "${domain}" in
+	matrix.*)
+		echo "Warning: you likely need to pass your base domain (example.com), not the Matrix server hostname (matrix.example.com)." >&2
+		echo "Proceeding anyway. Your Matrix server hostname will be: matrix.${domain}" >&2
+		;;
+esac
+
+matrix_hostname="matrix.${domain}"
+hosts_file="${base_path}/inventory/hosts"
+vars_dir="${base_path}/inventory/host_vars/${matrix_hostname}"
+vars_file="${vars_dir}/vars.yml"
+hosts_entry="${matrix_hostname} ansible_host=${server_address} ansible_ssh_user=root"
+
+if [ -e "${vars_dir}" ]; then
+	echo "Error: ${vars_dir} already exists. Refusing to overwrite it." >&2
+	exit 1
+fi
+
+if [ -f "${hosts_file}" ]; then
+	if ! grep -q '^\[matrix_servers\]' "${hosts_file}"; then
+		echo "Error: ${hosts_file} exists, but does not contain a [matrix_servers] section." >&2
+		echo "Unrecognized inventory format. Add the host to it manually:" >&2
+		echo "${hosts_entry}" >&2
+		exit 1
+	fi
+
+	matrix_hostname_pattern="$(printf '%s' "${matrix_hostname}" | sed 's|\.|\\.|g')"
+	if grep -Eq "^${matrix_hostname_pattern}([[:space:]]|$)" "${hosts_file}"; then
+		echo "Error: ${hosts_file} already contains an entry for ${matrix_hostname}. Refusing to modify it." >&2
+		exit 1
+	fi
+fi
+
+generate_secret() {
+	if command -v pwgen >/dev/null 2>&1; then
+		pwgen -s 64 1
+	elif command -v openssl >/dev/null 2>&1; then
+		openssl rand -base64 192 | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 64
+	else
+		head -c 4096 /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 64
+	fi
+}
+
+generic_secret_key="$(generate_secret)"
+postgres_password="$(generate_secret)"
+
+for secret in "${generic_secret_key}" "${postgres_password}"; do
+	if [ "${#secret}" -lt 64 ]; then
+		echo "Error: failed to generate a secret" >&2
+		exit 1
+	fi
+done
+
+mkdir -p "${vars_dir}"
+
+sed \
+	-e "s|^matrix_domain:.*|matrix_domain: ${domain}|" \
+	-e "s|^matrix_homeserver_generic_secret_key:.*|matrix_homeserver_generic_secret_key: '${generic_secret_key}'|" \
+	-e "s|^postgres_connection_password:.*|postgres_connection_password: '${postgres_password}'|" \
+	"${base_path}/examples/vars.yml" > "${vars_file}"
+
+if [ -f "${hosts_file}" ]; then
+	# Insert the new host right after the [matrix_servers] section header.
+	hosts_file_tmp="$(mktemp "${hosts_file}.XXXXXX")"
+	awk -v entry="${hosts_entry}" '{print} $0 ~ /^\[matrix_servers\]/ && !done {print entry; done=1}' \
+		"${hosts_file}" > "${hosts_file_tmp}"
+	mv "${hosts_file_tmp}" "${hosts_file}"
+else
+	sed \
+		-e "s|^matrix\.example\.com .*|${hosts_entry}|" \
+		"${base_path}/examples/hosts" > "${hosts_file}"
+fi
+
+echo "Added host ${matrix_hostname} to the inventory:"
+echo "- ${hosts_file}"
+echo "- ${vars_file}"
+echo ""
+echo "Secrets were generated automatically for matrix_homeserver_generic_secret_key and postgres_connection_password."
+echo "Review and adjust these files before installing."

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

bin/rebuild-mautrix-meta-instagram.sh

@@ -1,54 +0,0 @@
-#!/bin/bash
-
-# SPDX-FileCopyrightText: 2024 Slavi Pantaleev
-#
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-set -euxo pipefail
-
-# This script rebuilds the mautrix-meta-instagram Ansible role, using the mautrix-meta-messenger role as a source.
-
-if [ $# -eq 0 ]; then
-	echo "Error: No argument supplied. Please provide the path to the roles/custom directory."
-	exit 1
-fi
-
-roles_path=$1
-
-messenger_role_path=$roles_path/matrix-bridge-mautrix-meta-messenger
-instagram_role_path=$roles_path/matrix-bridge-mautrix-meta-instagram
-
-if [ ! -d $messenger_role_path ]; then
-	echo "Cannot find: $messenger_role_path"
-	exit 1
-fi
-
-if [ -d $instagram_role_path ]; then
-	rm -rf $instagram_role_path
-fi
-
-cp -ar $messenger_role_path $instagram_role_path
-
-find "$instagram_role_path" -type f | while read -r file; do
-	sed --in-place 's/matrix_mautrix_meta_messenger_/matrix_mautrix_meta_instagram_/g' "$file"
-	sed --in-place 's/mautrix-meta-messenger/mautrix-meta-instagram/g' "$file"
-done
-
-sed --in-place 's/matrix_mautrix_meta_instagram_meta_mode: \(.*\)/matrix_mautrix_meta_instagram_meta_mode: instagram/g' $instagram_role_path/defaults/main.yml
-sed --in-place 's/matrix_mautrix_meta_instagram_identifier: \(.*\)/matrix_mautrix_meta_instagram_identifier: matrix-mautrix-meta-instagram/g' $instagram_role_path/defaults/main.yml
-
-# Create the README.md file with the license header
-cat > $instagram_role_path/README.md << 'EOF'
-<!--
-SPDX-FileCopyrightText: 2024 - 2025 MDAD Contributors
-
-SPDX-License-Identifier: AGPL-3.0-or-later
--->
-EOF
-
-echo "" >> $instagram_role_path/README.md
-echo "# matrix-mautrix-meta-instagram" >> $instagram_role_path/README.md
-echo "" >> $instagram_role_path/README.md
-echo "This bridge role is derived from the matrix-mautrix-meta-messenger Ansible role via automatic changes (see \`just rebuild-mautrix-meta-instagram\` or \`bin/rebuild-mautrix-meta-instagram.sh\`)." >> $instagram_role_path/README.md
-echo "" >> $instagram_role_path/README.md
-echo "If you'd like to make a change to this role, consider making it to the \`matrix-mautrix-meta-messenger\` role instead." >> $instagram_role_path/README.md

collections/requirements.yml

@@ -1,4 +1,25 @@
 ---
+# This file is not used by the playbook's standard CLI installation flow.
+# Roles are pulled via `make roles` / `just roles`, which call
+# `ansible-galaxy install -r requirements.yml -p roles/galaxy/`.
+# Collections are not installed by that command, and the playbook relies
+# on whatever `community.*` collections ship with the user's `ansible`
+# package (which has been recent enough for years).
+#
+# This file exists for AWX / Ansible Automation Platform users, which
+# auto-detect `collections/requirements.yml` during project sync and
+# install the listed collections. See:
+# https://github.com/spantaleev/matrix-docker-ansible-deploy/commit/87a2240dc
+#
+# CLI users do not need to install anything from this file. If you are
+# using AWX and a collection version below the floor declared here is
+# present, AWX will upgrade it.
+
 collections:
   - name: community.general
   - name: community.docker
+    # `community.docker.docker_image_pull` and `community.docker.docker_image_build`
+    # are used by some roles (e.g. matrix-bot-draupnir,
+    # matrix-appservice-draupnir-for-all) and are first available in
+    # community.docker 3.6.0 (Jan 2024 / Ansible 9.2.0).
+    version: ">=3.6.0"

docs/README.md

@@ -76,6 +76,8 @@ If your server and services experience issues, feel free to come to [our support
 
 - [Alternative architectures](alternative-architectures.md)
 
+- [Configuring Synology DSM](configuring-playbook-synology.md)
+
 - [Container images used by the playbook](container-images.md)
 
 - [Obtaining an Access Token](obtaining-access-tokens.md)
@@ -88,6 +90,8 @@ If your server and services experience issues, feel free to come to [our support
 
 - [Self-building](self-building.md)
 
+- [Style guide for playbook developers](style-guide.md)
+
 - [Uninstalling](uninstalling.md)
 
 - [Updating users passwords](updating-users-passwords.md)

docs/ansible.md

@@ -39,6 +39,18 @@ If using the `pip` method, do note that the `ansible-playbook` binary may not be
 
 **Note**: Both of the above methods are a bad way to run system software such as Ansible. If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
 
+## SSH host key and passphrase prompts
+
+If Ansible fails with `Host key verification failed` (or a similar `Data could not be sent to remote host` error) without asking you to confirm the SSH host key of your server, you're likely on Ansible 2.21 or later.
+
+Since Ansible 2.21, forked workers call `setsid()` and thus lose the controlling terminal. SSH cannot open `/dev/tty` anymore, so it can no longer ask you to confirm an unknown host key or prompt you for the passphrase of an SSH key.
+
+To fix host key errors, connect to the server once (e.g. `ssh root@matrix.example.com`) and confirm the host key. Ansible runs after that will find it in your `known_hosts` file.
+
+If your SSH key is protected by a passphrase, load it into an [ssh-agent](https://man.openbsd.org/ssh-agent) (e.g. `ssh-add ~/.ssh/id_ed25519`), so that SSH does not need to prompt for the passphrase.
+
+**Note**: if you're [using Ansible via Docker](#using-ansible-via-docker), host keys of previously unknown hosts are accepted automatically, so only the passphrase advice above applies to you. For the agent to be reachable inside the container, share its socket by adding `--mount type=bind,src=$SSH_AUTH_SOCK,dst=/ssh-agent --env SSH_AUTH_SOCK=/ssh-agent` to `docker run`. If the key is already loaded into the agent, you do not need to mount the SSH key file into the container at all.
+
 ## Using Ansible via Docker
 
 Alternatively, you can run Ansible inside a Docker container (powered by the [ghcr.io/devture/ansible](https://github.com/devture/docker-ansible/pkgs/container/ansible) Docker image).
@@ -50,6 +62,8 @@ This ensures that:
 
 You can either [run Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself) or [run Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server).
 
+💡 If you use [Visual Studio Code](https://code.visualstudio.com/) or [GitHub Codespaces](https://github.com/features/codespaces), the playbook also ships a [dev container](https://containers.dev/) configuration (see the `.devcontainer/` directory) based on this same Ansible Docker image, which can prepare such a containerized Ansible environment for you automatically.
+
 ### Running Ansible in a container on the Matrix server itself
 
 To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation. Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
@@ -74,7 +88,7 @@ docker run \
 -w /work \
 --mount type=bind,src=`pwd`,dst=/work \
 --entrypoint=/bin/sh \
-ghcr.io/devture/ansible:11.6.0-r0-0
+ghcr.io/devture/ansible:14.0.0-r0-3
 ```
 
 Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container. The `/work` directory contains the playbook's code.
@@ -95,7 +109,7 @@ docker run \
 --mount type=bind,src=`pwd`,dst=/work \
 --mount type=bind,src=$HOME/.ssh/id_ed25519,dst=/root/.ssh/id_ed25519,ro \
 --entrypoint=/bin/sh \
-ghcr.io/devture/ansible:11.6.0-r0-0
+ghcr.io/devture/ansible:14.0.0-r0-3
 ```
 
 The above command tries to mount an SSH key (`$HOME/.ssh/id_ed25519`) into the container (at `/root/.ssh/id_ed25519`). If your SSH key is at a different path (not in `$HOME/.ssh/id_ed25519`), adjust that part.

docs/configuring-captcha.md

@@ -15,6 +15,8 @@ Captcha can be enabled for this home server. This file explains how to do that.
 
 The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.
 
+If you are using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), captcha is configured there instead (it handles registration), and [Cloudflare Turnstile](https://www.cloudflare.com/application-services/products/turnstile/) is supported as well. See [Matrix Authentication Service](#matrix-authentication-service) below.
+
 ## ReCaptcha
 
 ### Getting keys
@@ -61,3 +63,16 @@ matrix_dendrite_client_api_recaptcha_api_js_url: 'https://js.hcaptcha.com/1/api.
 matrix_dendrite_client_api_recaptcha_form_field: 'h-captcha-response'
 matrix_dendrite_client_api_recaptcha_sitekey_class: 'h-captcha'
 ```
+
+## Matrix Authentication Service
+
+When [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) is enabled, registration and other account operations are handled by it, so captcha protection is configured there (the Synapse and Dendrite settings above do not apply).
+
+Matrix Authentication Service supports [ReCaptcha v2](http://www.google.com/recaptcha/admin), [Cloudflare Turnstile](https://www.cloudflare.com/application-services/products/turnstile/) and [hCaptcha](https://dashboard.hcaptcha.com/sites/new). Obtain a site/secret key pair from your chosen service, then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Valid values: recaptcha_v2, cloudflare_turnstile, hcaptcha
+matrix_authentication_service_config_captcha_service: recaptcha_v2
+matrix_authentication_service_config_captcha_site_key: 'YOUR_SITE_KEY'
+matrix_authentication_service_config_captcha_secret_key: 'YOUR_SECRET_KEY'
+```

docs/configuring-ipv6.md

@@ -109,7 +109,7 @@ If you do have an IPv6 address, it's still worth [using curl](#with-curl) to con
 The `devture_systemd_docker_base_ipv6_enabled` setting controls whether container networks will be created with IPv6 support.
 
 Changing this setting subsequently requires manual work (deleting all container networks).
-See [I've changed the `devture_systemd_docker_base_ipv6_enabled` setting, but it doesn't seem to have any effect](#i-ve-changed-the-devture_systemd_docker_base_ipv6_enabled-setting-but-it-doesn-t-seem-to-have-any-effect).
+See [I've changed the `devture_systemd_docker_base_ipv6_enabled` setting, but it doesn't seem to have any effect](#ive-changed-the-devture_systemd_docker_base_ipv6_enabled-setting-but-it-doesnt-seem-to-have-any-effect).
 
 #### I've changed the `devture_systemd_docker_base_ipv6_enabled` setting, but it doesn't seem to have any effect.
 

docs/configuring-playbook-appservice-draupnir-for-all.md

@@ -1,4 +1,5 @@
 <!--
+SPDX-FileCopyrightText: 2024 - 2026 Catalan Lover <catalanlover@protonmail.com>
 SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 MDAD project contributors
 
@@ -13,34 +14,54 @@ Appservice mode can be used together with the regular [Draupnir bot](configuring
 
 ## Draupnir Appservice mode compared to Draupnir bot mode
 
-The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
+The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode.
 
-Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All (Even though the commands do show up in help).
+Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All.
 
 Draupnir for all in the playbook is rate-limit-exempt automatically as its appservice configuration file does not specify any rate limits.
 
-Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as D4A even on the branch with the Avatar command (To be Upstreamed to Mainline Draupnir) that command is clunky as it requires the use of things like Element Web devtools. In normal Draupnir this is a quick operation where you login to Draupnir with a normal client and set Avatar and Display name normally.
+Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as the avatar command is clunky as it requires the use of things like Element Web devtools. In normal Draupnir this can be done while logged in to the Draupnir account with a normal client and set Avatar and Display name normally.
 
-Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
+Draupnir for all only has limited support for external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
 
 ## Prerequisites
 
-### Create a main management room
+### Prerequisites for Zero Touch Deployment (recommended)
 
-The playbook does not create a management room for your Main Draupnir. You **need to create the room manually** before setting up the bot.
+As of Draupnir 3.1.0, Zero Touch Deployment of Draupnir Appservice Mode (Draupnir for all) requires you to supply the following:
+
+- MXID of the first person who gets invited to the admin room that the bot creates for you.
+
+That is all. The appservice manages everything on its own after you provide it with an MXID to invite.
+
+If proceeding with Zero Touch Deployment, skip ahead to [Adjusting the playbook configuration](#adjusting-the-playbook-configuration).
+
+### Create an admin room (optional)
+
+The playbook does not create an admin room for your Draupnir, but the appservice itself can do this for you. Alternatively, you **can create the room manually** before setting up the bot.
 
 Note that the room must be unencrypted.
 
-The management room has to be given an alias, and your bot has to be invited to the room.
+The admin room has to be given an alias, and your bot has to be invited to the room.
 
-This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
+This admin room is used to control who has access to your D4A deployment. The room stores this data in the control room state, so your bot must have sufficient power level to send custom state events. This is `50` by default (moderator, as Element clients call this power level).
 
 > [!WARNING]
 > Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE`.
+When using Zero Touch Deployment, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE` with the MXID of the user who should be invited to the admin room first.
+
+```yaml
+matrix_appservice_draupnir_for_all_enabled: true
+
+matrix_appservice_draupnir_for_all_zero_touch_deploy: true
+
+matrix_appservice_draupnir_for_all_config_initialManager: "INITIAL_MANAGER_MXID_HERE"
+```
+
+If opting out of Zero Touch Deployment, use the following configuration block instead. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE` with the alias of the admin room you have created earlier.
 
 ```yaml
 matrix_appservice_draupnir_for_all_enabled: true
@@ -48,6 +69,14 @@ matrix_appservice_draupnir_for_all_enabled: true
 matrix_appservice_draupnir_for_all_config_adminRoom: "MANAGEMENT_ROOM_ALIAS_HERE"
 ```
 
+### Running both bot mode and appservice mode
+
+When running both [bot mode](./configuring-playbook-bot-draupnir.md) and appservice mode, the playbook will force-restart
+the bot if running a non-release tag like `latest` or `main` or a development build.
+This is due to the conditional restart logic not being able to reliably tell when an update happened.
+
+Conditional restarts work correctly for all tags when running only one of these two operating modes.
+
 ### Extending the configuration
 
 There are some additional things you may wish to configure about the component.
@@ -95,20 +124,26 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
 ## Usage
 
-If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have successfully installed Draupnir for All and can now start using it.
+If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com`, you have successfully installed Draupnir for All and can now start using it.
 
-The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
+If using Zero Touch Deployment, the flow is reversed and the success signal is the initial manager account being invited to the admin room.
+
+Draupnir for all installation via this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode, except that protections requiring homeserver admin access are not available, and the config file is shared between all bots so legacy protections like wordlist share a single global config.
 
 ### Granting Users the ability to use D4A
 
 Draupnir for all includes several security measures like that it only allows users that are on its allow list to ask for a bot. To add a user to this list we have 2 primary options. Using the chat to tell Draupnir to do this for us or if you want to automatically do it by sending `m.policy.rule.user` events that target the subject you want to allow provisioning for with the `org.matrix.mjolnir.allow` recommendation. Using the chat is recommended.
 
-The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
+The bot requires a power level of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297).) This issue is largely mitigated by the Zero Touch Deployment workflows introduced in Draupnir 3.1.0.
 
-To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
+To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to provision a bot. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
 
 ### How to provision a D4A once you are allowed to
 
-To provision a D4A, you need to start a chat with `@draupnir-main:example.com`. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
+Once someone is allowed to provision a bot, simply provision them one with `!admin provision MXID`.
 
-Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
+Self-service provisioning is disabled as a security measure because it is currently bugged. Force-provisioning (with `!admin provision`) bypasses this disabled status.
+
+Note that you should always make sure there is an allow entry matching whoever is provisioned, because once self-service is fixed, the bot of anyone who is not allowed to provision a bot will refuse to start.
+
+Congratulations if you made it all the way here, because you now have a fully working Draupnir for all deployment.

docs/configuring-playbook-bot-baibot.md

@@ -14,7 +14,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 🤖 [baibot](https://github.com/etkecc/baibot) (pronounced bye-bot) is a [Matrix](https://matrix.org/) bot developed by [etke.cc](https://etke.cc/) that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you. 🤖
 
-It supports [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) models, as many well as other [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
+It supports many [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md), including the privacy-first [Venice](#venice) we recommend, [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) models, and more.
 
 It's designed as a more private and [✨ featureful](https://github.com/etkecc/baibot/?tab=readme-ov-file#-features) alternative to [matrix-chatgpt-bot](./configuring-playbook-bot-chatgpt.md). See the [baibot](https://github.com/etkecc/baibot) project and its documentation for more information.
 
@@ -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`.
 #
@@ -140,7 +159,38 @@ Agents defined statically and those created dynamically (via chat) are named dif
 
 Depending on your propensity for [GitOps](https://en.wikipedia.org/wiki/DevOps#GitOps), you may prefer to define agents statically via Ansible, or you may wish to do it dynamically via chat.
 
-Before proceeding, we recommend reading the upstream documentation on [How to choose a provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#how-to-choose-a-provider). In short, it's probably best to go with [OpenAI](#openai).
+Before proceeding, we recommend reading the upstream documentation on [How to choose a provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#how-to-choose-a-provider) for a side-by-side of what each one can do. In short: we recommend [Venice](#venice), the most capable provider baibot supports and the only one that keeps no logs and trains on nothing. If you'd rather start with the most widely-used option, [OpenAI](#openai) is a solid, well-supported choice too.
+
+#### Venice
+
+[Venice](https://venice.ai/chat?ref=kpXDe6) _(ref link with a $10 bonus for you)_ is the provider we recommend. It's the most capable one baibot supports, and the only one that pairs that full feature set with real privacy: inference runs on Venice's own GPUs or on zero-data-retention partner hardware, so your prompts and replies are stored nowhere and never used for training. It serves both frontier proprietary models and the latest open-source ones.
+
+Venice also leaves the content policy to you instead of imposing its own. Its models answer without the reflexive refusals some hosted services apply, and both text and image generation can handle adult or otherwise sensitive subjects when you need them to. Image generation ships a `safe_mode` that blurs adult content by default; you can turn it off (see the sample config). This pairs naturally with the privacy above: a bot you can speak to candidly, that keeps nothing.
+
+Unlike the [OpenAI Compatible](#openai-compatible) provider (which can also point at Venice, but drops images and can't reach its audio or native image endpoints), this is a first-class integration that exposes Venice's full parameter set: text-generation with vision, file inputs, prompt caching and native web search, plus speech-to-text, text-to-speech, and image generation and editing.
+
+You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Venice provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#venice) with the help of the playbook's preset variables.
+
+Here's an example **addition** to your `vars.yml` file:
+
+```yaml
+matrix_bot_baibot_config_agents_static_definitions_venice_enabled: true
+
+matrix_bot_baibot_config_agents_static_definitions_venice_config_api_key: "YOUR_API_KEY_HERE"
+
+# The preset ships sensible defaults for every purpose, so changing only the API key above is enough
+# to get going. Uncomment and adjust any of these if you'd like to use different models:
+# matrix_bot_baibot_config_agents_static_definitions_venice_config_text_generation_model_id: kimi-k2-5
+# matrix_bot_baibot_config_agents_static_definitions_venice_config_image_generation_model_id: chroma
+```
+
+Because this is a [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agent, it will be given a `static/` ID prefix and will be named `static/venice`.
+
+Every Venice knob (sampling, caching, reasoning, web-search behavior, voice and image controls) has a matching `matrix_bot_baibot_config_agents_static_definitions_venice_config_*` variable. The [fully-commented sample config](https://github.com/etkecc/baibot/blob/main/docs/sample-provider-configs/venice.yml) explains every one of them.
+
+If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
+
+💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
 
 #### Anthropic
 
@@ -355,7 +405,7 @@ Example **additional** `vars.yml` configuration:
 # As such, changing any of these values subsequently has no effect on the bot's behavior.
 # Once initially configured, the global configuration is managed via bot commands, not via Ansible.
 
-matrix_bot_baibot_config_initial_global_config_handler_catch_all: static/openai
+matrix_bot_baibot_config_initial_global_config_handler_catch_all: static/venice
 
 # In this example, there's no need to define any of these below.
 # Configuring the catch-all purpose handler is enough.
@@ -387,13 +437,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 [Ketesa](configuring-playbook-ketesa.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-bot-buscarron.md

@@ -89,7 +89,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
   `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_buscarron_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_buscarron_password` to let the bot know its new password.
+- If you change the bot password (`matrix_bot_buscarron_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 [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-draupnir.md

@@ -1,4 +1,5 @@
 <!--
+SPDX-FileCopyrightText: 2023 - 2026 Catalan Lover <catalanlover@protonmail.com>
 SPDX-FileCopyrightText: 2023 - 2025 MDAD project contributors
 SPDX-FileCopyrightText: 2023 Kim Brose
 SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
@@ -15,19 +16,35 @@ See the project's [documentation](https://the-draupnir-project.github.io/draupni
 
 This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead.
 
-If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
+**Note**: you can also use the [Meowlnir](configuring-playbook-bot-meowlnir.md) or [Mjolnir](configuring-playbook-bot-mjolnir.md) bots, which speak the same [policy list](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists) protocol.
+
+When migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
 
 ## Prerequisites
 
-### Create a management room
+### Prerequisites for Zero Touch Deployment (recommended)
+
+As of Draupnir 3.1.0, Zero Touch Deployment of Draupnir bot mode requires you to supply the following:
+
+- MXID of the first person who gets invited to the management room that the bot creates for you.
+- A permanent access token for authentication. Instructions for obtaining one can be found at [obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl).
+- A user account for Draupnir.
+
+Zero Touch Deployment is the officially preferred installation method for new deployments of Draupnir as of 3.1.0.
+
+### Create a management room (optional)
 
 Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room.
 
 > [!WARNING]
 > Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
 
+The bot also needs at least a Moderator power level (50) in this room. This power level is granted in a [later step](#create-and-invite-the-bot-to-the-management-room-only-when-using-native-login-without-zero-touch-deployment), after the bot gets invited to the room.
+
 It is possible to make the management room encrypted (E2EE). If doing so, then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
 
+E2EE support for the management room is mutually exclusive with Zero Touch Deployment of Draupnir.
+
 Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
 
 ## End-to-End Encryption support
@@ -63,7 +80,25 @@ matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
 
 ## Adjusting the playbook configuration
 
-To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created earlier.
+### Configuration for Zero Touch Deployment (recommended)
+
+To enable the bot using Zero Touch Deployment, add the following configuration to your `vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE` with the MXID of the user who should be invited to the management room first, and `CLEAN_ACCESS_TOKEN_HERE` with the access token you obtained.
+
+```yaml
+# Enable Draupnir
+matrix_bot_draupnir_enabled: true
+
+matrix_bot_draupnir_zero_touch_deploy: true
+
+matrix_bot_draupnir_config_initialManager: "INITIAL_MANAGER_MXID_HERE"
+
+# Access token which the bot will use for logging in.
+matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
+```
+
+### Configuration without Zero Touch Deployment
+
+If you'd prefer to have the bot manage its own login at the cost of having to create the management room manually, you can use native login with the configuration block below. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the ID of the management room you have created earlier.
 
 ```yaml
 # Enable Draupnir
@@ -82,7 +117,15 @@ matrix_bot_draupnir_login_native: true
 matrix_bot_draupnir_config_managementRoom: "MANAGEMENT_ROOM_ID_HERE"
 ```
 
-### Create and invite the bot to the management room
+### Running both bot mode and appservice mode
+
+When running both bot mode and [appservice mode (Draupnir for all)](./configuring-playbook-appservice-draupnir-for-all.md), the
+playbook will force-restart the bot if running a non-release tag like `latest` or `main` or a development build.
+This is due to the conditional restart logic not being able to reliably tell when an update happened.
+
+Conditional restarts work correctly for all tags when running only one of these two operating modes.
+
+### Create and invite the bot to the management room (only when using native login without Zero Touch Deployment)
 
 Before proceeding to the next step, run the playbook with the following command to create the bot user.
 
@@ -94,6 +137,19 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
 
+After the bot joins, give it at least a Moderator power level (50) in the management room.
+
+> [!WARNING]
+> Draupnir stores each protection's settings as custom state events in the management room, and sending those requires a power level of 50 by default. A bot without this power level cannot save any protection settings. The failure is easy to miss and has nasty consequences: the `PolicyChangeNotification` protection, unable to remember its notifications room, will create a brand new one on every restart of the bot (and the playbook restarts it on every installation run), littering your server with abandoned rooms.
+
+This is not a concern for Zero Touch Deployment, where the bot creates the management room itself and has full control over it.
+
+### Creating a user account for the bot (when using Zero Touch Deployment)
+
+Since Zero Touch Deployment is not validated with native login, you will need to create the user account manually.
+
+Refer to [registering users](registering-users.md) for documentation on how to configure the user account.
+
 ### Make sure the account is free from rate limiting (optional, recommended)
 
 If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a highly recommended step. If you do not configure it, Draupnir performance will be degraded.**
@@ -102,11 +158,11 @@ This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synap
 
 **Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
 
-The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
+The APIs can also be accessed via [Ketesa](https://github.com/etkecc/ketesa), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Ketesa for you. For details about it, see [this page](configuring-playbook-ketesa.md).
 
 #### Add the configuration
 
-To expose the APIs publicly, add the following configuration to your `vars.yml` file:
+This is automatically done if Ketesa is enabled. Otherwise, to expose the APIs publicly, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
@@ -132,6 +188,7 @@ curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://ma
 ```
 
 **Notes**:
+
 - This does not work on outdated Windows 10 as curl is not available there.
 - Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally.
 
@@ -157,13 +214,14 @@ matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled: true
 matrix_bot_draupnir_admin_api_enabled: true
 ```
 
-These protections need to be manually activated and consulting the [enabling protections](#enabling-built-in-protections) guide can be helpful or consulting upstream documentation.
+These protections need to be manually activated. Consulting the [enabling protections](#enabling-built-in-protections) guide and/or upstream documentation can be helpful.
 
-<!--
-NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
+The other method polls a Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin. To enable it, set `pollReports: true` in your `vars.yml` file as below:
 
-The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
--->
+```yaml
+matrix_bot_draupnir_configuration_extension_yaml: |
+  pollReports: true
+```
 
 ### Extending the configuration
 
@@ -212,7 +270,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
   `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_draupnir_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_draupnir_password` to let the bot know its new password.
+- If you change the bot password (`matrix_bot_draupnir_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 [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_draupnir_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-go-neb.md

@@ -1,267 +1,26 @@
 <!--
-SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019-2025 Slavi Pantaleev
 SPDX-FileCopyrightText: 2021 Yannick Goossens
 SPDX-FileCopyrightText: 2022 Dennis Ciba
-SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
-SPDX-FileCopyrightText: 2025 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2023-2025 MDAD project contributors
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Setting up Go-NEB (optional, unmaintained)
+# Setting up Go-NEB (optional, removed)
 
-**Note**: [Go-NEB](https://github.com/matrix-org/go-neb) is now an archived (**unmaintained**) project. We recommend not bothering with installing it. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be [installed using this playbook](configuring-playbook-bridge-hookshot.md). Consider using that bot instead of this one.
+🪦 The playbook used to be able to install and configure [Go-NEB](https://github.com/matrix-org/go-neb), but no longer includes this component as it has been discontinued.
 
-The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
+While not a 1:1 replacement, the bot's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be [installed using this playbook](configuring-playbook-bridge-hookshot.md).
 
-Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
+## Uninstalling Go-NEB manually
 
-See the project's [documentation](https://github.com/matrix-org/go-neb/blob/master/README.md) to learn what it does and why it might be useful to you.
-
-## Prerequisites
-
-### Register the bot account
-
-The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
-
-Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
-
-You can use the playbook to [register a new user](registering-users.md):
+If you still have the Go-NEB component installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server:
 
 ```sh
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+systemctl disable --now matrix-bot-go-neb.service
+
+rm -rf /matrix/go-neb
 ```
-
-### Obtain an access token
-
-The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
-
-> [!WARNING]
-> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
-
-## Adjusting DNS records
-
-By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to create a CNAME record for `goneb`, which targets `matrix.example.com`.
-
-When setting, replace `example.com` with your own.
-
-## Adjusting the playbook configuration
-
-To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_GONEB_HERE` and `ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE` with the ones created [above](#obtain-an-access-token).
-
-```yaml
-matrix_bot_go_neb_enabled: true
-
-# You need at least 1 client.
-# Use the access token you obtained in the step above.
-matrix_bot_go_neb_clients:
-  - UserID: "@goneb:{{ matrix_domain }}"
-    AccessToken: "ACCESS_TOKEN_FOR_GONEB_HERE"
-    DeviceID: "DEVICE1"
-    HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
-    Sync: true
-    AutoJoinRooms: true
-    DisplayName: "Go-NEB!"
-    AcceptVerificationFromUsers: [":{{ matrix_domain }}"]
-
-  - UserID: "@another_goneb:{{ matrix_domain }}"
-    AccessToken: "ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE"
-    DeviceID: "DEVICE2"
-    HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
-    Sync: false
-    AutoJoinRooms: false
-    DisplayName: "Go-NEB!"
-    AcceptVerificationFromUsers: ["^@admin:{{ matrix_domain }}"]
-
-# Optional, for use with the github_cmd, github_webhooks or jira services
-matrix_bot_go_neb_realms:
-  - ID: "github_realm"
-    Type: "github"
-    Config: {} # No need for client ID or Secret as Go-NEB isn't generating OAuth URLs
-
-# Optional. The list of *authenticated* sessions which Go-NEB is aware of.
-matrix_bot_go_neb_sessions:
-  - SessionID: "your_github_session"
-    RealmID: "github_realm"
-    UserID: "@alice:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
-    Config:
-      # Populate these fields by generating a "Personal Access Token" on github.com
-      AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
-      Scopes: "admin:org_hook,admin:repo_hook,repo,user"
-
-# The list of services which Go-NEB is aware of.
-# Delete or modify this list as appropriate.
-# See the docs for /configureService for the full list of options:
-# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
-# You need at least 1 service.
-matrix_bot_go_neb_services:
-  - ID: "echo_service"
-    Type: "echo"
-    UserID: "@goneb:{{ matrix_domain }}"
-    Config: {}
-
-# Can be obtained from https://developers.giphy.com/dashboard/
-  - ID: "giphy_service"
-    Type: "giphy"
-    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
-    Config:
-      api_key: "qwg4672vsuyfsfe"
-      use_downsized: false
-
-# This service has been dead for over a year :/
-  - ID: "guggy_service"
-    Type: "guggy"
-    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
-    Config:
-      api_key: "2356saaqfhgfe"
-
-# API Key via https://developers.google.com/custom-search/v1/introduction
-# CX via http://www.google.com/cse/manage/all
-# https://stackoverflow.com/questions/6562125/getting-a-cx-id-for-custom-search-google-api-python
-# 'Search the entire web' and 'Image search' enabled for best results
-  - ID: "google_service"
-    Type: "google"
-    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
-    Config:
-      api_key: "AIzaSyA4FD39m9"
-      cx: "AIASDFWSRRtrtr"
-
-# Obtain a key via https://api.imgur.com/oauth2/addclient
-# Select "oauth2 without callback url"
-  - ID: "imgur_service"
-    Type: "imgur"
-    UserID: "@imgur:{{ matrix_domain }}" # requires a Syncing client
-    Config:
-      client_id: "AIzaSyA4FD39m9"
-      client_secret: "somesecret"
-
-  - ID: "wikipedia_service"
-    Type: "wikipedia"
-    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
-    Config:
-
-  - ID: "rss_service"
-    Type: "rssbot"
-    UserID: "@another_goneb:{{ matrix_domain }}"
-    Config:
-      feeds:
-        "http://lorem-rss.herokuapp.com/feed?unit=second&interval=60":
-          rooms: ["!qporfwt:{{ matrix_domain }}"]
-          must_include:
-            author:
-              - author1
-            description:
-              - lorem
-              - ipsum
-          must_not_include:
-            title:
-              - Lorem
-              - Ipsum
-
-  - ID: "github_cmd_service"
-    Type: "github"
-    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
-    Config:
-      RealmID: "github_realm"
-
-    # Make sure your BASE_URL can be accessed by Github!
-  - ID: "github_webhook_service"
-    Type: "github-webhook"
-    UserID: "@another_goneb:{{ matrix_domain }}"
-    Config:
-      RealmID: "github_realm"
-      ClientUserID: "@alice:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
-      Rooms:
-        "!qporfwt:example.com":
-          Repos:
-            "element-hq/synapse":
-              Events: ["push", "issues"]
-            "matrix-org/dendron":
-              Events: ["pull_request"]
-        "!aaabaa:example.com":
-          Repos:
-            "element-hq/synapse":
-              Events: ["push", "issues"]
-            "matrix-org/dendron":
-              Events: ["pull_request"]
-
-  - ID: "slackapi_service"
-    Type: "slackapi"
-    UserID: "@slackapi:{{ matrix_domain }}"
-    Config:
-      Hooks:
-        "hook1":
-          RoomID: "!qporfwt:example.com"
-          MessageType: "m.text" # default is m.text
-
-  - ID: "alertmanager_service"
-    Type: "alertmanager"
-    UserID: "@alertmanager:{{ matrix_domain }}"
-    Config:
-      # This is for information purposes only. It should point to Go-NEB path as follows:
-      # `/services/hooks/<base64 encoded service ID>`
-      # Where in this case "service ID" is "alertmanager_service"
-      # Make sure your BASE_URL can be accessed by the Alertmanager instance!
-      webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
-      # Each room will get the notification with the alert rendered with the given template
-      rooms:
-        "!qporfwt:example.com":
-          text_template: "{% raw %}{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}{% endraw %}"
-          html_template: "{% raw %}{{range .Alerts -}}  {{ $severity := index .Labels \"severity\" }}    {{ if eq .Status \"firing\" }}      {{ if eq $severity \"critical\"}}        <font color='red'><b>[FIRING - CRITICAL]</b></font>      {{ else if eq $severity \"warning\"}}        <font color='orange'><b>[FIRING - WARNING]</b></font>      {{ else }}        <b>[FIRING - {{ $severity }}]</b>      {{ end }}    {{ else }}      <font color='green'><b>[RESOLVED]</b></font>    {{ end }}  {{ index .Labels \"alertname\"}} : {{ index .Annotations \"description\"}}   <a href=\"{{ .GeneratorURL }}\">source</a><br/>{{end -}}{% endraw %}"
-          msg_type: "m.text"  # Must be either `m.text` or `m.notice`
-```
-
-### Adjusting the Go-NEB URL (optional)
-
-By tweaking the `matrix_bot_go_neb_hostname` and `matrix_bot_go_neb_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
-
-Example additional configuration for your `vars.yml` file:
-
-```yaml
-# Switch to the domain used for Matrix services (`matrix.example.com`),
-# so we won't need to add additional DNS records for Go-NEB.
-matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
-
-# Expose under the /go-neb subpath
-matrix_bot_go_neb_path_prefix: /go-neb
-```
-
-After changing the domain, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
-
-If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
-
-### Extending the configuration
-
-There are some additional things you may wish to configure about the bot.
-
-Take a look at:
-
-- `roles/custom/matrix-bot-go-neb/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bot-go-neb/templates/config.yaml.j2` for the bot's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_go_neb_configuration_extension_yaml` variable
-
-## Installing
-
-After configuring the playbook and potentially [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.
-
-## Usage
-
-To use the bot, invite it to any existing Matrix room (`/invite @bot.go-neb:example.com` where `example.com` is your base domain, not the `matrix.` domain). Make sure you are granted with the sufficient permission if you are not the room owner.
-
-Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
-
-If you enabled the github_cmd service, send `!github help` to the bot in the room to see the available commands.
-
-You can also refer to the upstream [Documentation](https://github.com/matrix-org/go-neb).
-
-## 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-bot-go-neb`.

docs/configuring-playbook-bot-honoroit.md

@@ -78,7 +78,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
   `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_honoroit_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_honoroit_password` to let the bot know its new password.
+- If you change the bot password (`matrix_bot_honoroit_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 [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-matrix-registration-bot.md

@@ -1,103 +1,34 @@
 <!--
-SPDX-FileCopyrightText: 2022 - 2023 Julian-Samuel Gebühr
-SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Edgars Voroboks
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2019-2025 MDAD project contributors
+SPDX-FileCopyrightText: 2019-2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Chris van Dijk
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2020 jens quade
 SPDX-FileCopyrightText: 2022 Dennis Ciba
 SPDX-FileCopyrightText: 2022 Erick Wibben
+SPDX-FileCopyrightText: 2022 Kim Brose
 SPDX-FileCopyrightText: 2022 Kolja Lampe
-SPDX-FileCopyrightText: 2023 - 2024 MDAD project contributors
-SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2022 Travis Ralston
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2022 Yan Minagawa
+SPDX-FileCopyrightText: 2022, 2023 Julian-Samuel Gebühr
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Setting up matrix-registration-bot (optional)
+# Setting up matrix-registration-bot (optional, removed)
 
-The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
+🪦 The playbook used to be able to install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot), but no longer includes this component, as it has been unmaintained.
 
-The bot allows you to easily **create and manage registration tokens** aka. invitation codes. It can be used for an invitation-based server, where you invite someone by sending them a registration token (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process.
+## Uninstalling the component manually
 
-See the project's [documentation](https://github.com/moan0s/matrix-registration-bot/blob/master/README.md) to learn what it does and why it might be useful to you.
-
-## Adjusting the playbook configuration
-
-To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_bot_matrix_registration_bot_enabled: true
-
-# By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:example.com`.
-# Uncomment and adjust this part if you'd like to use a username different than the default
-# matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot
-
-# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
-matrix_bot_matrix_registration_bot_bot_password: PASSWORD_FOR_THE_BOT
-
-# Enables registration
-matrix_synapse_enable_registration: true
-
-# Restrict registration to users with a token
-matrix_synapse_registration_requires_token: true
-
-# Set an optional command prefix for the bot. This can be any arbitrary string, including whitespace.
-# Example: "!regbot "
-matrix_bot_matrix_registration_bot_bot_prefix: ""
-```
-
-The bot account will be created automatically.
-
-### Extending the configuration
-
-There are some additional things you may wish to configure about the bot.
-
-Take a look at:
-
-- `roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bot-matrix-registration-bot/templates/config.yaml.j2` for the bridge's default configuration
-
-## Installing
-
-After configuring the playbook, run it 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,ensure-matrix-users-created,start
-```
-
-**Notes**:
-
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
-
-- 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_matrix_registration_bot_bot_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_matrix_registration_bot_bot_password` to let the bot know its new password.
-
-## Usage
-
-To use the bot, start a chat with `@bot.matrix-registration-bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-Send `help` to the bot to see the available commands.
-
-You can also refer to the upstream [Usage documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands).
-
-If you have any questions, or if you need help setting it up, read the [troubleshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md) or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
-
-To clean the cache (session & encryption data) after you changed the bot's username, changed the login method from access_token to password etc… you can use:
+If you still have matrix-registration-bot installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server:
 
 ```sh
-just run-tags bot-matrix-registration-bot-clean-cache
-```
+systemctl disable --now matrix-bot-matrix-registration-bot.service
 
-## 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-bot-matrix-registration-bot`.
-
-### Increase logging verbosity
-
-The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
-
-```yaml
-# Valid values: ERROR, INFO, DEBUG
-matrix_bot_matrix_registration_bot_logging_level: DEBUG
+rm -rf /matrix/matrix-registration-bot
 ```

docs/configuring-playbook-bot-matrix-reminder-bot.md

@@ -57,7 +57,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
   `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_matrix_reminder_bot_matrix_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_matrix_reminder_bot_matrix_user_password` to let the bot know its new password.
+- If you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_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 [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-maubot.md

@@ -103,7 +103,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
   `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_maubot_initial_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_maubot_initial_password` to let the bot know its new password.
+- If you change the bot password (`matrix_bot_maubot_initial_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 [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-meowlnir.md

@@ -0,0 +1,409 @@
+<!--
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Meowlnir (optional)
+
+The playbook can install and configure the [Meowlnir](https://github.com/maunium/meowlnir) moderation bot for you.
+
+See the project's [documentation](https://docs.mau.fi/meowlnir/) to learn what it does and why it might be useful to you.
+
+Meowlnir is an alternative to [Draupnir](configuring-playbook-bot-draupnir.md) and [Mjolnir](configuring-playbook-bot-mjolnir.md). It speaks the same [policy list](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists) protocol, so it can subscribe to the same community ban lists, but it differs from them in a few ways that may matter to you:
+
+- It runs as an **appservice** and hosts **multiple bots**, each with its own management room. They live in Meowlnir's database, not its configuration file, but you still [declare them in your `vars.yml` file](#declaring-bots).
+- It can **override a policy coming from a list you do not control**, via unban policies combined with the ordering of your watched lists. See [Overriding a policy from someone else's list](#overriding-a-policy-from-someone-elses-list).
+- It is written in Go and is optimized for Synapse, using its database and admin APIs directly.
+
+Meowlnir and Draupnir can run side by side, but not usefully in the *same* room: whichever bot you are migrating away from still watches the same community lists, so it re-applies the very bans your unban policies remove. Migrate room by room. See [Trialling Meowlnir alongside another bot](#trialling-meowlnir-alongside-another-bot).
+
+## Prerequisites
+
+### Postgres
+
+Meowlnir stores its state in a Postgres database. The playbook creates one for you automatically when using the integrated Postgres server.
+
+### Adjusting DNS records
+
+**No DNS changes are necessary.** Meowlnir is reached by the homeserver over the container network, and the paths it optionally serves publicly (abuse reports and the policy server) are routed on your existing `matrix.example.com` domain.
+
+## Adjusting the playbook configuration
+
+To enable Meowlnir, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bot_meowlnir_enabled: true
+```
+
+### Declaring bots
+
+That gets the service running, but Meowlnir does nothing until it has at least one bot. Declare the ones you want and the playbook creates them for you:
+
+```yaml
+matrix_bot_meowlnir_bots_custom:
+  - username: meowlnir_bot
+    displayname: Meowlnir
+    avatar_url: ""
+    management_room_auto_create: true
+    management_rooms: []
+    # Left out, the initial managers default to `matrix_bot_meowlnir_initial_managers`,
+    # which is defined in terms of `matrix_admin`.
+    # Uncomment to override that for this bot, or if neither variable is set.
+    # initial_managers:
+    #   - "@alice:example.com"
+    #   - "@bob:example.com"
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `username` | yes | The localpart of the bot's Matrix user. Awkward to change later, so choose it carefully. |
+| `displayname` | yes | The name shown in rooms. Safe to change at any time. |
+| `avatar_url` | yes | An `mxc://` URI, or `""` for no avatar. |
+| `management_room_auto_create` | yes | Whether the playbook creates the bot's management room. Mutually exclusive with a non-empty `management_rooms`. |
+| `management_rooms` | yes | Rooms you have created yourself, `[]` when auto-creating. See [Supplying your own management room](#supplying-your-own-management-room). |
+| `initial_managers` | no | Who to invite to an auto-created room. Defaults to the instance-wide list below. |
+
+Usernames have to start with `meowlnir_` (the value of `matrix_bot_meowlnir_user_prefix`), so that bots fall inside the user namespace the homeserver lets Meowlnir operate.
+
+Changing `displayname` or `avatar_url` and re-running updates the bot in place. The comparison is against Meowlnir's own record, so profile edits made directly from a Matrix client are not reverted.
+
+#### Initial managers
+
+With `management_room_auto_create: true`, the playbook creates each bot's management room and invites its initial managers to it. You only need to accept the room invitation.
+
+`matrix_admin` is a single playbook variable which affects all bridges and bots, so setting it is usually a better move than setting anything specific to this role — **if it is already configured in your `vars.yml` file, there is nothing to do here**. If neither `matrix_admin` nor `matrix_bot_meowlnir_initial_managers` are set, the playbook would tell you about it.
+
+A per-bot `initial_managers` replaces the instance-wide list. Declaring it empty means nobody, which fails the run for a bot relying on `management_room_auto_create`.
+
+The list is consulted only while the room is being created. Adding a name to it later invites nobody, because the room already exists — invite and promote further moderators from inside the room instead, as described in [Who can command a bot](#who-can-command-a-bot).
+
+#### Rooms the playbook creates
+
+The bot creates the room with the `trusted_private_chat` preset, which gives every invitee the standing to command it. This is an additional room creator on room versions supporting [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289) (like v12) and power level 100 on older room versions. Creator status cannot be revoked subsequently.
+
+The room's encryption follows `matrix_bot_meowlnir_config_encryption_enable`, and its name and topic come from `matrix_bot_meowlnir_management_room_name` and `matrix_bot_meowlnir_management_room_topic`.
+
+### Supplying your own management room
+
+If you would rather own the room outright, create it yourself and declare it instead. The bot is then merely an administrator in a room you created:
+
+```yaml
+matrix_bot_meowlnir_bots_custom:
+  - username: meowlnir_bot
+    displayname: Meowlnir
+    avatar_url: ""
+    management_room_auto_create: false
+    management_rooms:
+      - id: "!qporfwt:example.com"
+        encrypted: false
+```
+
+An empty, invite-only room is fine. The order matters, because **each step depends on the one before it**:
+
+1. Declare the room and run the playbook. Do not invite the bot beforehand.
+2. The playbook creates the bot and tells Meowlnir about the room. Meowlnir would try to join right away, but will fail for invite-only rooms (a harmless error in the log).
+3. Invite the bot. It accepts the invitation, because the room is already marked as a management room for it.
+4. Give it power level 50 or more (ideally 100), so that it can store its protected rooms and watched lists there.
+
+Meowlnir supports several management rooms per bot, and `encrypted` is set per room. Marking a room encrypted only means something when [End-to-End Encryption support](#end-to-end-encryption-support) is switched on, which it is not by default.
+
+### Several management rooms for one bot
+
+Protected rooms, watched policy lists, protection settings and who may command the bot are properties of **a management room**, not of the bot. A room can be protected from exactly one management room, so moving a room means `!rooms unprotect` in the old room and `!rooms protect` in the new one, with its settings and subscriptions set up again there.
+
+That is how you hand one room to another moderator without giving them power over everything else the bot moderates: a second management room, the room moved into it, and power level 50 for them there. That last part is revocable, unlike the creator status everyone invited at creation time receives.
+
+Splitting rooms up this way does not split two other things:
+
+- The variables which name a single management room (`matrix_bot_meowlnir_synapse_http_antispam_management_room_id`, `matrix_bot_meowlnir_config_meowlnir_report_room`, `matrix_bot_meowlnir_config_meowlnir_room_ban_room`) keep pointing at the room you named there.
+- A policy list can be written to from any management room watching it, and its policies apply in every room those management rooms protect. Give a delegated management room a list of its own with `!lists create`.
+
+Create the room with `meowlnir-create-management-room` (see [Inspecting and driving Meowlnir directly](#inspecting-and-driving-meowlnir-directly)), then add its ID to `management_rooms` and re-run the playbook, which is what registers it with Meowlnir.
+
+#### Switching a bot from an auto-created room to declared ones
+
+Auto-creation makes exactly one room, and since it is not declared anywhere, [pruning](#bots-which-are-no-longer-declared) leaves such a bot's rooms alone. Declaring a second room means taking over the declaration of all of them: list what Meowlnir knows about with `/matrix/meowlnir/bin/meowlnir-bots`, set `management_room_auto_create: false`, put **every** one of those rooms under `management_rooms`, and re-run the playbook.
+
+> [!WARNING]
+> A room left out of that list is unregistered on the next run. Nothing is destroyed, but the bot stops taking commands there and stops protecting the rooms attached to it, until you declare the room again.
+
+### Who can command a bot
+
+**Management room membership alone is not enough**, which is different from what [Draupnir](configuring-playbook-bot-draupnir.md) does, where everyone in the management room can issue commands.
+
+Meowlnir decides who may drive a bot from power levels in its management room: anyone who can send the `fi.mau.meowlnir.watched_lists` state event (power level 50 by default), plus the room's creators.
+
+### Bots which are no longer declared
+
+The bot list (`matrix_bot_meowlnir_bots_custom`) is authoritative. Removing entries from there will make the playbook unregister them with the Meowlnir instance.
+
+Removal only adjusts Meowlnir's own records. A removed bot's Matrix user remains activated and stays in the rooms it had joined. A removed management room leaves the room and the bot's membership in it intact - it's just that Meowlnir stops taking commands there.
+
+Removal happens under the same `ensure-matrix-users-created` tag that creates bots. It's one Ansible tag for "synchronizing the bots state" (creation, changes, and removal).
+
+To turn removal off entirely, set `matrix_bot_meowlnir_bots_pruning_enabled: false`. As a safety measure, the playbook refuses to prune when *no* bots are declared at all; override that with `matrix_bot_meowlnir_bots_pruning_on_empty_roster_enabled: true`.
+
+### Trialling Meowlnir alongside another bot
+
+Meowlnir has a dry-run mode in which it does everything except take moderation actions:
+
+```yaml
+matrix_bot_meowlnir_config_meowlnir_dry_run: true
+```
+
+> [!WARNING]
+> Dry run does not cover the [synapse-http-antispam](#enabling-synapse-http-antispam-support) integration. It suppresses actions Meowlnir takes itself (bans, server ACLs, rejecting pending invites), but the verdicts it hands back to Synapse still block invites and joins. Leave that integration off while trialling.
+
+Do not expect dry run to preview what Meowlnir would do in rooms another policy-list bot already moderates. Meowlnir only acts on users who are *in* a room, and the other bot has already removed everyone its lists match, so the preview comes out empty. Dry run also skips the power level check described under [Protecting a room](#protecting-a-room), so it will not surface a permissions problem either.
+
+### Abuse reports
+
+Meowlnir can intercept the report endpoints of the client-server API, so that abuse reports are delivered to a management room. This requires integration with the reverse proxy in front of the homeserver, which the playbook sets up for you when using Traefik:
+
+```yaml
+matrix_bot_meowlnir_config_reporting_enabled: true
+
+# The management room that receives the reports.
+matrix_bot_meowlnir_config_meowlnir_report_room: "!qporfwt:example.com"
+```
+
+Only the `v3` report endpoints are routed to Meowlnir. Requests to the legacy `r0` endpoints continue to reach the homeserver, because Meowlnir does not serve them.
+
+### Enabling synapse-http-antispam support
+
+Meowlnir can block invites and joins before they happen. This requires the [synapse-http-antispam](https://github.com/maunium/synapse-http-antispam) module, which the playbook can enable for you:
+
+```yaml
+matrix_bot_meowlnir_synapse_http_antispam_enabled: true
+
+# The management room whose policies the module consults.
+matrix_bot_meowlnir_synapse_http_antispam_management_room_id: "!qporfwt:example.com"
+```
+
+> [!WARNING]
+> The playbook wires the module up to a single consumer, so this cannot be enabled at the same time as `matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled`. The playbook fails the run if both are enabled.
+
+With the module in place, you can also block invitations to specific users outright, which is useful for accounts that attract spam:
+
+```yaml
+matrix_bot_meowlnir_config_antispam_block_invites_to_custom:
+  - "@alice:example.com"
+```
+
+Such an invitation can still be let through case by case with the `!allow-invite` command.
+
+### End-to-End Encryption support
+
+To let Meowlnir's bots participate in encrypted rooms:
+
+```yaml
+matrix_bot_meowlnir_config_encryption_enable: true
+```
+
+When using Synapse, the playbook turns on the experimental features this depends on (`msc2409_to_device_messages_enabled` and `msc3202_transaction_extensions`) for you.
+
+### Policy server (MSC4284)
+
+Meowlnir can act as a [policy server](https://github.com/matrix-org/matrix-spec-proposals/pull/4284), letting rooms ask it to vet events before they are accepted:
+
+```yaml
+matrix_bot_meowlnir_policy_server_enabled: true
+```
+
+This exposes `/_matrix/policy` on your Matrix federation endpoint, so that other servers participating in a room can reach it.
+
+That only stands the policy server up, though — no room is put behind it until you say so from the management room:
+
+```
+!policyserver enable !qporfwt:example.com
+```
+
+Given no room, `enable` applies to every protected room. Rooms which are not protected are skipped, with `Skipped ... as it is not a protected room`, so [protect a room](#protecting-a-room) before enabling it here. `!policyserver` on its own reports whether the policy server is available and prints its public key, and `!policyserver disable` reverses the change.
+
+The playbook derives a stable signing key for you from `matrix_homeserver_generic_secret_key`. If you would rather use an independently generated one, produce it with the command below and set it as `matrix_bot_meowlnir_config_policy_server_signing_key`:
+
+```sh
+python3 -c "import os, base64; print('ed25519 policy_server ' + base64.b64encode(os.urandom(32)).decode().rstrip('='))"
+```
+
+### Synapse admin API access (optional)
+
+A few of Meowlnir's features go through Synapse's admin API, not the client-server API — suspending or deactivating users, and deleting rooms during a takedown. Those calls require the caller to be a Synapse **server admin**, which bots are not by default, so they come back as `M_FORBIDDEN` ("You are not a server admin"). Nothing else is affected: bans, server ACLs, protecting rooms and watching policy lists all go through the client-server API, where a sufficient power level is the only requirement.
+
+To grant that access, point each bot at a token belonging to a server admin:
+
+```yaml
+matrix_bot_meowlnir_config_meowlnir_admin_tokens:
+  "@meowlnir_bot:example.com": "ADMIN_TOKEN_HERE"
+```
+
+The key is the bot the token is used for; the token itself belongs to an administrator account, not to the bot.
+
+If you have more than one management room, note that room bans are only processed in the one named by `matrix_bot_meowlnir_config_meowlnir_room_ban_room`, and ignored elsewhere.
+
+Where the token comes from depends on how your homeserver authenticates. Ordinarily you [obtain an access token](obtaining-access-tokens.md) for an account which is a Synapse server admin. When [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) is enabled, Synapse no longer decides who is an admin, so the token has to be issued by MAS with admin privileges:
+
+```sh
+/matrix/matrix-authentication-service/bin/mas-cli manage issue-compatibility-token --yes-i-want-to-grant-synapse-admin-privileges alice
+```
+
+Note that bot users are created by the appservice and are not known to Matrix Authentication Service, so the token cannot be issued for the bot itself — use an administrator account.
+
+### Access to the Synapse database (optional)
+
+Some room takedown features rely on Meowlnir reading room IDs directly from the Synapse database. Upstream expects a user with read-only permissions, which the playbook does not create. Enabling the integration below hands Meowlnir the same credentials Synapse itself uses, which also grant write access:
+
+```yaml
+matrix_bot_meowlnir_synapse_database_integration_enabled: true
+```
+
+If you would rather not do that, create a read-only Postgres user yourself and point Meowlnir at it with `matrix_bot_meowlnir_synapse_database_uri`.
+
+### Adopting an existing Meowlnir installation
+
+If you already run Meowlnir outside the playbook and want to bring it under this role, two things need attention before the first run.
+
+Your bots exist in Meowlnir's database but not in your `vars.yml` file, and [pruning](#bots-which-are-no-longer-declared) is on by default, so the first run would remove them. Declare them in `matrix_bot_meowlnir_bots_custom` — with `management_room_auto_create: false` and their existing rooms under `management_rooms` — or set `matrix_bot_meowlnir_bots_pruning_enabled: false`.
+
+If the installation uses encryption, also copy the `pickle_key` from its old configuration file into `matrix_bot_meowlnir_config_encryption_pickle_key`. The crypto store cannot be read with a different key than it was written with, so leaving the playbook's default in place costs your bots their existing encryption sessions.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-meowlnir/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_meowlnir_configuration_extension_yaml` variable
+
+> [!WARNING]
+> Do not set any of Meowlnir's secrets to the literal value `generate`. Meowlnir re-runs its configuration upgrader on every start, so a `generate` placeholder would produce a brand new secret on every restart. The playbook derives stable values for you, and fails the run if it finds a `generate` placeholder.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+With `management_room_auto_create`, you then have an invitation waiting for you — accept it and start sending commands. If you supplied the management room yourself, carry on from step 3 of [Supplying your own management room](#supplying-your-own-management-room): invite the bot, then give it power level 50 or more.
+
+**Notes**:
+
+- The `ensure-matrix-users-created` tag is what creates the bots declared in `matrix_bot_meowlnir_bots_custom`, registers their management rooms, and removes the ones you no longer declare. It deliberately does not run as part of `setup-all`, so that installing onto a server whose database you are about to restore from a backup does not write anything.
+
+- Re-running is safe and idempotent, so adding a bot later is a matter of extending the list and running the same command again.
+
+- If the homeserver turns out to be running without Meowlnir's appservice registration (which is the normal state of affairs on the run that first enables Meowlnir), the playbook restarts the homeserver during bot provisioning, so that everything completes in a single run.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+## Usage
+
+You can refer to the upstream [documentation](https://docs.mau.fi/meowlnir/) for a more detailed usage guide.
+
+Below is a **non-exhaustive quick-start guide** for the impatient.
+
+### Inspecting and driving Meowlnir directly
+
+The playbook drives Meowlnir's management API for you based on `matrix_bot_meowlnir_bots_custom`, which is the recommended way. For anything it does not cover, helper scripts are installed under `/matrix/meowlnir/bin`, which find the management secret and reach the API inside the container:
+
+```sh
+# Show the bots, their management rooms, protected rooms and watched policy lists
+/matrix/meowlnir/bin/meowlnir-bots
+
+# Call any endpoint: meowlnir-api <METHOD> <PATH> [JSON body]
+/matrix/meowlnir/bin/meowlnir-api GET /_meowlnir/v1/bots
+
+# Create another management room for an existing bot, with the given users able to command it there
+/matrix/meowlnir/bin/meowlnir-create-management-room meowlnir_bot @alice:example.com
+
+# Ask the homeserver who Meowlnir's appservice token belongs to.
+# A 401 response means the homeserver is running without Meowlnir's appservice registration, which is also what Meowlnir's own "Failed to connect to homeserver" log messages usually mean.
+/matrix/meowlnir/bin/meowlnir-whoami
+```
+
+`meowlnir-create-management-room` prints the new room's ID, which you then register with `meowlnir-api PUT /_meowlnir/v1/management_room/<room ID>`.
+
+See the upstream [bot creation documentation](https://docs.mau.fi/meowlnir/bot-create.html) for the full set of endpoints. Bear in mind that bots you create this way are not declared in your `vars.yml` file, so the next playbook run will remove them again (see [Bots which are no longer declared](#bots-which-are-no-longer-declared)).
+
+If you have enabled encryption, each bot also needs verifying once. That step is left manual because it returns a recovery key you need to store somewhere safe:
+
+```sh
+/matrix/meowlnir/bin/meowlnir-api POST /_meowlnir/v1/bot/meowlnir_bot/verify '{"generate": true}'
+```
+
+### Protecting a room
+
+Invite the bot to a room, give it a power level high enough to act (see below), and then tell it to protect the room by sending this command to its management room:
+
+```
+!rooms protect !qporfwt:example.com
+```
+
+If the bot has more than one management room, send this to the one that should own the room: a room can only be protected from a single management room. See [Several management rooms for one bot](#several-management-rooms-for-one-bot).
+
+Meowlnir refuses to protect a room unless its power level reaches that room's own `ban` and `redact` levels (50 in a default room). That is only enough for user bans, though: writing `m.room.server_acl` usually requires 100, and without it the server rules in your watched lists have no effect — which is most of what a list like [CME](https://matrix.to/#/%23community-moderation-effort-bl:neko.dev) carries. **Give the bot power level 100** unless you only care about user bans.
+
+Set the power level *before* protecting the room. Meowlnir re-sends server ACLs when it starts and when a watched list changes, but not when its own power level goes up subsequently, so raising it afterwards leaves the room without ACLs until you restart the bot (`systemctl restart matrix-bot-meowlnir` or via the playbook's Ansible `start` tag).
+
+### Subscribing to a policy list
+
+Policy lists are maintained in Matrix rooms. Popular public ones are:
+
+- `#community-moderation-effort-bl:neko.dev`
+- `#huginn-muninn-active-threats:feline.support`
+
+Subscribe to one by sending the following command to the management room:
+
+```
+!lists subscribe #community-moderation-effort-bl:neko.dev cme
+```
+
+The last argument is a shortcode, which you use to refer to the list in later commands.
+
+### Overriding a policy from someone else's list
+
+This is the main capability Meowlnir has that Draupnir does not.
+
+When several watched lists carry a policy for the same user, **the first match wins**, and "first" means the order in which the lists are watched. So to be able to override a community list's ban, your own list has to come before it.
+
+`!lists subscribe` appends, which makes subscription order the precedence order. Subscribe to your own list first, and to community lists afterwards:
+
+```
+!lists create my-ban-exceptions
+!lists subscribe #community-moderation-effort-bl:neko.dev cme
+```
+
+> [!NOTE]
+> To subscribe somewhere other than the end of the list, pass `--insert-before <shortcode>`.
+
+You can then publish an unban policy into your own list, which takes precedence over the community list's ban:
+
+```
+!add-unban my-bans @alice:example.com false-positive
+```
+
+> [!NOTE]
+> Unlike `!ban`, the `!add-unban` command does not treat its reason as a trailing argument, so a reason containing spaces is discarded. Use a single word (or hyphenate) until that is fixed upstream.
+
+> [!IMPORTANT]
+> An unban policy stops a ban from being **re-applied**; it does not undo one that is already in place unless Meowlnir applied it itself and still has it on record. A ban placed by a human moderator, or by the Draupnir or Mjolnir you are migrating away from, stays. Unban such a user once by hand — from then on the policy keeps them unbanned, while you remain subscribed to the list that banned them.
+
+Use `!match @alice:example.com` to see which policies currently apply to a user and which list each came from.
+
+> [!NOTE]
+> Unban policies use a Meowlnir-specific recommendation (`fi.mau.meowlnir.unban`) which is not part of the Matrix specification. If you publish your policy list for other people to subscribe to, subscribers running Draupnir or Mjolnir will ignore your unban policies.
+
+There is also a blunter, server-wide escape hatch for policies that are too wide to tolerate at all — `matrix_bot_meowlnir_config_meowlnir_hacky_rule_filter_custom`, which makes Meowlnir ignore any policy matching the listed entities.
+
+## 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 running a command like `journalctl -fu matrix-bot-meowlnir`.
+
+If bots appear to do nothing, check that they have an Administrator power level in the rooms they are meant to protect, and that the room has been added with `!rooms protect`.
+
+If commands in a management room get no reply at all, check the bot's power level *there* too — it needs at least 50 to record its own configuration.
+
+A bare `!lists` returns nothing in a management room which has never had a policy list. That is an upstream bug and it clears as soon as you subscribe to one; `!lists subscribe` works from the start.

docs/configuring-playbook-bot-mjolnir.md

@@ -15,6 +15,8 @@ The playbook can install and configure the [Mjolnir](https://github.com/matrix-o
 
 See the project's [documentation](https://github.com/matrix-org/mjolnir/blob/main/README.md) to learn what it does and why it might be useful to you.
 
+**Note**: you can also use the [Draupnir](configuring-playbook-bot-draupnir.md) or [Meowlnir](configuring-playbook-bot-meowlnir.md) bots, which speak the same [policy list](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists) protocol.
+
 ## Prerequisites
 
 ### Register the bot account
@@ -46,7 +48,7 @@ This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synap
 
 **Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
 
-The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
+The APIs can also be accessed via [Ketesa](https://github.com/etkecc/ketesa), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Ketesa for you. For details about it, see [this page](configuring-playbook-ketesa.md).
 
 #### Add the configuration
 
@@ -198,7 +200,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
   `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 Pantalaimon's password (`matrix_bot_mjolnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_mjolnir_pantalaimon_password` to let Pantalaimon know its new password.
+- If you change the Pantalaimon's password (`matrix_bot_mjolnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_mjolnir_pantalaimon_password` to let Pantalaimon know its new password.
 
 ## Usage
 

docs/configuring-playbook-bridge-appservice-discord.md

@@ -26,9 +26,9 @@ Create a Discord Application [here](https://discordapp.com/developers/applicatio
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_appservice_discord_enabled: true
-matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
-matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
+matrix_bridge_appservice_discord_enabled: true
+matrix_bridge_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
+matrix_bridge_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
 
 # As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
 # Note: This deprecated method is considered insecure.
@@ -44,7 +44,7 @@ There are some additional things you may wish to configure about the bridge.
 Take a look at:
 
 - `roles/custom/matrix-bridge-appservice-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_discord_configuration_extension_yaml` variable
+- `roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bridge_appservice_discord_configuration_extension_yaml` variable
 
 ## Installing
 
@@ -65,7 +65,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. To enable it, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_appservice_discord_bridge_enableSelfServiceBridging: true
+matrix_bridge_appservice_discord_bridge_enableSelfServiceBridging: true
 ```
 
 **Note**: If self-service bridging is not enabled, `!discord help` commands will return no results.
@@ -91,14 +91,14 @@ All Matrix rooms created this way are **listed publicly** by default, and you wi
 To disable portal bridging, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_appservice_discord_bridge_disablePortalBridging: true
+matrix_bridge_appservice_discord_bridge_disablePortalBridging: true
 ```
 
 ### Usage
 
 To get started with Portal Bridging:
 
-1. To invite the bot to Discord, retrieve the invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
+1. To invite the bot to Discord, retrieve the invite link from the `{{ matrix_bridge_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
 2. Room addresses follow this syntax: `#_discord_<guildID>_<channelID>`. You can easily find the guild and channel IDs by logging into Discord in a browser and opening the desired channel. The URL will have this format: `discord.com/channels/<guildID>/<channelID>`.
 3. Once you have figured out the appropriate room address, you can join by doing `/join #_discord_<guildID>_<channelID>` in your Matrix client.
 
@@ -124,7 +124,7 @@ As with all other services, you can find the logs in [systemd-journald](https://
 The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file (adapt to your needs) and re-run the playbook:
 
 ```yaml
-matrix_appservice_discord_configuration_extension_yaml: |
+matrix_bridge_appservice_discord_configuration_extension_yaml: |
   logging:
     # What level should the logger output to the console at.
     console: "info" # Valid values: silent, error, warn, http, info, verbose, silly

docs/configuring-playbook-bridge-appservice-irc.md

@@ -20,9 +20,9 @@ See the project's [documentation](https://github.com/matrix-org/matrix-appservic
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_appservice_irc_enabled: true
+matrix_bridge_appservice_irc_enabled: true
 
-matrix_appservice_irc_ircService_servers:
+matrix_bridge_appservice_irc_ircService_servers:
   irc.example.com:
     name: "ExampleNet"
     port: 6697
@@ -76,7 +76,7 @@ There are some additional things you may wish to configure about the bridge.
 Take a look at:
 
 - `roles/custom/matrix-bridge-appservice-irc/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_irc_configuration_extension_yaml` variable
+- `roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bridge_appservice_irc_configuration_extension_yaml` variable
 
 ## Installing
 
@@ -104,7 +104,7 @@ As with all other services, you can find the logs in [systemd-journald](https://
 The default logging level for this component is `debug`, and the log is output to the console only. If you want to change the verbosity or enable logging to a file, add the following configuration to your `vars.yml` file (adapt to your needs) and re-run the playbook:
 
 ```yaml
-matrix_appservice_irc_configuration_extension_yaml: |
+matrix_bridge_appservice_irc_configuration_extension_yaml: |
   logging:
     # Level to log on console/logfile.
     # Valid values: error, warn, info, debug

docs/configuring-playbook-bridge-appservice-kakaotalk.md

@@ -1,75 +1,26 @@
 <!--
 SPDX-FileCopyrightText: 2022 Dennis Ciba
-SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 - 2026 Slavi Pantaleev
 SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 MDAD project contributors
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Setting up Appservice Kakaotalk bridging (optional)
+# Setting up Appservice Kakaotalk bridging (optional, removed)
 
-The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you, for bridging to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG). This bridge is based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
+🪦 The playbook used to be able to install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) (a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG)), but no longer includes this component.
 
-See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk/src/branch/master/README.md) to learn what it does and why it might be useful to you.
+The bridge could only be installed by self-building its source code, and its upstream repository has become unreachable, which makes installation impossible. The bridge was also based on the now-unmaintained [node-kakao](https://github.com/storycraft/node-kakao) library, and there have been reports that using it may get your Kakaotalk account banned.
 
-> [!WARNING]
-> There have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
+## Uninstalling the component manually
 
-## Prerequisite (optional)
+If you still have matrix-appservice-kakaotalk installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server:
 
-### Enable Shared Secret Auth
-
-If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
-
-See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
-
-**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
-
-## Adjusting the playbook configuration
-
-To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_appservice_kakaotalk_enabled: true
-```
-
-### Extending the configuration
-
-There are some additional things you may wish to configure about the bridge.
-
-Take a look at:
-
-- `roles/custom/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-appservice-kakaotalk/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_kakaotalk_configuration_extension_yaml` variable
-
-## Installing
-
-After configuring the playbook, run it 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
-```
+systemctl disable --now matrix-appservice-kakaotalk.service
 
-The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+systemctl disable --now matrix-appservice-kakaotalk-node.service
 
-`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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-You then need to send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
-
-## 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-appservice-kakaotalk`.
-
-### Increase logging verbosity
-
-The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
-
-```yaml
-matrix_appservice_kakaotalk_logging_level: DEBUG
+rm -rf /matrix/appservice-kakaotalk
 ```

docs/configuring-playbook-bridge-beeper-line.md

@@ -0,0 +1,101 @@
+<!--
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Beeper LINE bridging (optional)
+
+<sup>Refer to the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
+The playbook can install and configure [beeper-line](https://github.com/beeper/line) for you, for bridging to [LINE](https://line.me/).
+
+See the project's [documentation](https://github.com/beeper/line/blob/main/README.md) to learn what it does and which features it supports.
+
+## Prerequisites
+
+### Prepare your LINE account
+
+The bridge logs in with the email address configured in your LINE account. If your account does not have an email address, set one in the LINE mobile app under **Settings** → **Account** → **Email address** before trying to log in.
+
+The bridge identifies itself to LINE as a Chrome Extension client. LINE only permits one active Chrome Extension session, so the bridge and the real LINE Chrome Extension cannot be used at the same time. Logging in with either one invalidates the other session.
+
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the common mautrix bridge guide for details.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bridge_beeper_line_enabled: true
+```
+
+### Using another container image
+
+Upstream does not publish container images publicly, as its CI only pushes them to Beeper's private registry. The playbook therefore uses [`docker.io/crispyduck/beeper-line`](https://hub.docker.com/r/crispyduck/beeper-line) by default, which is a community-maintained image built from the upstream source.
+
+That image is only available for the amd64 architecture. On other architectures, the playbook self-builds the image from source automatically.
+
+To use an image that you have built and published elsewhere, override the complete image name:
+
+```yaml
+matrix_bridge_beeper_line_container_image_self_build: false
+matrix_bridge_beeper_line_container_image: docker.io/example/beeper-line:latest
+```
+
+The role can also build the bridge directly from a Git repository on the Matrix server:
+
+```yaml
+matrix_bridge_beeper_line_container_image_self_build: true
+matrix_bridge_beeper_line_container_image_self_build_repo: https://github.com/beeper/line.git
+matrix_bridge_beeper_line_container_image_self_build_branch: main
+```
+
+Self-building requires more time and resources on the server than pulling a prebuilt image.
+
+### Extending the configuration
+
+There are additional things you may wish to configure about the bridge.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the common mautrix bridge guide for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), and the [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional).
+
+When following the common guide, replace `_mautrix_SERVICENAME_` in variable names with `_beeper_line_`.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+```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 when its components remain unchanged. If you adjust your `vars.yml` to remove other components, run `just setup-all` so those components are uninstalled.
+
+## Usage
+
+To use the bridge, start a chat with `@linebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+Send `login` and enter your LINE email address and password when prompted. The bridge then shows you a PIN code, which you need to enter into the LINE app on your mobile device to approve the new session.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in systemd-journald by logging in to the server with SSH and running:
+
+```sh
+journalctl -fu matrix-beeper-line
+```
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. To increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_bridge_beeper_line_logging_level: debug
+```

docs/configuring-playbook-bridge-beeper-linkedin.md

@@ -8,7 +8,9 @@ SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Setting up Beeper Linkedin bridging (optional)
+# Setting up Beeper Linkedin bridging (optional, unmaintained)
+
+**Note**: this bridge is unmaintained. Its [upstream repository](https://github.com/beeper/linkedin) has been archived and has not seen a change since March 2025. For bridging to LinkedIn, consider using the [mautrix-linkedin](configuring-playbook-bridge-mautrix-linkedin.md) bridge instead, which is actively maintained and also supported by the playbook.
 
 The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the mautrix bridges.
 
@@ -29,7 +31,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_beeper_linkedin_enabled: true
+matrix_bridge_beeper_linkedin_enabled: true
 ```
 
 ### Extending the configuration
@@ -68,7 +70,7 @@ As with all other services, you can find the logs in [systemd-journald](https://
 The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
 ```yaml
-matrix_beeper_linkedin_logging_level: DEBUG
+matrix_bridge_beeper_linkedin_logging_level: DEBUG
 ```
 
 ### Bridge asking for 2FA even if you don't have 2FA enabled

docs/configuring-playbook-bridge-heisenbridge.md

@@ -25,26 +25,26 @@ If you wish to adjust it, see the section [below](#adjusting-the-heisenbridge-ur
 To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_heisenbridge_enabled: true
+matrix_bridge_heisenbridge_enabled: true
 
 # Setting the owner is optional as the first local user to DM `@heisenbridge:example.com` will be made the owner.
 # If you are not using a local user you must set it as otherwise you can't DM it at all.
-matrix_heisenbridge_owner: "@alice:{{ matrix_domain }}"
+matrix_bridge_heisenbridge_owner: "@alice:{{ matrix_domain }}"
 
 # Uncomment to enable identd on host port 113/TCP (optional)
-# matrix_heisenbridge_identd_enabled: true
+# matrix_bridge_heisenbridge_identd_enabled: true
 ```
 
 ### Adjusting the Heisenbridge URL (optional)
 
-By tweaking the `matrix_heisenbridge_hostname` and `matrix_heisenbridge_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+By tweaking the `matrix_bridge_heisenbridge_hostname` and `matrix_bridge_heisenbridge_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
 
 Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Change the default hostname and path prefix
-matrix_heisenbridge_hostname: heisenbridge.example.com
-matrix_heisenbridge_path_prefix: /
+matrix_bridge_heisenbridge_hostname: heisenbridge.example.com
+matrix_bridge_heisenbridge_path_prefix: /
 ```
 
 If you've changed the default hostname, you may need to create a CNAME record for the Heisenbridge domain (`heisenbridge.example.com`), which targets `matrix.example.com`.

docs/configuring-playbook-bridge-hookshot.md

@@ -29,20 +29,23 @@ You need to download the private key file, if you will install the file manually
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `GITHUB_PRIVATE_KEY_HERE` with the one created [above](#download-github-app-private-key).
 
 ```yaml
-matrix_hookshot_enabled: true
+matrix_bridge_hookshot_enabled: true
 
 # Uncomment to enable end-to-bridge encryption.
 # See: https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html
-# matrix_hookshot_encryption_enabled: true
+# matrix_bridge_hookshot_encryption_enabled: true
 
 # Uncomment and paste the contents of GitHub app private key to enable GitHub bridge.
 # Alternatively, you can use one of the other methods explained below on the "Manage GitHub Private Key with aux role" section.
-# matrix_hookshot_github_private_key: "GITHUB_PRIVATE_KEY_HERE"
+# matrix_bridge_hookshot_github_private_key: "GITHUB_PRIVATE_KEY_HERE"
 ```
 
-For each of the services (GitHub, GitLab, Jira, Figma, and generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
+> [!NOTE]
+> End-to-bridge encryption requires the homeserver to support (and have enabled) [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409) and [MSC3202](https://github.com/matrix-org/matrix-spec-proposals/pull/3202). When using Synapse, the playbook turns on the experimental features this depends on (`msc2409_to_device_messages_enabled` and `msc3202_transaction_extensions`) for you. On other homeserver implementations, you need to arrange for this yourself.
 
-Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab and generic webhooks), while you must first add the required configuration and enable the others (GitHub, Jira, and Figma).
+For each of the services (GitHub, GitLab, Jira, Figma, and generic webhooks) fill in the respective variables `matrix_bridge_hookshot_service_*` listed in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
+
+Take special note of the `matrix_bridge_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab and generic webhooks), while you must first add the required configuration and enable the others (GitHub, Jira, and Figma).
 
 ### Extending the configuration
 
@@ -51,7 +54,7 @@ There are some additional things you may wish to configure about the bridge.
 Take a look at:
 
 - `roles/custom/matrix-bridge-hookshot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-hookshot/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables
+- `roles/custom/matrix-bridge-hookshot/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bridge_hookshot_configuration_extension_yaml` and `matrix_bridge_hookshot_registration_extension_yaml` variables
 
 Refer the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) and the comments in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) to learn what the individual options do.
 
@@ -96,31 +99,31 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
 
 | Listener | Default path | Variable | Used as |
 |---|---|---|---|
-| - | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
-| generic | `/hookshot/webhooks/webhook` | `matrix_hookshot_generic_endpoint` | Generic webhooks |
-| github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
-| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | Jira OAuth |
-| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
-| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
-| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
+| - | `/hookshot/webhooks/` | `matrix_bridge_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
+| generic | `/hookshot/webhooks/webhook` | `matrix_bridge_hookshot_generic_endpoint` | Generic webhooks |
+| github oauth | `/hookshot/webhooks/oauth` | `matrix_bridge_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
+| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_bridge_hookshot_jira_oauth_endpoint` | Jira OAuth |
+| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_bridge_hookshot_figma_endpoint` | Figma |
+| appservice | `/hookshot/_matrix/app/` | `matrix_bridge_hookshot_appservice_endpoint` | Matrix server |
+| widgets | `/hookshot/widgetapi/` | `matrix_bridge_hookshot_widgets_endpoint` | Widgets |
 
-Also see the various `matrix_hookshot_container_labels_*` variables in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly.
+Also see the various `matrix_bridge_hookshot_container_labels_*` variables in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly.
 
-The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
+The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_bridge_hookshot_container_url`) and on different ports (e.g. `matrix_bridge_hookshot_appservice_port`). Read [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
 
 ### Manage GitHub Private Key with aux role
 
 The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
 
-- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml)).
-- somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
+- copy the *contents* of the downloaded file and set the variable `matrix_bridge_hookshot_github_private_key` to the contents (see example in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml)).
+- somehow copy the file to the path `{{ matrix_bridge_hookshot_base_path }}/{{ matrix_bridge_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
 - use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
 
-To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following configuration to your `vars.yml` file:
+To use the `aux` role, make sure the `matrix_bridge_hookshot_github_private_key` variable is empty. Then add the following configuration to your `vars.yml` file:
 
 ```yaml
 aux_file_definitions:
-  - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
+  - dest: "{{ matrix_bridge_hookshot_base_path }}/{{ matrix_bridge_hookshot_github_private_key_file }}"
     content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
     mode: '0400'
     owner: "{{ matrix_user_name }}"
@@ -139,23 +142,23 @@ To enable the metrics, add the following configuration to your `vars.yml` file:
 
 ```yaml
 # Expose metrics (locally, on the container network).
-matrix_hookshot_metrics_enabled: true
+matrix_bridge_hookshot_metrics_enabled: true
 ```
 
 **To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.example.com/metrics/hookshot` by adding the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_hookshot_metrics_proxying_enabled: true
+matrix_bridge_hookshot_metrics_proxying_enabled: true
 ```
 
 By default metrics are exposed publicly **without** password-protection. To password-protect the metrics with dedicated credentials, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
-matrix_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
+matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
+matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
 ```
 
-To `matrix_hookshot_container_labels_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
+To `matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
 
 **Note**: alternatively, you can use `matrix_metrics_exposure_enabled` to expose all services on this `/metrics/*` feature, and you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` to password-protect the metrics of them. See [this section](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) for more information.
 
@@ -175,5 +178,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: error, warn, info, debug
-matrix_hookshot_logging_level: debug
+matrix_bridge_hookshot_logging_level: debug
 ```

docs/configuring-playbook-bridge-matrix-bridge-sms.md

@@ -21,23 +21,23 @@ The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/androi
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_sms_bridge_enabled: true
+matrix_bridge_sms_enabled: true
 
 # (optional but recommended) a room ID to a default room
-matrix_sms_bridge_default_room: ""
+matrix_bridge_sms_default_room: ""
 
 # (optional but recommended) configure your server location
-matrix_sms_bridge_default_region: DE
-matrix_sms_bridge_default_timezone: Europe/Berlin
+matrix_bridge_sms_default_region: DE
+matrix_bridge_sms_default_timezone: Europe/Berlin
 
 # Settings to connect to android-sms-gateway-server
-matrix_sms_bridge_provider_android_baseurl: https://192.168.24.24:9090
-matrix_sms_bridge_provider_android_username: admin
-matrix_sms_bridge_provider_android_password: supeSecretPassword
+matrix_bridge_sms_provider_android_baseurl: https://192.168.24.24:9090
+matrix_bridge_sms_provider_android_username: admin
+matrix_bridge_sms_provider_android_password: supeSecretPassword
 
 # (optional) if your android-sms-gateway-server uses a self signed vertificate, the bridge needs a "truststore". This can be the certificate itself.
-matrix_sms_bridge_provider_android_truststore_local_path: android-sms-gateway-server.p12
-matrix_sms_bridge_provider_android_truststore_password: 123
+matrix_bridge_sms_provider_android_truststore_local_path: android-sms-gateway-server.p12
+matrix_bridge_sms_provider_android_truststore_password: 123
 ```
 
 ### Extending the configuration
@@ -46,7 +46,7 @@ There are some additional things you may wish to configure about the bridge.
 
 Take a look at:
 
-- `roles/custom/matrix-bridge-sms/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_sms_bridge_configuration_extension_yaml` variable
+- `roles/custom/matrix-bridge-sms/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bridge_sms_configuration_extension_yaml` variable
 
 ## Installing
 

docs/configuring-playbook-bridge-mautrix-bluesky.md

@@ -27,7 +27,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_bluesky_enabled: true
+matrix_bridge_mautrix_bluesky_enabled: true
 ```
 
 ### Extending the configuration
@@ -70,5 +70,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug, trace
-matrix_mautrix_bluesky_logging_level: 'debug'
+matrix_bridge_mautrix_bluesky_logging_level: 'debug'
 ```

docs/configuring-playbook-bridge-mautrix-bridges.md

@@ -21,12 +21,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 
 ```yaml
 # Replace SERVICENAME with one of: twitter, discord, signal, googlechat, etc.
-matrix_mautrix_SERVICENAME_enabled: true
+matrix_bridge_mautrix_SERVICENAME_enabled: true
 ```
 
-**Note**: for bridging to Meta's Messenger or Instagram, you would need to add `meta` with an underscore symbol (`_`) or hyphen (`-`) based on the context as prefix to each `SERVICENAME`; add `_` to variables (as in `matrix_mautrix_meta_messenger_configuration_extension_yaml` for example) and `-` to paths of the configuration files (as in `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2`), respectively.
+**Note**: for bridging to Meta's Messenger or Instagram, you would need to add `meta` with an underscore symbol (`_`) or hyphen (`-`) based on the context as prefix to each `SERVICENAME`; add `_` to variables (as in `matrix_bridge_mautrix_meta_messenger_configuration_extension_yaml` for example) and `-` to paths of the configuration files (as in `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2`), respectively.
 
-There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges.
+There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_bridge_mautrix_telegram_api_id` and `matrix_bridge_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges.
 
 ### Configure bridge permissions (optional)
 
@@ -43,7 +43,7 @@ If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin
 **Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
 
 ```yaml
-matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
+matrix_bridge_mautrix_SERVICENAME_configuration_extension_yaml: |
   bridge:
     permissions:
       '@alice:{{ matrix_domain }}': admin
@@ -67,8 +67,8 @@ matrix_bridges_encryption_default: true
 **Alternatively**, for a specific bridge:
 
 ```yaml
-matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
-matrix_mautrix_SERVICENAME_bridge_encryption_default: true
+matrix_bridge_mautrix_SERVICENAME_bridge_encryption_enabled: true
+matrix_bridge_mautrix_SERVICENAME_bridge_encryption_default: true
 ```
 
 ### Enable relay mode (optional)
@@ -86,16 +86,16 @@ matrix_bridges_relay_enabled: true
 **Alternatively**, for a specific bridge:
 
 ```yaml
-matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
+matrix_bridge_mautrix_SERVICENAME_configuration_extension_yaml: |
   bridge:
     relay:
       enabled: true
 ```
 
-You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
+You can only have one `matrix_bridge_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
 
 ```yaml
-matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
+matrix_bridge_mautrix_SERVICENAME_configuration_extension_yaml: |
   bridge:
     relay:
       enabled: true
@@ -115,7 +115,7 @@ Use `!prefix set-pl 100` to be able for the bot to modify room settings and invi
 By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_mautrix_SERVICENAME_bridge_relay_admin_only: false
+matrix_bridge_mautrix_SERVICENAME_bridge_relay_admin_only: false
 ```
 
 ### Set the bot's username (optional)
@@ -123,7 +123,7 @@ matrix_mautrix_SERVICENAME_bridge_relay_admin_only: false
 To set the bot's username, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
+matrix_bridge_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
 ```
 
 ### Configure the logging level (optional)
@@ -131,13 +131,42 @@ matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
 To specify the logging level, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_mautrix_SERVICENAME_logging_level: warn
+matrix_bridge_mautrix_SERVICENAME_logging_level: warn
 ```
 
 Replace `warn` with one of the following to control the verbosity of the logs generated: `trace`, `debug`, `info`, `warn`, `error` or `fatal`.
 
 If you have issues with a service, and are requesting support, the higher levels of logging (those that appear earlier in the list, like `trace`) will generally be more helpful.
 
+### Expose the bridge's API (for Mautrix Manager and similar tools)
+
+Each mautrix bridge runs an HTTP API which tools like [Mautrix Manager](https://github.com/mautrix/manager) can use to help you log into the bridge. This is especially handy for bridges where logging in manually is cumbersome (like [mautrix-gmessages](configuring-playbook-bridge-mautrix-gmessages.md)).
+
+By default, the playbook exposes this API publicly at `https://matrix.example.com/bridges/SERVICENAME` (for example, `https://matrix.example.com/bridges/gmessages`). Such tools authenticate to the bridge with your own Matrix access token, so you never need to share any bridge secret with them.
+
+To make discovery easier, the playbook also serves a `/.well-known/matrix/mautrix` file which advertises all your exposed bridges. Mautrix Manager reads this file and offers your bridges automatically, so you don't need to enter their URLs by hand.
+
+This is all enabled by default. To **disable exposing the API for all bridges**, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_bridges_exposure_enabled: false
+```
+
+**Alternatively**, to disable it for a specific bridge:
+
+```yaml
+matrix_bridge_mautrix_SERVICENAME_exposure_enabled: false
+```
+
+If you run additional bridges on the same server which are not managed by this playbook and would like compatible tools to discover them as well, you can advertise their base URLs in the `/.well-known/matrix/mautrix` file:
+
+```yaml
+matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges_custom:
+  - https://matrix.example.com/bridges/SOME_OTHER_BRIDGE
+```
+
+Only list bridges hosted on (and connected to) this server here, as compatible tools will send your Matrix access token to them. For bridges on other servers, take a look at the `fi.mau.external_bridge_servers` property described in the [Mautrix Manager](https://github.com/mautrix/manager) documentation, which you can add via `matrix_static_files_file_matrix_mautrix_configuration_extension_json`.
+
 ### Extending the configuration
 
 There are some additional things you may wish to configure about the bridge.
@@ -145,7 +174,7 @@ There are some additional things you may wish to configure about the bridge.
 Take a look at:
 
 - `roles/custom/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_SERVICENAME_configuration_extension_yaml` variable
+- `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bridge_mautrix_SERVICENAME_configuration_extension_yaml` variable
 
 ## Installing
 
@@ -197,7 +226,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 - Previously there were multiple different automatic double puppeting methods like one with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but they have been superseded by this Appservice Double Puppet method. Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future as the older methods were completely removed in the megabridge rewrites on [the upstream project](https://docs.mau.fi/bridges/general/double-puppeting.html#automatically).
 
 <!-- TODO: remove this note if the Shared Secret Auth service has stopped working or the bridges have been removed -->
-- Some bridges like [the deprecated Facebook mautrix bridge](configuring-playbook-bridge-mautrix-facebook.md) and [matrix-appservice-kakaotalk](configuring-playbook-bridge-appservice-kakaotalk.md), which is partially based on the Facebook bridge, are compatible with the Shared Secret Auth service only. These bridges automatically perform Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+- Some bridges like [the deprecated Facebook mautrix bridge](configuring-playbook-bridge-mautrix-facebook.md) are compatible with the Shared Secret Auth service only. These bridges automatically perform Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
 
 #### Method 2: manually, by asking each user to provide a working access token
 

docs/configuring-playbook-bridge-mautrix-discord.md

@@ -39,7 +39,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_discord_enabled: true
+matrix_bridge_mautrix_discord_enabled: true
 ```
 
 ### Extending the configuration
@@ -96,7 +96,7 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug, trace
-matrix_mautrix_discord_logging_level: 'debug'
+matrix_bridge_mautrix_discord_logging_level: 'debug'
 ```
 
 ### Command requires room admin rights when user is creator

docs/configuring-playbook-bridge-mautrix-gmessages.md

@@ -27,7 +27,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_gmessages_enabled: true
+matrix_bridge_mautrix_gmessages_enabled: true
 ```
 
 ### Extending the configuration
@@ -68,5 +68,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug, trace
-matrix_mautrix_gmessages_logging_level: 'debug'
+matrix_bridge_mautrix_gmessages_logging_level: 'debug'
 ```

docs/configuring-playbook-bridge-mautrix-googlechat.md

@@ -30,7 +30,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the [Google Chat](https://chat.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_googlechat_enabled: true
+matrix_bridge_mautrix_googlechat_enabled: true
 ```
 
 ### Extending the configuration
@@ -70,5 +70,5 @@ As with all other services, you can find the logs in [systemd-journald](https://
 The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
 ```yaml
-matrix_mautrix_googlechat_logging_level: DEBUG
+matrix_bridge_mautrix_googlechat_logging_level: DEBUG
 ```

docs/configuring-playbook-bridge-mautrix-gvoice.md

@@ -0,0 +1,73 @@
+<!--
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+SPDX-FileCopyrightText: 2026 Nikita Chernyi
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Mautrix Google Voice bridging (optional)
+
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
+The playbook can install and configure [mautrix-gvoice](https://github.com/mautrix/gvoice) for you, for bridging to [Google Voice](https://voice.google.com/).
+
+See the project's [documentation](https://docs.mau.fi/bridges/go/gvoice/index.html) to learn what it does and why it might be useful to you.
+
+## Prerequisite (optional)
+
+### Enable Appservice Double Puppet
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bridge_mautrix_gvoice_enabled: true
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+<!-- NOTE: relay mode is not supported for this bridge -->
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it 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.
+
+## Usage
+
+To use the bridge, start a chat with `@gvoicebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+Google Voice has no phone to pair and no QR code to scan. It logs in with cookies, which you copy from a browser already signed in to [voice.google.com](https://voice.google.com/) and hand to the bot. It is fiddlier than scanning a code and feels more suspicious than it is, but Google leaves no cleaner door open. The bridge's [official Authentication guide](https://docs.mau.fi/bridges/go/gvoice/authentication.html) has the exact cookies to grab and the steps for grabbing them.
+
+Those cookies are a login session, and Google expires them on its own schedule. When they lapse the bridge goes quiet and you log in again. Nothing is broken, that is just how cookie auth ages.
+
+Once you log in, the bridge builds portal rooms for your recent conversations and carries text and media both ways. Don't reach for it to start a brand-new chat or to place a call, though. That ground still belongs to Google Voice, so keep the app around for those.
+
+## 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-mautrix-gvoice`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_bridge_mautrix_gvoice_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-linkedin.md

@@ -0,0 +1,112 @@
+<!--
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+SPDX-FileCopyrightText: 2026 Nikita Chernyi
+SPDX-FileCopyrightText: 2026 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Mautrix LinkedIn bridging (optional)
+
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
+The playbook can install and configure [mautrix-linkedin](https://github.com/mautrix/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) messaging.
+
+See the project's [documentation](https://docs.mau.fi/bridges/go/linkedin/index.html) to learn what it does and why it might be useful to you.
+
+>[!NOTE]
+> LinkedIn keeps its messaging function behind a login wall and does not provide a usable public API, so using this bridge requires you to manually copy cookies on a web browser for logging in. Refer to [this section](#usage) below for details.
+
+## Prerequisite
+
+### Uninstalling `beeper-linkedin`
+
+If `beeper-linkedin` bridge is enabled on your host, you need to uninstall it first, since it claims the `@linkedinbot` username and `@linkedin_*` user range as exclusive appservice namespaces, which will cause conflicts with `mautrix-linkedin`.
+
+To uninstall the bridge, set `matrix_bridge_beeper_linkedin_enabled: false` and re-run the playbook. The playbook refuses to install `mautrix-linkedin` until `beeper-linkedin` is uninstalled.
+
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bridge_mautrix_linkedin_enabled: true
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+<!-- NOTE: relay mode is not supported for this bridge -->
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it 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.
+
+## Usage
+
+Start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, the bare one without the `matrix.` prefix) and send `login`.
+
+### Logging in
+
+To log in, you need to sign in to LinkedIn with a web browser and hand one of the requests it makes to the bot. Because the bridge presents itself as Chrome on Linux, the request needs to come from **Chrome or a Chrome-based browser**.
+
+>[!WARNING]
+> LinkedIn ties the session to the browser that made the request and rejects it when it is replayed under a different user-agent. A request copied from Firefox therefore results in a session that stops working immediately, without an error message.
+
+You need to follow these steps to log in:
+
+1. Open [linkedin.com](https://www.linkedin.com/) in a private/incognito window on Chrome / a Chrome-based browser
+2. Sign in to LinkedIn
+3. Open your browser's devtools (F12) and go to the Network tab
+4. Filter for `graphql`
+5. Right-click any one of those requests, then "Copy" and "Copy as cURL"
+6. Paste the output into the chat with the bot and send it
+
+The bridge's [official Authentication guide](https://docs.mau.fi/bridges/go/linkedin/authentication.html) walks the same steps with screenshots.
+
+Once you log in, the bridge builds portal rooms for your recent conversations and carries messages both ways.
+
+**💡 Notes:**
+
+- The request contains a login session, which LinkedIn may expire at any time. When the bridge goes quiet, log in again by following the steps above.
+- If you would rather not retrieve the request yourself, you may wish to take a look at [mautrix-manager](https://github.com/mautrix/manager).
+
+## Troubleshooting
+
+### The bot does not respond after you send it the cURL output
+
+This most likely means that you have obtained the request with a browser other than Chrome or a Chrome-based one. LinkedIn silently discards a session replayed under a different user-agent. Follow the login steps above again, this time using Chrome or a Chrome-based browser.
+
+### The bridge worked before, but has gone quiet
+
+Your LinkedIn session has most likely expired. Send `login` to the bot and follow the login steps above again.
+
+### Other issues
+
+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-mautrix-linkedin`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_bridge_mautrix_linkedin_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-meta-instagram.md

@@ -13,7 +13,7 @@ The playbook can install and configure the [mautrix-meta](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you.
 
-Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
+The mautrix-meta project provides bridging to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/), each via a separate bridge (its own binary and container image) since mautrix-meta v26.07. The playbook makes them available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`), which can both be enabled at the same time.
 
 This documentation page only deals with the bridge's ability to bridge to Instagram. For bridging to Facebook/Messenger, see [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md).
 
@@ -23,7 +23,7 @@ This documentation page only deals with the bridge's ability to bridge to Instag
 
 If you've been using the [mautrix-instagram](./configuring-playbook-bridge-mautrix-instagram.md) bridge, **you'd better get rid of it first** or the 2 bridges will be in conflict:
 
-- both trying to use `@instagrambot:example.com` as their username. This conflict may be resolved by adjusting `matrix_mautrix_instagram_appservice_bot_username` or `matrix_mautrix_meta_instagram_appservice_username`
+- both trying to use `@instagrambot:example.com` as their username. This conflict may be resolved by adjusting `matrix_mautrix_instagram_appservice_bot_username` or `matrix_bridge_mautrix_meta_instagram_appservice_username`
 - both trying to bridge the same DMs
 
 To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@instagrambot:example.com`). It gives you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
@@ -41,7 +41,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_meta_instagram_enabled: true
+matrix_bridge_mautrix_meta_instagram_enabled: true
 ```
 
 Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
@@ -83,5 +83,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
-matrix_mautrix_meta_instagram_logging_min_level: debug
+matrix_bridge_mautrix_meta_instagram_logging_min_level: debug
 ```

docs/configuring-playbook-bridge-mautrix-meta-messenger.md

@@ -14,7 +14,7 @@ The playbook can install and configure the [mautrix-meta](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you.
 
-Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
+The mautrix-meta project provides bridging to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/), each via a separate bridge (its own binary and container image) since mautrix-meta v26.07. The playbook makes them available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`), which can both be enabled at the same time.
 
 This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md).
 
@@ -41,7 +41,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_meta_messenger_enabled: true
+matrix_bridge_mautrix_meta_messenger_enabled: true
 ```
 
 Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
@@ -56,7 +56,7 @@ The bridge can pull your Messenger messages via 3 different methods:
 - (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) — does not currently proxy media downloads
 - (default) (`messenger`) Messenger via `messenger.com` — usable even without a Facebook account
 
-You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variable. The playbook defaults to the `messenger` mode, because it's most universal (every Facebook user has a Messenger account, but the opposite is not true).
+You may switch the mode via the `matrix_bridge_mautrix_meta_messenger_meta_mode` variable. The playbook defaults to the `messenger` mode, because it's most universal (every Facebook user has a Messenger account, but the opposite is not true).
 
 Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.).
 
@@ -99,5 +99,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
-matrix_mautrix_meta_messenger_logging_min_level: debug
+matrix_bridge_mautrix_meta_messenger_logging_min_level: debug
 ```

docs/configuring-playbook-bridge-mautrix-signal.md

@@ -28,7 +28,7 @@ See the project's [documentation](https://docs.mau.fi/bridges/go/signal/index.ht
 
 If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing.
 
-However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
+However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_bridge_mautrix_signal_database_*`).
 
 ### Enable Appservice Double Puppet
 
@@ -41,7 +41,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_signal_enabled: true
+matrix_bridge_mautrix_signal_enabled: true
 ```
 
 ### Extending the configuration
@@ -83,5 +83,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug, trace
-matrix_mautrix_signal_logging_level: 'debug'
+matrix_bridge_mautrix_signal_logging_level: 'debug'
 ```

docs/configuring-playbook-bridge-mautrix-slack.md

@@ -34,7 +34,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_slack_enabled: true
+matrix_bridge_mautrix_slack_enabled: true
 ```
 
 ### Extending the configuration
@@ -74,5 +74,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug, trace
-matrix_mautrix_slack_logging_level: 'debug'
+matrix_bridge_mautrix_slack_logging_level: 'debug'
 ```

docs/configuring-playbook-bridge-mautrix-telegram.md

@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 - 2026 Slavi Pantaleev
 SPDX-FileCopyrightText: 2018 Hugues Morisset
 SPDX-FileCopyrightText: 2019 - 2022 MDAD project contributors
 SPDX-FileCopyrightText: 2021 Panagiotis Georgiadis
@@ -17,7 +17,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 The playbook can install and configure [mautrix-telegram](https://github.com/mautrix/telegram) for you.
 
-See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/index.html) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://docs.mau.fi/bridges/go/telegram/index.html) to learn what it does and why it might be useful to you.
 
 ## Prerequisites
 
@@ -25,61 +25,34 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/in
 
 To use the bridge, you'd need to obtain an API key from [https://my.telegram.org/apps](https://my.telegram.org/apps).
 
-### Enable Appservice Double Puppet or Shared Secret Auth (optional)
+### Enable Appservice Double Puppet (optional)
 
-If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
 
 See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
 
-**Notes**:
-
-- Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
-
-- If you decided to enable Double Puppeting manually, send `login-matrix` to the bot in order to receive an instruction about how to send an access token to it.
-
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `YOUR_TELEGRAM_APP_ID` and `YOUR_TELEGRAM_API_HASH`.
 
 ```yaml
-matrix_mautrix_telegram_enabled: true
-matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
-matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
+matrix_bridge_mautrix_telegram_enabled: true
+matrix_bridge_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
+matrix_bridge_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
 ```
 
 ### Relaying
 
-### Enable relay-bot (optional)
-
-If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `vars.yml` file:
-
-```yaml
-matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
-matrix_mautrix_telegram_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '*': relaybot
-```
+This bridge supports the common [mautrix bridge relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional). Once enabled, any authenticated user can be turned into a relaybot for a chat by sending `!tg set-relay` in that chat.
 
 ### Configure a user as an administrator of the bridge (optional)
 
 You might also want to give permissions to a user to administrate the bot. See [this section](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional) on the common guide for details about it.
 
-More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
-
-### Use the bridge for direct chats only (optional)
-
-If you want to exclude all groups from syncing and use the Telegram-Bridge only for direct chats, add the following configuration to your `vars.yml` file:
-
-```yaml
-matrix_mautrix_telegram_filter_mode: whitelist
-```
-
 ### Extending the configuration
 
 There are some additional things you may wish to configure about the bridge.
 
-<!-- NOTE: common relay mode is not supported for this bridge -->
 See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
 
 ## Installing
@@ -99,9 +72,9 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 
 To use the bridge, you need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/telegram/authentication.html).
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/telegram/authentication.html).
 
-After logging in, the bridge will create portal rooms for all of your Telegram groups and invite you to them. Note that the bridge won't automatically create rooms for private chats.
+After logging in, the bridge will create portal rooms for all of your Telegram groups and invite you to them.
 
 ## Troubleshooting
 
@@ -109,8 +82,9 @@ As with all other services, you can find the logs in [systemd-journald](https://
 
 ### Increase logging verbosity
 
-The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
 ```yaml
-matrix_mautrix_telegram_logging_level: DEBUG
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_bridge_mautrix_telegram_logging_level: debug
 ```

docs/configuring-playbook-bridge-mautrix-twitter.md

@@ -28,7 +28,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_twitter_enabled: true
+matrix_bridge_mautrix_twitter_enabled: true
 ```
 
 ### Extending the configuration
@@ -69,5 +69,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug, trace
-matrix_mautrix_twitter_logging_level: 'debug'
+matrix_bridge_mautrix_twitter_logging_level: 'debug'
 ```

docs/configuring-playbook-bridge-mautrix-whatsapp.md

@@ -34,7 +34,7 @@ See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_whatsapp_enabled: true
+matrix_bridge_mautrix_whatsapp_enabled: true
 ```
 
 ### Extending the configuration
@@ -76,5 +76,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug, trace
-matrix_mautrix_whatsapp_logging_level: 'debug'
+matrix_bridge_mautrix_whatsapp_logging_level: 'debug'
 ```

docs/configuring-playbook-bridge-mautrix-wsproxy.md

@@ -25,26 +25,26 @@ When setting, replace `example.com` with your own.
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mautrix_wsproxy_enabled: true
+matrix_bridge_mautrix_wsproxy_enabled: true
 
-matrix_mautrix_androidsms_appservice_token: 'secret token from bridge'
-matrix_mautrix_androidsms_homeserver_token: 'secret token from bridge'
-matrix_mautrix_imessage_appservice_token: 'secret token from bridge'
-matrix_mautrix_imessage_homeserver_token: 'secret token from bridge'
-matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_androidsms_appservice_token: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_androidsms_homeserver_token: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_imessage_appservice_token: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_imessage_homeserver_token: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
 ```
 
 Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device.
 
 ### Adjusting the wsproxy URL (optional)
 
-By tweaking the `matrix_mautrix_wsproxy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+By tweaking the `matrix_bridge_mautrix_wsproxy_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
 # Change the default hostname
-matrix_mautrix_wsproxy_hostname: ws.example.com
+matrix_bridge_mautrix_wsproxy_hostname: ws.example.com
 ```
 
 After changing the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.

docs/configuring-playbook-bridge-meshtastic-relay.md

@@ -0,0 +1,95 @@
+<!--
+SPDX-FileCopyrightText: 2025 - 2026 luschmar
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up a Matrix <-> Meshtastic bridge (optional)
+
+The playbook can install and configure [meshtastic-matrix-relay](https://github.com/jeremiah-k/meshtastic-matrix-relay) (sometimes referred to as `mmrelay`) for you — a bridge between [Matrix](https://matrix.org/) and [Meshtastic](https://meshtastic.org/) mesh networks.
+
+See the [project's documentation](https://github.com/jeremiah-k/meshtastic-matrix-relay) to learn what it does and why it might be useful to you.
+
+## Prerequisites
+
+You need a Matrix account for the bot. You can either [register the bot account manually](registering-users.md) or let the playbook create it when running `ansible-playbook … --tags=ensure-matrix-users-created`. Either way, you'll need the account's **password** to configure the bridge — unlike most other bridges in this playbook, `mmrelay` authenticates with a password and creates its own session (optionally with End-to-End Encryption material).
+
+You also need access to a Meshtastic device, connected to the server via one of:
+
+- **TCP**: the device is reachable on the network (e.g. a Meshtastic node running the TCP API),
+- **Serial**: the device is plugged in via USB and available on the host (e.g. `/dev/ttyUSB0`),
+- **BLE**: the device is reachable via Bluetooth Low Energy from the host.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bridge_meshtastic_relay_enabled: true
+
+# Password for the bot's Matrix account.
+# On first startup, the bridge uses this to log in and persist credentials
+# (including End-to-End Encryption material) under its data directory.
+# After that, the password can be removed from this variable.
+matrix_bridge_meshtastic_relay_matrix_bot_password: "PASSWORD_FOR_THE_BOT"
+
+# How the bridge connects to your Meshtastic device.
+# One of: tcp, serial, ble
+matrix_bridge_meshtastic_relay_connection_type: tcp
+
+# For connection_type: tcp
+matrix_bridge_meshtastic_relay_tcp_host: "meshtastic.local"
+
+# For connection_type: serial
+# matrix_bridge_meshtastic_relay_serial_port: "/dev/ttyUSB0"
+
+# For connection_type: ble
+# matrix_bridge_meshtastic_relay_ble_address: "AA:BB:CC:DD:EE:FF"
+
+# Matrix rooms to bridge to Meshtastic channels.
+matrix_bridge_meshtastic_relay_matrix_rooms_list:
+  - id: "#meshtastic:{{ matrix_domain }}"
+    meshtastic_channel: "0"
+```
+
+By default, the bot's Matrix ID is `@meshtasticbot:{{ matrix_domain }}`. To change it, adjust `matrix_bridge_meshtastic_relay_matrix_bot_user_id`.
+
+### Bluetooth (BLE) connections
+
+When `matrix_bridge_meshtastic_relay_connection_type` is `ble`, the container runs with `--network=host` and bind-mounts the host's DBus socket — both are required for Bluetooth pairing/communication. Only use this connection type if you trust the playbook-managed host and are comfortable with these privileges.
+
+### Serial connections
+
+When `matrix_bridge_meshtastic_relay_connection_type` is `serial`, the host device referenced by `matrix_bridge_meshtastic_relay_serial_port` is passed through to the container. Make sure that `matrix_user_uid` / `matrix_user_gid` have read/write access to that device (e.g. by adding the matrix user to the `dialout` group, or adjusting udev rules).
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-meshtastic-relay/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override individual `matrix_bridge_meshtastic_relay_*` variables, or make finer-grained adjustments via `matrix_bridge_meshtastic_relay_configuration_extension_yaml`.
+
+## Installing
+
+After configuring the playbook, 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.
+
+## Usage
+
+Invite the bot to the Matrix rooms listed in `matrix_bridge_meshtastic_relay_matrix_rooms_list` and it will relay between Matrix and the corresponding Meshtastic channel. Messages sent on Meshtastic will appear in Matrix and vice versa.
+
+See the [project's wiki](https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki) for details about commands, plugins and advanced usage.
+
+## 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-meshtastic-relay`.

docs/configuring-playbook-bridge-mx-puppet-groupme.md

@@ -18,7 +18,7 @@ See the project's [documentation](https://gitlab.com/xangelix-pub/matrix/mx-pupp
 To enable the [GroupMe](https://groupme.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mx_puppet_groupme_enabled: true
+matrix_bridge_mx_puppet_groupme_enabled: true
 ```
 
 ## Installing

docs/configuring-playbook-bridge-mx-puppet-steam.md

@@ -20,7 +20,7 @@ See the project's [documentation](https://codeberg.org/icewind/mx-puppet-steam/b
 To enable the [Steam](https://steampowered.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_mx_puppet_steam_enabled: true
+matrix_bridge_mx_puppet_steam_enabled: true
 ```
 
 ## Installing

docs/configuring-playbook-bridge-postmoogle.md

@@ -24,7 +24,7 @@ Open the following ports on your server to be able to receive incoming emails:
 
 If you don't open these ports, you will still be able to send emails, but not receive any.
 
-These port numbers are configurable via the `matrix_postmoogle_smtp_host_bind_port` and `matrix_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
+These port numbers are configurable via the `matrix_bridge_postmoogle_smtp_host_bind_port` and `matrix_bridge_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
 
 ## Adjusting DNS records
 
@@ -44,17 +44,17 @@ To make Postmoogle enable its email sending features, you need to configure MX a
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_postmoogle_enabled: true
+matrix_bridge_postmoogle_enabled: true
 
 # Uncomment and adjust this part if you'd like to use a username different than the default
-# matrix_postmoogle_login: postmoogle
+# matrix_bridge_postmoogle_login: postmoogle
 
 # Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
-matrix_postmoogle_password: PASSWORD_FOR_THE_BOT
+matrix_bridge_postmoogle_password: PASSWORD_FOR_THE_BOT
 
 # Uncomment to add one or more admins to this bridge:
 #
-# matrix_postmoogle_admins:
+# matrix_bridge_postmoogle_admins:
 #  - '@yourAdminAccount:{{ matrix_domain }}'
 #
 # … unless you've made yourself an admin of all bots/bridges like this:
@@ -87,7 +87,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
   `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 bridge's bot password (`matrix_postmoogle_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_postmoogle_password` to let the bot know its new password.
+- If you change the bridge's bot password (`matrix_bridge_postmoogle_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 [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bridge_postmoogle_password` to let the bot know its new password.
 
 ## Usage
 
@@ -108,5 +108,5 @@ As with all other services, you can find the logs in [systemd-journald](https://
 The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
 ```yaml
-matrix_postmoogle_loglevel: 'DEBUG'
+matrix_bridge_postmoogle_loglevel: 'DEBUG'
 ```

docs/configuring-playbook-bridge-rustpush.md

@@ -0,0 +1,100 @@
+<!--
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+SPDX-FileCopyrightText: 2026 Jason LaGuidice
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up RustPush (iMessage) bridging (optional)
+
+> **Note:** This bridge is in early development and may have stability issues. It may not be desirable to deploy this to a large number of users. Your testing and feedback is appreciated.
+
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
+The playbook can install and configure [RustPush bridge to iMessage](https://github.com/jasonlaguidice/imessage) for you using Apple's push notification service.
+
+See the project's [documentation](https://github.com/jasonlaguidice/imessage/blob/main/README.md) to learn what it does and why it might be useful to you.
+
+## Prerequisites
+
+### Hardware Key Extraction
+
+To use this bridge on Linux (Docker), each user needs a **hardware key** extracted from a real Mac. This key contains hardware identifiers needed for iMessage registration. Hardware keys can be shared by a number of users (approximately 20) before causing issues with Apple.
+
+The key is entered interactively through the bridge bot's login flow (not configured via Ansible variables). See the upstream [README](https://github.com/jasonlaguidice/imessage/blob/main/README.md) for instructions on extracting the key.
+
+If extracted from an Intel Mac, the Mac does not need to remain running after the key is extracted for this bridge to work. Apple Silicon Macs must run a NAC relay and thus must remain running.
+
+### Phone Number Registration (optional)
+
+This bridge can **not** do phone number registration (PNR). The only way to have your phone number registered and used (instead of an Apple ID e-mail address) is to have an iPhone connected to your Apple account. Reference the [BlueBubbles Phone Number Registration Guide](https://docs.bluebubbles.app/server/advanced/registering-a-phone-number-with-your-imessage-account) for information on how to set this up.
+
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bridge_rustpush_enabled: true
+```
+
+### Disable Backfill (optional)
+
+Backfill can be disabled globally if desired via config. By default, the bridge will backfill from iCloud (CloudKit) and APNS if available. Backfill from `chat.db` is only possible when the bridge is running on MacOS.
+
+```yaml
+matrix_bridge_rustpush_backfill_enabled: false
+```
+
+### Extending the Configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it 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
+```
+
+**Notes**:
+
+- 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.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@rustpushbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+After logging in, the bridge will start receiving iMessages and creating portal rooms.
+
+## 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-rustpush-bridge`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_bridge_rustpush_logging_level: 'debug'
+
+# Enable debug logging for RustPush
+matrix_bridge_rustpush_rust_log: "warn,rustpushgo=info,openabsinthe=debug"
+```
+## Notable Configuration Options
+- `matrix_bridge_rustpush_statuskit_notifications` will display StatusKit information for conversation participants. In some clients, this update will cause the DM to be pushed to the top of the conversation list continuously, so this option is disabled by default.
+  - `matrix_bridge_rustpush_statuskit_notification_style` can be set to either `topic` or `notice`
+  - `topic` sets the status as a room topic. In supported clients (like Cinny and Sable), this will display `🔕 Focus` as a second line when the person has focus mode enabled.
+  - `notice` sends an `m.notice` event to the room which will display text in the room but should not generate a notification

docs/configuring-playbook-bridge-steam.md

@@ -15,7 +15,7 @@ See the project's [documentation](https://github.com/jasonlaguidice/matrix-steam
 To enable the [Steam](https://steampowered.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_steam_bridge_enabled: true
+matrix_bridge_steam_enabled: true
 ```
 
 ## Installing
@@ -46,3 +46,6 @@ Once logged in, send `search [name]` to search through recognized Steam friends.
 Chat rooms will automatically be opened as new messages are received.
 
 Send `help` to the bot to see the available commands.
+
+## Notable Configuration Options
+- `matrix_bridge_steam_network_presence_topic_enabled` and `matrix_bridge_steam_network_presence_topic_rich_presence_enabled` mirror Steam's [Enhanced Rich Presence](https://partner.steamgames.com/doc/features/enhancedrichpresence) feature in Matrix. This will display the user's current game and rich presence if supported by the game. This sets the DM room's `m.topic` field to achieve this. Some games (like Deadlock) update the rich presence every minute with a match timer. In some clients, the topic update will cause the DM to be pushed to the top of the conversation list continuously, so this option is disabled by default.

docs/configuring-playbook-bridge-wechat.md

@@ -19,7 +19,7 @@ See the project's [documentation](https://github.com/duo/matrix-wechat/blob/mast
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_wechat_enabled: true
+matrix_bridge_wechat_enabled: true
 ```
 
 ### Extending the configuration
@@ -29,7 +29,7 @@ There are some additional things you may wish to configure about the bridge.
 Take a look at:
 
 - `roles/custom/matrix-bridge-wechat/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-wechat/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_wechat_configuration_extension_yaml` variable
+- `roles/custom/matrix-bridge-wechat/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bridge_wechat_configuration_extension_yaml` variable
 
 ## Installing
 
@@ -62,5 +62,5 @@ The default logging level for this component is `warn`. If you want to increase
 
 ```yaml
 # Valid values: fatal, error, warn, info, debug
-matrix_wechat_log_level: 'debug'
+matrix_bridge_wechat_log_level: 'debug'
 ```

docs/configuring-playbook-client-commet.md

@@ -0,0 +1,93 @@
+<!--
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Commet (optional)
+
+The playbook can install and configure the [Commet](https://github.com/commetchat/commet) Matrix web client for you.
+
+## Adjusting DNS records
+
+By default, this playbook installs Commet on the `commet.` subdomain (`commet.example.com`) and requires you to create a CNAME record for `commet`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+## Adjusting the playbook configuration
+
+To enable Commet, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_client_commet_enabled: true
+```
+
+### Adjusting the Commet URL (optional)
+
+By tweaking the `matrix_client_commet_hostname` and `matrix_client_commet_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Commet.
+matrix_client_commet_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /commet subpath
+matrix_client_commet_path_prefix: /commet
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the Commet domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+**Note**: `matrix_client_commet_path_prefix` must either be `/` or not end with a slash (e.g. `/commet`).
+
+### Adjusting the default homeserver (optional)
+
+Commet is configured with a `default_homeserver` value. By default, the playbook uses `matrix.org`.
+
+To change it, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_client_commet_default_homeserver: "{{ matrix_domain }}"
+```
+
+### Adjusting the Commet version/branch to build (optional)
+
+When self-building the container image (`matrix_client_commet_container_image_self_build: true`), the playbook checks out the Commet source repository and builds an image from it.
+
+To build from a different git branch/tag/SHA, set `matrix_client_commet_version` in your `vars.yml` file:
+
+```yaml
+# Examples: "main", "v1.2.3", "feature-branch", "a1b2c3d4"
+matrix_client_commet_version: "main"
+```
+
+**Note**: by default, the image tag is derived from `matrix_client_commet_version` (`localhost/matrix-client-commet:{{ matrix_client_commet_version }}`). If your branch name contains `/` (e.g. `feature/foo`), override `matrix_client_commet_container_image` (and optionally `matrix_client_commet_container_image_self_build_version_tag`) to a Docker-tag-safe value.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-commet/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-commet/templates/global_config.json.j2` for the component's default runtime configuration
+
+## Installing
+
+After configuring the playbook and potentially [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-commet`.

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/SableClient/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-conduwuit.md

@@ -1,6 +1,6 @@
 <!--
 SPDX-FileCopyrightText: 2019 Eduardo Beltrame
-SPDX-FileCopyrightText: 2019-2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019-2026 Slavi Pantaleev
 SPDX-FileCopyrightText: 2020 Tulir Asokan
 SPDX-FileCopyrightText: 2021, 2024 MDAD project contributors
 SPDX-FileCopyrightText: 2022 Dennis Ciba
@@ -29,13 +29,17 @@ To uninstall the service, run the command below on the server:
 systemctl disable --now matrix-conduwuit.service
 ```
 
+## Migrating to Tuwunel
+
+[Tuwunel](configuring-playbook-tuwunel.md) is a fork of conduwuit, [endorsed as conduwuit's successor](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/5200#issuecomment-4396211185) by the former conduwuit maintainer. It reads conduwuit's database directly, so migration is possible. Please refer to [this section](./configuring-playbook-tuwunel.md#migrating-from-conduwuit) for details.
+
 ## Migrating to Continuwuity
 
 Since [Continuwuity](configuring-playbook-continuwuity.md) is a drop-in replacement for conduwuit, migration is possible. Please refer to [this section](./configuring-playbook-continuwuity.md#migrating-from-conduwuit) for details.
 
 ## Removing data manually
 
-If you are not going to migrate to [Continuwuity](configuring-playbook-continuwuity.md), you can remove data by running the command on the server:
+If you are not going to migrate to [Tuwunel](configuring-playbook-tuwunel.md) or [Continuwuity](configuring-playbook-continuwuity.md), you can remove data by running the command on the server:
 
 ```sh
 rm -rf /matrix/conduwuit

docs/configuring-playbook-continuwuity.md

@@ -46,6 +46,13 @@ Take a look at:
 
 There are various Ansible variables that control settings in the `continuwuity.toml` file.
 
+💡 By default, the playbook wires Continuwuity into a few playbook-wide settings:
+
+- if `exim_relay_enabled: true` (the default), Continuwuity SMTP is automatically enabled and pointed at the [local Exim relay](configuring-playbook-email.md) service
+- `matrix_continuwuity_config_well_known_client` is automatically set to the public homeserver URL in the usual SSL-enabled setup, which helps email verification and password-reset links work in delegated-domain setups
+
+You can override any of these defaults in your `vars.yml` file if you want Continuwuity to use a different SMTP server or a different well-known client URL.
+
 If a specific setting you'd like to change does not have a dedicated Ansible variable, you can either submit a PR to us to add it, or you can [override the setting using an environment variable](https://continuwuity.org/configuration#environment-variables) using `matrix_continuwuity_environment_variables_extension`. For example:
 
 ```yaml

docs/configuring-playbook-element-admin.md

@@ -13,7 +13,7 @@ Element Admin is a web-based administration panel for Synapse and [Matrix Authen
 
 See the project's [documentation](https://github.com/element-hq/element-admin) to learn more.
 
-💡 **Note**: This project is still very young and doesn't have many features. For now, it's recommended to use [Synapse Admin](./configuring-playbook-synapse-admin.md) instead. Deployments that use [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) can use Element Admin for user-management (something that Synapse Admin can't do), while continuing to use Synapse Admin for all other purposes.
+💡 **Note**: This project is still very young and doesn't have many features. [Ketesa](./configuring-playbook-ketesa.md) is the fully-featured alternative — it covers all Synapse and MAS Admin APIs, including complete user management, session management, and MAS policy data. Element Admin remains a valid choice if you prefer its interface.
 
 ## Prerequisites
 

docs/configuring-playbook-email.md

@@ -23,7 +23,7 @@ The [Ansible role for exim-relay](https://github.com/mother-of-all-self-hosting/
 
 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
+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), [Continuwuity](configuring-playbook-continuwuity.md), etc.) there, with 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
 

docs/configuring-playbook-federation.md

@@ -24,14 +24,14 @@ matrix_synapse_federation_domain_whitelist:
 
 If you wish to disable federation, you can do that with an empty list (`[]`), or better yet by completely disabling federation (see below).
 
-## Exposing the room directory over federation
+## Controlling exposure of the room directory over federation
 
-By default, your server's public rooms directory is not exposed to other servers via federation.
+By default, your server's public rooms directory is exposed to other servers via federation, so that public rooms hosted on your server can be discovered by users on other servers. This goes against the Synapse upstream default (which is `false`); see the [2023-10-23 changelog entry](../CHANGELOG.md#enabling-allow_public_rooms_over_federation-by-default-for-synapse) for the reasoning behind this choice.
 
-To expose it, add the following configuration to your `vars.yml` file:
+To prevent your public rooms directory from being exposed over federation (restoring the Synapse upstream default), add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_synapse_allow_public_rooms_over_federation: true
+matrix_synapse_allow_public_rooms_over_federation: false
 ```
 
 ## Disabling federation
@@ -71,4 +71,6 @@ matrix_synapse_federation_port_enabled: false
 matrix_synapse_tls_federation_listener_enabled: false
 ```
 
+**Note**: `matrix_synapse_federation_port_enabled: false` only makes sense in this specific setup, where federation traffic is served through the client port (because of the `federation` entry in `matrix_synapse_http_listener_resource_names`). If federation still flows through the dedicated federation port on your setup (e.g. another reverse proxy of yours forwarding a custom public port to this playbook's federation port), leave `matrix_synapse_federation_port_enabled` at its default (enabled). Disabling it removes the federation route entirely and breaks such setups.
+
 **Use this at you own risk as all the possible side-effects of doing this are not fully known. However, it has been tested and works fine and passes all the tests on <https://federationtester.matrix.org/> without issues.**

docs/configuring-playbook-jwt-service.md

@@ -1,47 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2024 wjbeckett
-SPDX-FileCopyrightText: 2024 Slavi Pantaleev
-
-SPDX-License-Identifier: AGPL-3.0-or-later
--->
-
-# Setting up JWT Service (optional)
-
-The playbook can install and configure [LiveKit JWT Service](https://github.com/element-hq/lk-jwt-service) for you.
-
-LK-JWT-Service is currently used for a single reason: generate JWT tokens with a given identity for a given room, so that users can use them to authenticate against LiveKit SFU.
-
-See the project's [documentation](https://github.com/element-hq/lk-jwt-service/) to learn more.
-
-## Decide on a domain and path
-
-By default, JWT Service is configured to be served:
-
-- on the Matrix domain (`matrix.example.com`), configurable via `matrix_livekit_jwt_service_hostname`
-- under a `/livekit-jwt-service` path prefix, configurable via `matrix_livekit_jwt_service_path_prefix`
-
-This makes it easy to set it up, **without** having to adjust your DNS records manually.
-
-## Adjusting DNS records
-
-If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server.
-
-## Adjusting the playbook configuration
-
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_livekit_jwt_service_enabled: true
-```
-
-## Installing
-
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
-
-## Usage
-
-Once installed, a new `org.matrix.msc4143.rtc_foci` section is added to the Element Web client to point to your JWT service URL (e.g., `https://matrix.example.com/livekit-jwt-service`).
-
-## Additional Information
-
-Refer to the LiveKit JWT-Service documentation for more details on configuring and using JWT Service.

docs/configuring-playbook-ketesa.md

@@ -0,0 +1,101 @@
+<!--
+SPDX-FileCopyrightText: 2020-2024 MDAD project contributors
+SPDX-FileCopyrightText: 2020-2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Aaron Raimist
+SPDX-FileCopyrightText: 2023 Christian González
+SPDX-FileCopyrightText: 2024 Nikita Chernyi
+SPDX-FileCopyrightText: 2024 Uğur İLTER
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
+SPDX-FileCopyrightText: 2026 Nikita Chernyi
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Ketesa (optional)
+
+The playbook can install and configure [Ketesa](https://ketesa.app) ([source code](https://github.com/etkecc/ketesa)) for you.
+
+Ketesa is a fully-featured admin interface for Matrix homeservers — manage users, rooms, media, sessions, and more from one clean, responsive web UI. It is the evolution of [Awesome-Technologies/synapse-admin](https://github.com/Awesome-Technologies/synapse-admin): what began as a fork has grown into its own independent project with a redesigned interface, comprehensive Synapse and MAS API coverage, and multi-language support. See the [Ketesa v1.0.0 announcement](https://etke.cc/blog/introducing-ketesa/) for a full overview of what's new.
+
+>[!NOTE]
+>
+> - Ketesa does not work with other homeserver implementations than Synapse due to API's incompatibility.
+> - The latest version of Ketesa is hosted by [etke.cc](https://etke.cc/) at [cloud.ketesa.app](https://cloud.ketesa.app/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting.
+> - This playbook also supports an alternative management UI in the shape of [Element Admin](./configuring-playbook-element-admin.md). Please note that it's currently less feature-rich than Ketesa and requires [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md).
+
+## Adjusting DNS records (optional)
+
+By default, this playbook installs Ketesa on the `matrix.` subdomain, at the `/synapse-admin` path (https://matrix.example.com/synapse-admin) — the legacy path is kept for backward compatibility. This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
+
+If you wish to adjust it, see the section [below](#adjusting-the-ketesa-url-optional) for details about DNS configuration.
+
+## Adjusting the playbook configuration
+
+To enable Ketesa, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_ketesa_enabled: true
+```
+
+**Note**: Ketesa requires Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). Because Ketesa needs these APIs to function, when installing Ketesa, the playbook **automatically** exposes the Synapse Admin API publicly for you. Depending on the homeserver implementation you're using (Synapse, Dendrite), this is equivalent to:
+
+- for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true`
+- for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true`
+- for [Tuwunel](./configuring-playbook-tuwunel.md): `matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: true`
+
+By default, Ketesa installation will be [restricted to only work with one homeserver](https://github.com/etkecc/ketesa/blob/main/README.md#restricting-available-homeserver) — the one managed by the playbook. To adjust these restrictions, tweak the `matrix_ketesa_config_restrictBaseUrl` variable.
+
+### Adjusting the Ketesa URL (optional)
+
+By tweaking the `matrix_ketesa_hostname` and `matrix_ketesa_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+We recommend updating the path prefix to `/ketesa` to align with the new branding, while the default `/synapse-admin` is kept for backward compatibility:
+
+```yaml
+matrix_ketesa_path_prefix: /ketesa
+```
+
+Or to change the hostname entirely:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_ketesa_hostname: admin.example.com
+matrix_ketesa_path_prefix: /
+```
+
+If you've changed the default hostname, you may need to create a CNAME record for the Ketesa domain (`admin.example.com`), which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-ketesa/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_ketesa_configuration_extension_json` variable
+
+## Installing
+
+After configuring the playbook and potentially [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.
+
+## Usage
+
+After installation, Ketesa will be accessible at: `https://matrix.example.com/synapse-admin/` (or `/ketesa/` if you updated the path prefix as recommended)
+
+To use Ketesa, you need to have [registered at least one administrator account](registering-users.md) on your server.
+
+## 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-ketesa`.
+
+If you have questions, you can join this community room and feel free to ask: [#ketesa:etke.cc](https://matrix.to/#/#ketesa:etke.cc)

docs/configuring-playbook-ldap-auth.md

@@ -11,7 +11,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 The playbook can install and configure the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider for you.
 
-See the project's [documentation](https://github.com/matrix-org/matrix-synapse-ldap3/blob/main/README.rst) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/matrix-synapse-ldap3/blob/main/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
@@ -52,9 +52,3 @@ 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.
-
-## Usage
-
-### Handling user registration
-
-If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md).

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
 
@@ -59,6 +61,12 @@ livekit_server_container_labels_turn_traefik_entrypoints: "<your-livekit-turn-tr
 
 and configuring their own Traefik TCP entrypoint dedicated to LiveKit TURN traffic.
 
+## TURN access controls
+
+LiveKit's embedded TURN server enforces a credential TTL and restricts which peer CIDRs it will relay to. The playbook leaves these at the role's secure defaults, which are appropriate for typical deployments where TURN peers live on the public Internet.
+
+If your setup needs TURN to relay to private/restricted ranges, or you want to override the credential TTL, see the [TURN access controls and credential TTL](https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server/blob/main/docs/configuring-livekit-server.md#turn-access-controls-and-credential-ttl) section of the role's documentation.
+
 ## Limitations
 
 LiveKit Server's TURN listener behavior depends on where TLS is terminated:

docs/configuring-playbook-matrix-authentication-service.md

@@ -51,7 +51,7 @@ This section details what you can expect when switching to the Matrix Authentica
 
 - ❌ **Synapse password providers will need to be disabled**. You can no longer use [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc. When the authentication flow is handled by MAS (not by Synapse anymore), it doesn't make sense to extend the Synapse authentication flow with additional modules. Many bridges used to rely on shared-secret-auth for doing double-puppeting (impersonating other users), but most (at least the mautrix bridges) nowadays use [Appservice Double Puppet](./configuring-playbook-appservice-double-puppet.md) as a better alternative. Older/maintained bridges may still rely on shared-secret-auth, as do other services like [matrix-corporal](./configuring-playbook-matrix-corporal.md).
 
-- ❌ Certain **tools like [Synapse Admin](./configuring-playbook-synapse-admin.md) do not have full compatibility with MAS yet**. Synapse Admin already supports OIDC auth, browsing users (which Synapse will internally fetch from MAS) and updating user avatars. However, editing users (passwords, etc.) now needs to happen directly against MAS using the [MAS Admin API](https://element-hq.github.io/matrix-authentication-service/api/index.html), which Synapse Admin cannot interact with yet. You may be interested in using [Element Admin](./configuring-playbook-element-admin.md) for these purposes.
+- ✅ **[Ketesa](./configuring-playbook-ketesa.md) has full MAS integration**. Ketesa supports OIDC auth, user management, all session types (browser, OAuth2, compatibility), linked email addresses, upstream OAuth provider links, MAS policy data, and user creation through MAS. It is the recommended tool for managing homeservers running MAS.
 
 - ❌ **Some services experience issues when authenticating via MAS**:
 
@@ -398,6 +398,8 @@ To perform a real migration, run the `matrix-authentication-service-mas-cli-syn2
 just run-tags matrix-authentication-service-mas-cli-syn2mas
 ```
 
+After `syn2mas` completes, Synapse will intentionally remain stopped to avoid new registrations or other authentication changes from being accepted before the migration is completed. Continue with the next steps in this guide before re-running the installation.
+
 Having performed a `syn2mas` migration once, trying to do it again will report errors (e.g. "Error: The MAS database is not empty: rows found in at least `users`. Please drop and recreate the database, then try again.").
 
 ## Verify that Matrix Authentication Service is installed correctly

docs/configuring-playbook-matrix-ldap-registration-proxy.md

@@ -1,69 +1,32 @@
 <!--
-SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Edgars Voroboks
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2019-2025 MDAD project contributors
+SPDX-FileCopyrightText: 2019-2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Chris van Dijk
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2020 jens quade
+SPDX-FileCopyrightText: 2022 Dennis Ciba
 SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
-SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2022 Kim Brose
+SPDX-FileCopyrightText: 2022 Travis Ralston
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2022 Yan Minagawa
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Setting up matrix-ldap-registration-proxy (optional)
+# Setting up matrix-ldap-registration-proxy (optional, removed)
 
-The playbook can install and configure [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) for you.
+🪦 The playbook used to be able to install and configure [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy), but no longer includes this component, as it has become unavailable.
 
-This proxy handles Matrix registration requests and forwards them to LDAP.
+## Uninstalling the component manually
 
-See the project's [documentation](https://gitlab.com/activism.international/matrix_ldap_registration_proxy/-/blob/main/README.md) to learn what it does and why it might be useful to you.
+If you still have matrix-ldap-registration-proxy installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server:
 
-**Note**: This does support the full Matrix specification for registrations. It only provide a very coarse implementation of a basic password registration.
-
-## Adjusting the playbook configuration
-
-To enable the component, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
-
-```yaml
-matrix_ldap_registration_proxy_enabled: true
-
-# LDAP credentials
-matrix_ldap_registration_proxy_ldap_uri: YOUR_URI_HERE
-matrix_ldap_registration_proxy_ldap_base_dn: YOUR_DN_HERE
-matrix_ldap_registration_proxy_ldap_user: YOUR_USER_HERE
-matrix_ldap_registration_proxy_ldap_password: YOUR_PASSWORD_HERE
-```
-
-If you already use the [synapse external password provider via LDAP](configuring-playbook-ldap-auth.md) (that is, you have `matrix_synapse_ext_password_provider_ldap_enabled: true` and other options in your configuration) you can use the following values as configuration:
-
-```yaml
-# Use the LDAP values specified for the synapse role to setup LDAP proxy
-matrix_ldap_registration_proxy_ldap_uri: "{{ matrix_synapse_ext_password_provider_ldap_uri }}"
-matrix_ldap_registration_proxy_ldap_base_dn: "{{ matrix_synapse_ext_password_provider_ldap_base }}"
-matrix_ldap_registration_proxy_ldap_user: "{{ matrix_synapse_ext_password_provider_ldap_bind_dn }}"
-matrix_ldap_registration_proxy_ldap_password: "{{ matrix_synapse_ext_password_provider_ldap_bind_password }}"
-
-matrix_ldap_registration_proxy_systemd_wanted_services_list_custom:
-  - matrix-synapse.service
-```
-
-### Extending the configuration
-
-There are some additional things you may wish to configure about the component.
-
-Take a look at:
-
-- `roles/custom/matrix-ldap-registration-proxy/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-
-## Installing
-
-After configuring the playbook, run it 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
+systemctl disable --now matrix-ldap-registration-proxy.service
+
+rm -rf /matrix/matrix_ldap_registration_proxy
 ```
-
-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-ldap-registration-proxy`.

docs/configuring-playbook-matrix-registration.md

@@ -1,115 +1,36 @@
 <!--
-SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
-SPDX-FileCopyrightText: 2022 MDAD project contributors
-SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2019 Edgars Voroboks
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2019-2025 MDAD project contributors
+SPDX-FileCopyrightText: 2019-2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Chris van Dijk
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2020 jens quade
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Kim Brose
+SPDX-FileCopyrightText: 2022 Travis Ralston
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2022 Yan Minagawa
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Setting up matrix-registration (optional)
+# Setting up matrix-registration (optional, removed)
 
-> [!WARNING]
-> - This is a poorly maintained and buggy project. It's better to avoid using it.
-> - This is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md)
+> [!NOTE]
+> This is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md).
 
-The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you. It is a simple python application to have a token based Matrix registration.
+🪦 The playbook used to be able to install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration), but no longer includes this component, as it has been unmaintained since November, 2025.
 
-Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows certain people (these having a special link) to register a user account, **keeping your server's registration closed (private)**.
+## Uninstalling the component manually
 
-**matrix-registration** provides 2 things:
-
-- **an API for creating registration tokens** (unique registration links). This API can be used via `curl` or via the playbook (see [Usage](#usage) below)
-
-- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.example.com/matrix-registration`
-
-## Adjusting DNS records (optional)
-
-By default, this playbook installs the matrix-registration on the `matrix.` subdomain, at the `/matrix-registration` path (https://matrix.example.com/matrix-registration). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
-
-If you wish to adjust it, see the section [below](#adjusting-the-matrix-registration-url-optional) for details about DNS configuration.
-
-## Adjusting the playbook configuration
-
-To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_registration_enabled: true
-
-# Generate a strong secret here. You can create one with a command like `pwgen -s 64 1`.
-matrix_registration_admin_secret: "ENTER_SOME_SECRET_HERE"
-```
-
-### Adjusting the matrix-registration URL (optional)
-
-By tweaking the `matrix_registration_hostname` and `matrix_registration_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
-
-Example additional configuration for your `vars.yml` file:
-
-```yaml
-# Change the default hostname and path prefix
-matrix_registration_hostname: registration.example.com
-matrix_registration_path_prefix: /
-```
-
-If you've changed the default hostname, you may need to create a CNAME record for the matrix-registration domain (`registration.example.com`), which targets `matrix.example.com`.
-
-When setting, replace `example.com` with your own.
-
-### Extending the configuration
-
-There are some additional things you may wish to configure about the component.
-
-Take a look at:
-
-- `roles/custom/matrix-registration/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-registration/templates/config.yaml.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_registration_configuration_extension_yaml` variable
-
-## Installing
-
-After configuring the playbook and potentially [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.
-
-## Usage
-
-**matrix-registration** gets exposed at `https://matrix.example.com/matrix-registration`
-
-It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) — for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`.
-
-We make the most common APIs easy to use via the playbook (see below).
-
-### Creating registration tokens
-
-To **create a new user registration token (link)**, use this command:
+If you still have matrix-registration installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server:
 
 ```sh
-ansible-playbook -i inventory/hosts setup.yml \
---tags=generate-matrix-registration-token \
---extra-vars="one_time=yes ex_date=2021-12-31"
+systemctl disable --now matrix-registration.service
+
+rm -rf /matrix/matrix-registration
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_registration;'
 ```
-
-The above command creates and returns a **one-time use** token, which **expires** on the 31st of December 2021. Adjust the `one_time` and `ex_date` variables as you see fit.
-
-Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
-
-### Listing registration tokens
-
-To **list the existing user registration tokens**, use this command:
-
-```sh
-ansible-playbook -i inventory/hosts setup.yml \
---tags=list-matrix-registration-tokens
-```
-
-The shortcut command with `just` program is also available: `just run-tags list-matrix-registration-tokens`
-
-## 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-registration`.

docs/configuring-playbook-matrix-rtc.md

@@ -38,6 +38,12 @@ matrix_rtc_enabled: true
 
 In addition to the HTTP/HTTPS ports (which you've already exposed as per the [prerequisites](prerequisites.md) document), you'll also need to open ports required by [LiveKit Server](configuring-playbook-livekit-server.md) as described in its own [Adjusting firewall rules](configuring-playbook-livekit-server.md#adjusting-firewall-rules) section.
 
+## Fronting the integrated reverse-proxy with another reverse-proxy
+
+If you're [fronting the integrated reverse-proxy webserver with another reverse-proxy](configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) (e.g. nginx), it needs to forward WebSocket traffic for [LiveKit Server](configuring-playbook-livekit-server.md) at the `/livekit-server/` path. Without that, Matrix RTC calls will not work.
+
+See [`examples/reverse-proxies/nginx/matrix.conf`](../examples/reverse-proxies/nginx/matrix.conf) for an nginx example.
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records) and [adjusting firewall rules](#adjusting-firewall-rules), run the playbook with [playbook tags](playbook-tags.md) as below:

docs/configuring-playbook-prometheus-grafana.md

@@ -178,11 +178,14 @@ 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`.
+`ntfy_metrics_listen_http_port`|Set this to a port number (e.g. `9090`) to make [ntfy](configuring-playbook-ntfy.md) serve its metrics (locally, on the container network) on that port.
+`ntfy_container_labels_traefik_metrics_enabled`|Set this to `true` to expose the [ntfy](configuring-playbook-ntfy.md) metrics on `https://matrix.example.com/metrics/ntfy`.
+`matrix_synapse_usage_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [synapse-usage-exporter](configuring-playbook-synapse-usage-exporter.md) metrics on `https://matrix.example.com/metrics/synapse-usage-exporter`.
 
 ### Expose metrics of other services/roles
 

docs/configuring-playbook-synapse-admin.md

@@ -1,93 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2020-2024 MDAD project contributors
-SPDX-FileCopyrightText: 2020-2024 Slavi Pantaleev
-SPDX-FileCopyrightText: 2021 Aaron Raimist
-SPDX-FileCopyrightText: 2023 Christian González
-SPDX-FileCopyrightText: 2024 Nikita Chernyi
-SPDX-FileCopyrightText: 2024 Uğur İLTER
-SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
-
-SPDX-License-Identifier: AGPL-3.0-or-later
--->
-
-# Setting up Synapse Admin (optional)
-
-The playbook can install and configure Synapse Admin for you.
-
-Synapse Admin is a web UI tool you can use to **administrate users, rooms, media, etc. on your Matrix homeserver**. This playbook is configured to install [etkecc/synapse-admin](https://github.com/etkecc/synapse-admin), which is a [feature-rich](https://github.com/etkecc/synapse-admin#fork-differences) fork of [Awesome-Technologies/synapse-admin](https://github.com/Awesome-Technologies/synapse-admin).
-
->[!NOTE]
->
-> - Synapse Admin does not work with other homeserver implementations than Synapse due to API's incompatibility.
-> - The latest version of Synapse Admin is hosted by [etke.cc](https://etke.cc/) at [admin.etke.cc](https://admin.etke.cc/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting.
-> - This playbook also supports an alternative management UI in the shape of [Element Admin](./configuring-playbook-element-admin.md). Please note that it's currently less feature-rich than Synapse Admin and requires [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md).
-
-## Adjusting DNS records (optional)
-
-By default, this playbook installs Synapse Admin on the `matrix.` subdomain, at the `/synapse-admin` path (https://matrix.example.com/synapse-admin). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
-
-If you wish to adjust it, see the section [below](#adjusting-the-synapse-admin-url-optional) for details about DNS configuration.
-
-## Adjusting the playbook configuration
-
-To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_synapse_admin_enabled: true
-```
-
-**Note**: Synapse Admin requires Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, the playbook **automatically** exposes the Synapse Admin API publicly for you. Depending on the homeserver implementation you're using (Synapse, Dendrite), this is equivalent to:
-
-- for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true`
-- for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true`
-
-By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) — the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable.
-
-### Adjusting the Synapse Admin URL (optional)
-
-By tweaking the `matrix_synapse_admin_hostname` and `matrix_synapse_admin_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
-
-Example additional configuration for your `vars.yml` file:
-
-```yaml
-# Change the default hostname and path prefix
-matrix_synapse_admin_hostname: admin.example.com
-matrix_synapse_admin_path_prefix: /
-```
-
-If you've changed the default hostname, you may need to create a CNAME record for the Synapse Admin domain (`admin.example.com`), which targets `matrix.example.com`.
-
-When setting, replace `example.com` with your own.
-
-### Extending the configuration
-
-There are some additional things you may wish to configure about the component.
-
-Take a look at:
-
-- `roles/custom/matrix-synapse-admin/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_synapse_admin_configuration_extension_json` variable
-
-## Installing
-
-After configuring the playbook and potentially [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.
-
-## Usage
-
-After installation, Synapse Admin will be accessible at: `https://matrix.example.com/synapse-admin/`
-
-To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server.
-
-## 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-synapse-admin`.
-
-If you have questions, you can join this community room and feel free to ask: [#synapse-admin:etke.cc](https://matrix.to/#/#synapse-admin:etke.cc)

docs/configuring-playbook-synapse-usage-exporter.md

@@ -1,7 +1,7 @@
 <!--
 SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 Michael Hollister
-SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2026 Slavi Pantaleev
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
@@ -38,13 +38,35 @@ To enable synapse-usage-exporter, add the following configuration to your `inven
 ```yaml
 matrix_synapse_usage_exporter_enabled: true
 
-# (Optional) Expose endpoint if you want to collect statistics from outside (from other homeservers).
+# (Optional) Expose the usage-stats ingestion endpoint if you want to collect statistics from outside (from other homeservers).
 # If enabled, synapse-usage-exporter will be exposed publicly at `matrix.example.com/report-usage-stats/push`.
 # When collecting usage statistics for Synapse running on the same host, you don't need to enable this.
 # You can adjust the hostname and path via `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix`.
 # matrix_synapse_usage_exporter_proxying_enabled: true
 ```
 
+**Note**: `matrix_synapse_usage_exporter_proxying_enabled` only exposes the endpoint that Synapse pushes usage statistics **to** (`/report-usage-stats/push`). Despite its generic name, it has nothing to do with the metrics endpoint that Prometheus reads **from**. See [below](#collecting-metrics-to-an-external-prometheus-server) for exposing metrics.
+
+### Collecting metrics to an external Prometheus server
+
+Metrics are always served on the container network, so the [integrated Prometheus](./configuring-playbook-prometheus-grafana.md) (`prometheus_enabled: true`) scrapes them without any additional configuration.
+
+To collect them with an **external Prometheus server**, you need to expose them publicly. You can do so by enabling metrics exposure for all services (`matrix_metrics_exposure_enabled: true`), or just for this service:
+
+```yaml
+# Expose the metrics on https://matrix.example.com/metrics/synapse-usage-exporter
+matrix_synapse_usage_exporter_metrics_proxying_enabled: true
+
+# Uncomment to password-protect the metrics for synapse-usage-exporter.
+# matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_enabled: true
+
+# Uncomment and set this part to the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint.
+# See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
+# matrix_synapse_usage_exporter_container_labels_traefik_metrics_middleware_basic_auth_users: ''
+```
+
+Refer to [this section](./configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) of the Prometheus and Grafana documentation for more details.
+
 ### Adjusting the synapse-usage-exporter URL (optional)
 
 By tweaking the `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.

docs/configuring-playbook-synapse.md

@@ -196,11 +196,11 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 
 ## Usage
 
-### Synapse Admin
+### Ketesa
 
-With [Synapse Admin](configuring-playbook-synapse-admin.md), certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace.
+[Ketesa](configuring-playbook-ketesa.md) is a fully-featured web UI for administrating your homeserver — managing users, rooms, media, sessions, and more.
 
-The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
+The playbook can install and configure Ketesa for you. For details about it, see [this page](configuring-playbook-ketesa.md).
 
 ### Monitoring Synapse Metrics with Prometheus and Grafana
 

docs/configuring-playbook-synology.md

@@ -0,0 +1,179 @@
+<!--
+SPDX-FileCopyrightText: 2026 Chiu Ki Sit
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Configuring Synology DSM
+
+This document is a guide for preparing Synology DSM for the installation of the [Matrix Docker Ansible Deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy) project.
+
+> **Note:** Synology DSM is a community-supported platform. It is not officially tested or maintained by the project maintainers. Use at your own discretion.
+
+**Intended audience:** Users already familiar with DSM, SSH, and this Ansible project.
+
+## Assumptions
+
+- DSM version 7 or higher
+- `Volume1` is used as the default Docker storage location
+- You are using DSM's built-in reverse proxy for handling HTTPS
+
+## How Synology Support Works
+
+The playbook automatically detects Synology DSM by checking for `/etc/synoinfo.conf`. When detected, it:
+
+- Uses `synouser` and `synogroup` (DSM-native tools) instead of standard Linux user management
+- Constrains the Python `requests` package to a version compatible with the Docker SDK
+- Ensures `/volume1` has shared mount propagation so container bind mounts work correctly
+- Deploys a `matrix-synology-boot-fix` service that runs on every boot after Docker is ready
+
+You can override auto-detection by setting `matrix_base_host_is_synology: true` or `false` in your `vars.yml`.
+
+### Matrix Service Account
+
+The playbook creates a `matrix` system account using Synology's `synouser` tool. The account is secured as follows:
+
+- **Expired** (`expired=1`) — the account cannot be used to log in to DSM or any application
+
+You must set a password for this account via `matrix_synology_user_password` in your `vars.yml` (see [vars.yml Configuration](#varsyml-configuration)). The password cannot be used to log in because the account is expired, but a non-empty password is required as an additional security layer.
+
+> If you pre-create the `matrix` user manually before running the playbook, the playbook will not modify the existing account's settings — you are responsible for securing it.
+
+### Boot-fix Service
+
+Synology DSM has two boot-time quirks that the boot-fix service addresses automatically:
+
+1. **`/volume1` shared mount propagation**
+
+    Docker requires `/volume1` to be mounted as shared (`mount --make-shared /volume1`) for container bind mounts with `bind-propagation=slave` to work correctly (used by matrix-synapse for its media store). On Synology, this cannot be inserted into the systemd chain before Container Manager starts — doing so causes Container Manager to detect a broken dependency and prompt for repair on every boot. The playbook applies this during setup, and the boot-fix service re-applies it on every subsequent reboot, safely outside Container Manager's dependency chain.
+
+2. **Skipped services at boot**
+
+    Synology's systemd drops services with multi-level dependency chains from the boot activation queue (e.g. `matrix-traefik → matrix-container-socket-proxy → docker`). These services show as `inactive` or `failed` after reboot even though they are enabled. The boot-fix service scans for any enabled `matrix-*.service` in either state and starts them automatically.
+
+    > **If you previously configured a Task Scheduler entry** (`Control Panel > Task Scheduler`) to run `mount --make-shared /volume1` at boot-up, you can remove it — the boot-fix service now handles this.
+
+## Synology GUI Preparation
+
+1. **Enable SSH**
+   - `Control Panel` > `Terminal & SNMP` > `Enable SSH service`
+
+2. **Enable SFTP**
+   - `Control Panel` > `File Service` > `FTP` > `Enable SFTP service` with default port
+
+3. **Enable User Home Directory**
+   - `Control Panel` > `User & Group` > `Advanced` > `Enable user home service`
+
+4. **Install Container Manager**
+   - Install from `Package Center`
+
+5. **Configure Reverse Proxy**
+   - `Control Panel` > `Login Portal` > `Advanced` > `Reverse Proxy`
+   - Create entries for each service you enable (e.g. Matrix, Element, admin page)
+   - Example entry:
+     - Source: `HTTPS` / `matrix.example.com` / port `443`
+     - Destination: `HTTP` / `localhost` / port `81`
+
+## SSH Preparation
+
+### (Optional but Recommended) Enable SSH Key Authentication
+
+Configure key-based SSH login to avoid password prompts during Ansible runs.
+
+### Set Up the Ansible Environment
+
+Create a project folder and Python virtual environment on the DSM host:
+
+```shell
+mkdir ~/path/to/your/project/folder
+cd ~/path/to/your/project/folder
+
+python3 -m venv ./myenv
+# (optional) activate python virtual environment
+# source ./myenv/bin/activate
+```
+
+## Inventory Configuration
+
+In your `inventory/hosts` file, set the Python interpreter to your virtual environment:
+
+```ini
+# SSH key authentication with empty passphrase example
+matrix.example.com ansible_host=<your-dsm-ip> ansible_ssh_user=<dsm-ssh-user> become=true become_user=root ansible_python_interpreter=/volume1/homes/path/to/your/project/folder/myenv/bin/python ansible_sudo_pass='your-password'
+```
+
+## vars.yml Configuration
+
+Add the following Synology-specific variables to your `vars.yml`:
+
+```yaml
+# Synology-specific settings
+
+# Controls Synology DSM-specific handling. `null` means autodetect (via /etc/synoinfo.conf).
+# Set to `true`/`false` to force.
+# matrix_base_host_is_synology: true
+
+# Password for the Matrix service account created by the playbook.
+# The account is created as expired so this password cannot be used to log in.
+matrix_synology_user_password: "your-strong-password"
+
+# User and group that will be created automatically by the playbook
+matrix_user_name: "matrix"
+matrix_group_name: "matrix"
+
+# Data path on your Synology volume
+matrix_base_data_path: "/volume1/docker/matrix"
+
+# Use Synology Container Manager's Docker daemon instead of installing Docker
+matrix_playbook_docker_installation_enabled: false
+devture_systemd_docker_base_host_command_docker: "/var/packages/ContainerManager/target/usr/bin/docker"
+devture_systemd_docker_base_docker_service_name: "pkg-ContainerManager-dockerd.service"
+
+# Use Synology's NTP service
+devture_timesync_ntpd_service: "chronyd"
+
+# Reverse proxy settings — use HTTPS at the DSM reverse proxy level
+matrix_playbook_ssl_enabled: true
+traefik_config_entrypoint_web_secure_enabled: false
+
+# Bind to localhost only — DSM reverse proxy handles public traffic
+traefik_container_web_host_bind_port: '127.0.0.1:81'
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: '127.0.0.1:8449'
+
+# Trust X-Forwarded-* headers from the local reverse proxy
+traefik_config_entrypoint_web_forwardedHeaders_insecure: true
+
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
+  forwardedHeaders:
+    insecure: true
+```
+
+## Running the Playbook
+
+```shell
+# Full setup
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
+
+# start
+ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+
+# Stop all services
+ansible-playbook -i inventory/hosts setup.yml --tags=stop
+
+# Apply config changes (always include start to restart running containers)
+ansible-playbook -i inventory/hosts setup.yml --tags=stop,setup-all,start
+```
+
+> **Important:** Always include `stop` before `setup-all,start` when changing configuration. Running `setup-all` alone does not restart already-running containers.
+
+## Creating Matrix Users
+
+After the services are running, create your first Matrix user:
+
+```shell
+# option 1:
+sudo docker exec -it matrix-synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -u your_username -p your_password
+
+# option 2:
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=your_username password=your_password admin=yes|no' --tags=register-user
+```

docs/configuring-playbook-traefik.md

@@ -25,16 +25,31 @@ traefik_config_accessLog_enabled: false
 
 ### Enable Traefik Dashboard
 
-To enable a Traefik [Dashboard](https://doc.traefik.io/traefik/operations/dashboard/) UI at `https://matrix.example.com/dashboard/` (note the trailing `/`), add the following configuration to your `vars.yml` file:
+To enable the Traefik [Dashboard](https://doc.traefik.io/traefik/operations/dashboard/) UI at `https://matrix.example.com/dashboard/` (note the trailing `/`), add the following configuration to your `vars.yml` file:
 
 ```yaml
 traefik_dashboard_enabled: true
 traefik_dashboard_hostname: "{{ matrix_server_fqn_matrix }}"
 traefik_dashboard_basicauth_enabled: true
-traefik_dashboard_basicauth_user: YOUR_USERNAME_HERE
-traefik_dashboard_basicauth_password: YOUR_PASSWORD_HERE
+traefik_dashboard_basicauth_htpasswd: "YOUR_USERNAME_HERE:$apr1$..."
 ```
 
+Choose a username and password for the dashboard, then generate the corresponding `htpasswd` entry with:
+
+```sh
+htpasswd -nb YOUR_USERNAME_HERE YOUR_PASSWORD_HERE
+```
+
+The command outputs the exact value to use for `traefik_dashboard_basicauth_htpasswd` — your username, a colon, and a hash of your chosen password:
+
+```text
+YOUR_USERNAME_HERE:$apr1$...
+```
+
+Copy the full output line into `traefik_dashboard_basicauth_htpasswd`. After deploying, log in to the dashboard using the same username and password that you chose earlier.
+
+The role also supports the legacy `traefik_dashboard_basicauth_user` / `traefik_dashboard_basicauth_password` convenience variables, but that path depends on the `passlib` Python library on the Ansible controller, may be affected by passlib/bcrypt compatibility issues, and generates non-deterministic hashes which can lead to unnecessary changes.
+
 > [!WARNING]
 > Enabling the dashboard on a hostname you use for something else (like `matrix_server_fqn_matrix` in the configuration above) may cause conflicts. Enabling the Traefik Dashboard makes Traefik capture all `/dashboard` and `/api` requests and forward them to itself. If any of the services hosted on the same hostname requires any of these 2 URL prefixes, you will experience problems. So far, we're not aware of any playbook services which occupy these endpoints and are likely to cause conflicts.
 

docs/configuring-playbook-turn.md

@@ -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-tuwunel.md

@@ -0,0 +1,269 @@
+<!--
+SPDX-FileCopyrightText: 2026 MDAD project contributors
+SPDX-FileCopyrightText: 2026 Jason Volk
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Configuring Tuwunel (optional)
+
+The playbook can install and configure the [Tuwunel](https://matrix-construct.github.io/tuwunel/) Matrix homeserver for you.
+
+Tuwunel is a featureful homeserver written entirely in Rust, intended as a scalable, low-cost, enterprise-ready alternative to Synapse that fully implements the [Matrix specification](https://spec.matrix.org/latest/) for all but the most niche uses. It is the official successor to [conduwuit](configuring-playbook-conduwuit.md), is now sponsored by the government of Switzerland 🇨🇭 (where it is currently deployed for citizens), and is used by a number of organisations with a vested interest in its continued development. See the project's [documentation](https://matrix-construct.github.io/tuwunel/) for further background.
+
+By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
+
+> [!WARNING]
+> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse → Tuwunel). Proceed below only if you're OK with starting over, or you're dealing with a server on a new domain name which hasn't participated in the Matrix federation yet. The one exception is migrating from conduwuit; see [Migrating from conduwuit](#migrating-from-conduwuit).
+> - **Homeserver implementations other than Synapse may not be fully functional** with every part of this playbook. Make yourself familiar with the trade-offs before proceeding.
+
+## Adjusting the playbook configuration
+
+To use Tuwunel, set the following on `inventory/host_vars/matrix.example.com/vars.yml`:
+
+```yaml
+matrix_homeserver_implementation: tuwunel
+
+# Open the registration endpoint long enough to create your first user.
+# After signing up, set this back to false.
+matrix_tuwunel_config_allow_registration: true
+
+# A registration token to protect the endpoint from abuse.
+# Generate one with `pwgen -s 64 1` or similar.
+matrix_tuwunel_config_registration_token: ''
+```
+
+The first user account that registers becomes a server admin and is automatically invited to the admin room. See [Creating the first user account](#creating-the-first-user-account) below for the bootstrap procedure.
+
+## Wiring done for you
+
+When `matrix_homeserver_implementation: tuwunel` is set, the playbook automatically integrates Tuwunel with the rest of your stack:
+
+- **Federation.** Toggled by `matrix_homeserver_federation_enabled`. The federation virtual host (port 8448 in the default setup) is wired up via Traefik labels.
+- **Well-known.** `matrix_tuwunel_config_well_known_client` is set to your public homeserver URL whenever SSL is enabled. Matrix clients use this for delegated-domain server discovery; identity-provider entries below can also omit their `callback_url`, since Tuwunel derives `<well-known>/_matrix/client/unstable/login/sso/callback/<client_id>` automatically.
+- **Element Call / MatrixRTC.** When the [LiveKit JWT service](configuring-playbook-matrix-rtc.md) is enabled, Tuwunel publishes its public URL through `.well-known/matrix/client` per [MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143).
+- **Legacy calls (TURN).** When [Coturn](configuring-playbook-turn.md) is enabled, its URIs and shared secret (or username/password, depending on `coturn_authentication_method`) are wired automatically.
+
+## Extending the configuration
+
+Tuwunel exposes a large configuration surface. The role surfaces commonly used options as Ansible variables under `matrix_tuwunel_config_*`. See [`roles/custom/matrix-tuwunel/defaults/main.yml`](../roles/custom/matrix-tuwunel/defaults/main.yml) for the complete list, and [`roles/custom/matrix-tuwunel/templates/tuwunel.toml.j2`](../roles/custom/matrix-tuwunel/templates/tuwunel.toml.j2) for the rendered configuration.
+
+For options that aren't surfaced as a dedicated variable, [environment variables](https://matrix-construct.github.io/tuwunel/configuration.html#environment-variables) are the recommended override mechanism. They take priority over the rendered TOML, are scoped to the running container, and require no template patching:
+
+```yaml
+matrix_tuwunel_environment_variables_extension: |
+  TUWUNEL_REQUEST_TIMEOUT=60
+  TUWUNEL_DNS_CACHE_SIZE=131072
+```
+
+Keys nested under a TOML section use `__` (double underscore) to descend, e.g. `TUWUNEL_WELL_KNOWN__SERVER`. User-named sections become path segments too: `TUWUNEL_STORAGE_PROVIDER__ARCHIVE__S3__URL` overrides the `url` field of the `archive` storage provider in the example below.
+
+If you need wholesale control of the configuration file, copy [`roles/custom/matrix-tuwunel/templates/tuwunel.toml.j2`](../roles/custom/matrix-tuwunel/templates/tuwunel.toml.j2) into your inventory and point `matrix_tuwunel_template_tuwunel_config` at your copy.
+
+The container image published as `:latest` is built with `io_uring`, `jemalloc`, LDAP, blurhashing, URL preview, sentry telemetry, and zstd compression all enabled, so most opt-in features are simply a configuration toggle away.
+
+### Identity providers (OAuth2 / OIDC)
+
+Configure one or more `[[global.identity_provider]]` entries via a list. Each entry maps directly to Tuwunel's [identity-provider fields](https://matrix-construct.github.io/tuwunel/authentication/providers.html); only the fields you set are emitted. GitHub, GitLab, and Google have built-in `issuer_url` defaults so a `client_id` plus `client_secret` is enough; for any other `brand` (Apple, Facebook, Keycloak, MAS, Twitter, etc.) you must supply `issuer_url` explicitly:
+
+```yaml
+matrix_tuwunel_config_identity_providers:
+  - brand: keycloak
+    client_id: matrix
+    client_secret: '<provider secret>'
+    issuer_url: https://sso.example.com/realms/matrix
+    callback_url: https://matrix.example.com/_matrix/client/unstable/login/sso/callback/matrix
+    trusted: true
+  - brand: github
+    client_id: '<github oauth app id>'
+    client_secret: '<github oauth app secret>'
+```
+
+Self-hosted providers must supply both `client_id` and `issuer_url`. Set `trusted: true` only on providers you operate yourself; trusting a public provider (GitHub, Google, etc.) is an account-takeover risk.
+
+### LDAP
+
+Tuwunel can authenticate `m.login.password` requests against an LDAP directory and, in search-then-bind mode, keep admin status in sync with directory membership. The shipped image already includes the `ldap` build feature.
+
+```yaml
+matrix_tuwunel_config_ldap_enabled: true
+matrix_tuwunel_config_ldap_uri: ldaps://ldap.example.com:636
+matrix_tuwunel_config_ldap_base_dn: ou=users,dc=example,dc=org
+matrix_tuwunel_config_ldap_bind_dn: cn=ldap-reader,dc=example,dc=org
+matrix_tuwunel_config_ldap_bind_password_file: /etc/tuwunel/ldap.pw
+matrix_tuwunel_config_ldap_filter: '(&(objectClass=person)(memberOf=cn=matrix,ou=groups,dc=example,dc=org))'
+```
+
+> [!NOTE]
+> `bind_password_file` is read **inside the container**. The role bind-mounts `/matrix/tuwunel/config` to `/etc/tuwunel` (read-only) and `/matrix/tuwunel/data` to `/var/lib/tuwunel`. To make the file available at the path above, drop it on the host at `/matrix/tuwunel/config/ldap.pw` (owned by `matrix:matrix`) before running the playbook; the role does not template secret files for you.
+
+For direct-bind, anonymous-search, and admin-sync details, see [LDAP authentication](https://matrix-construct.github.io/tuwunel/authentication/ldap.html).
+
+### JWT login
+
+Tuwunel can accept signed JSON Web Tokens both as a login flow and as a User-Interactive Authentication step:
+
+```yaml
+matrix_tuwunel_config_jwt_enabled: true
+matrix_tuwunel_config_jwt_key: '<shared secret>'
+matrix_tuwunel_config_jwt_format: HMAC          # one of HMAC, B64HMAC, ECDSA, EDDSA
+matrix_tuwunel_config_jwt_algorithm: HS256
+matrix_tuwunel_config_jwt_audience: ['matrix']
+matrix_tuwunel_config_jwt_issuer: ['https://issuer.example.com']
+```
+
+The defaults match Synapse's `experimental_features.jwt_config` semantics, so a key + algorithm port should authenticate the same set of tokens. See [Enterprise JWT](https://matrix-construct.github.io/tuwunel/authentication/jwt.html) for the full reference, including the asymmetric (ECDSA / EdDSA) formats and the operator-controlled UIAA override flow.
+
+### Media storage providers
+
+Each entry becomes a `[global.storage_provider.<id>.<kind>]` block. `kind` is `local` or `s3`; the remaining keys map directly to the fields documented in [Storage providers](https://matrix-construct.github.io/tuwunel/media/storage.html):
+
+```yaml
+matrix_tuwunel_config_storage_providers:
+  - id: primary
+    kind: local
+    base_path: /var/lib/tuwunel/media
+
+  - id: archive
+    kind: s3
+    url: s3://my-bucket/media
+    region: us-east-1
+    key: AKIA...
+    secret: '<aws secret>'
+    multipart_threshold: 100 MiB
+```
+
+The S3 backend ships with native multipart upload, so no goofys/rclone sidecar is required. MinIO, Cloudflare R2, and DigitalOcean Spaces all work; set `endpoint` and `use_vhost_request: false` as appropriate.
+
+> [!NOTE]
+> Local provider paths must live under `/var/lib/tuwunel` (the container's data mount, persisted on the host at `/matrix/tuwunel/data`), or you must mount the target directory into the container yourself via `matrix_tuwunel_container_extra_arguments`. The container otherwise runs read-only.
+
+### RocksDB and cache tuning
+
+Tuwunel embeds RocksDB. The defaults (`rocksdb_compression_algo: zstd`) suit most deployments. For high-throughput servers you may want to enable direct I/O, raise parallelism, and configure a backup path:
+
+```yaml
+matrix_tuwunel_config_rocksdb_direct_io: true
+matrix_tuwunel_config_rocksdb_parallelism_threads: 8
+matrix_tuwunel_config_database_backup_path: /var/lib/tuwunel/backups
+```
+
+`matrix_tuwunel_config_cache_capacity_modifier` is left empty by default, so Tuwunel picks a value (`1.0` since v1.7.0, with rebalanced per-cache sizes that already raise memory use). Set it to `2.0` only on small hosts with four or fewer cores; on larger machines the default is recommended.
+
+If you run on ZFS, the [Tuwunel maintenance guide](https://matrix-construct.github.io/tuwunel/maintenance.html#zfs) lists the dataset properties (`recordsize`, `primarycache`, `compression`, `atime`, `logbias`) and config flags (`rocksdb_direct_io`, `rocksdb_allow_fallocate`) you need to adjust to avoid severe write amplification.
+
+To enable Sentry crash reporting, set `matrix_tuwunel_config_sentry_enabled: true`.
+
+### Federation gating
+
+Tuwunel accepts regular-expression patterns at every level of remote-server filtering:
+
+```yaml
+matrix_tuwunel_config_forbidden_remote_server_names:
+  - 'bad\.example\.com$'
+matrix_tuwunel_config_forbidden_remote_room_directory_server_names:
+  - 'spam\.example\.com$'
+matrix_tuwunel_config_prevent_media_downloads_from:
+  - 'heavy\.example\.com$'
+```
+
+Tuwunel additionally implements [MSC4284 policy servers](https://github.com/matrix-org/matrix-spec-proposals/pull/4284) for room-level federation gating. The policy itself lives in room state, but enforcement is opt-in at the server level:
+
+```yaml
+matrix_tuwunel_config_enable_policy_servers: true
+matrix_tuwunel_config_policy_server_request_timeout: 5
+```
+
+When enabled, rooms with a valid `m.room.policy` state event have outgoing events signed by the configured policy server before federation. Transient network or timeout failures fail open (with a warn log), so a policy-server outage will not silently take the room offline.
+
+### Default room version
+
+The role sets `default_room_version: '12'`, so newly created rooms default to Matrix [room version 12](https://github.com/matrix-org/matrix-spec-proposals/pull/4289) ("Hydra"). Override `matrix_tuwunel_config_default_room_version` if you need an earlier version for client compatibility.
+
+### The `/_tuwunel` API path
+
+Besides `/_matrix`, Tuwunel serves its own first-party routes under `/_tuwunel`. This namespace carries ad-hoc endpoints such as `/_tuwunel/server_version` and `/_tuwunel/local_user_count`, and the [native OpenID Connect provider](https://matrix-construct.github.io/tuwunel/authentication/oidc-server.html) endpoints (`/_tuwunel/oidc/...`) that clients use when Tuwunel handles OIDC login itself, rather than delegating to an upstream provider as described above. The role routes `/_tuwunel` on the public entrypoint by default so these features work out of the box.
+
+To keep this namespace off the public entrypoint and expose it only on the internal one, set:
+
+```yaml
+matrix_tuwunel_container_labels_public_tuwunel_api_enabled: false
+matrix_tuwunel_container_labels_internal_tuwunel_api_enabled: true
+```
+
+### Exposing the Administration API
+
+Tuwunel serves a Synapse-compatible Administration API under the `/_synapse/admin` path, so administration dashboards (such as synapse-admin and ketesa) and moderation bots (such as Draupnir and Meowlnir) work against it. The served endpoints are listed on the [Tuwunel Synapse Admin API page](https://matrix-construct.github.io/tuwunel/development/compliance/synapse-admin.html).
+
+The API is not routed through the reverse proxy by default. Every endpoint requires an administrator access token, but you may still prefer to keep it off the public entrypoint. To reach it only from trusted networks, expose it on the internal Traefik entrypoint:
+
+```yaml
+matrix_tuwunel_container_labels_internal_client_synapse_admin_api_enabled: true
+```
+
+To expose it publicly instead (for example, when a dashboard runs in the browser), set:
+
+```yaml
+matrix_tuwunel_container_labels_public_client_synapse_admin_api_enabled: true
+```
+
+## Creating the first user account
+
+Unlike Synapse and Dendrite, Tuwunel does not register users from the command line or via the playbook. On first startup it logs a one-time-use registration token to its journal:
+
+```sh
+# Adjust the duration if necessary or remove the --since argument.
+journalctl -u matrix-tuwunel.service --since="10 minutes ago"
+```
+
+Use the token to create your first account from any client that supports token-gated registration (e.g. [Element Web](configuring-playbook-client-element-web.md)). The account is auto-promoted to admin and invited to the admin room together with the `@conduit:<server_name>` server bot. The bot keeps the legacy `conduit` localpart due to the project's lineage from Conduit.
+
+## Configuring bridges and appservices
+
+The playbook does not auto-register appservices for Tuwunel. After your bridge has produced its `registration.yaml` (e.g. `/matrix/mautrix-signal/bridge/registration.yaml`), register it manually by sending the contents to the admin room, prefixed with `!admin appservices register` and wrapped in a fenced code block:
+
+    !admin appservices register
+    ```
+    id: signal
+    url: http://matrix-mautrix-signal:29328
+    as_token: <token>
+    hs_token: <token>
+    sender_localpart: _bot_signalbot
+    rate_limited: false
+    namespaces:
+      users:
+        - exclusive: true
+          regex: '^@signal_.+:example\.org$'
+        - exclusive: true
+          regex: '^@signalbot:example\.org$'
+      aliases:
+        - exclusive: true
+          regex: '^#signal_.+:example\.org$'
+    ```
+
+Registrations stored this way are persisted in the database and survive restarts. Re-running the command with the same `id` replaces the existing entry. See [Application services](https://matrix-construct.github.io/tuwunel/appservices.html) for the full reference and admin commands.
+
+## Migrating from conduwuit
+
+Tuwunel is a "binary swap" for conduwuit; it reads conduwuit's RocksDB layout directly, so migration is a data move, not an export/import.
+
+1. Set `matrix_homeserver_implementation: tuwunel` on `vars.yml` and remove any `matrix_conduwuit_*` overrides.
+2. Run a full installation so that the new service is created and the old one removed (e.g. `just setup-all`).
+3. Run `just run-tags tuwunel-migrate-from-conduwuit`.
+
+The migration stops `matrix-conduwuit.service`, copies `/matrix/conduwuit` into `/matrix/tuwunel`, renames the config file, and starts `matrix-tuwunel.service`. The freshly generated tuwunel data directory is preserved alongside as `/matrix/tuwunel_old` until you remove it manually.
+
+> [!CAUTION]
+> Migrating from any other Conduit derivative (Conduit itself, Continuwuity, or any other fork) is **not supported** and will corrupt your database. All Conduit forks share the same linear database version with no awareness of each other; switching between them produces unrecoverable damage. See the [upstream migration table](https://matrix-construct.github.io/tuwunel/#migrating-to-tuwunel).
+
+## Troubleshooting
+
+As with all other services, the logs are available via [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html):
+
+```sh
+journalctl -fu matrix-tuwunel
+```
+
+Logging verbosity is controlled by `matrix_tuwunel_config_log` in [`tracing-subscriber` env-filter syntax](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html). The default (`info,state_res=warn`) is reasonable for production; for debugging, try `debug` or scope it tighter, e.g. `info,tuwunel_service::sending=debug`.
+
+For RocksDB-level issues, online backups, and offline backup procedures, see the [Tuwunel maintenance guide](https://matrix-construct.github.io/tuwunel/maintenance.html). For protocol-compliance state across MSCs, the spec, and Complement, the project's [compliance dashboard](https://matrix-construct.github.io/tuwunel/development/compliance.html) is the authoritative tracker.

docs/configuring-playbook.md

@@ -53,6 +53,8 @@ For a more custom setup, see the [Other configuration options](#other-configurat
 
   - [Configuring continuwuity](configuring-playbook-continuwuity.md), if you've switched to the [continuwuity](https://continuwuity.org) homeserver implementation
 
+  - [Configuring Tuwunel](configuring-playbook-tuwunel.md), if you've switched to the [Tuwunel](https://matrix-construct.github.io/tuwunel/) homeserver implementation
+
   - [Configuring Dendrite](configuring-playbook-dendrite.md), if you've switched to the [Dendrite](https://matrix-org.github.io/dendrite) homeserver implementation
 
 - Server components:
@@ -87,10 +89,14 @@ 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/SableClient/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/)
 
+- [Setting up Commet](configuring-playbook-client-commet.md), if you've enabled [Commet](https://github.com/commetchat/commet), a Matrix web client
+
 
 ### Authentication and user-related
 
@@ -100,9 +106,7 @@ Extend and modify how users are authenticated on your homeserver.
 
 - [Setting up Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md)
 
-- [Setting up Synapse Admin](configuring-playbook-synapse-admin.md)
-
-- [Setting up matrix-registration](configuring-playbook-matrix-registration.md)
+- [Setting up Ketesa](configuring-playbook-ketesa.md)
 
 - [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (advanced)
 
@@ -110,8 +114,6 @@ Extend and modify how users are authenticated on your homeserver.
 
 - [Setting up the LDAP authentication password provider module](configuring-playbook-ldap-auth.md) (advanced)
 
-- [Setting up matrix-ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md) (advanced)
-
 - [Setting up Synapse Simple Antispam](configuring-playbook-synapse-simple-antispam.md) (advanced)
 
 - [Setting up Matrix User Verification Service](configuring-playbook-user-verification-service.md) (advanced)
@@ -144,6 +146,10 @@ Bridges can be used to connect your Matrix installation with third-party communi
 
 - [Setting up Mautrix Google Messages bridging](configuring-playbook-bridge-mautrix-gmessages.md)
 
+- [Setting up Mautrix Google Voice bridging](configuring-playbook-bridge-mautrix-gvoice.md)
+
+- [Setting up Mautrix LinkedIn bridging](configuring-playbook-bridge-mautrix-linkedin.md)
+
 - [Setting up Mautrix Whatsapp bridging](configuring-playbook-bridge-mautrix-whatsapp.md)
 
 - [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md)
@@ -158,13 +164,13 @@ Bridges can be used to connect your Matrix installation with third-party communi
 
 - [Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage](configuring-playbook-bridge-mautrix-wsproxy.md)
 
+- [Setting up RustPush (iMessage) bridging](configuring-playbook-bridge-rustpush.md)
+
 - [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md)
 
 - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md)
 
-- [Setting up Appservice Kakaotalk bridging](configuring-playbook-bridge-appservice-kakaotalk.md)
-
-- [Setting up Beeper LinkedIn bridging](configuring-playbook-bridge-beeper-linkedin.md)
+- [Setting up Beeper LINE bridging](configuring-playbook-bridge-beeper-line.md)
 
 - [Setting up matrix-hookshot](configuring-playbook-bridge-hookshot.md) — a bridge between Matrix and multiple project management services, such as [GitHub](https://github.com), [GitLab](https://about.gitlab.com) and [JIRA](https://www.atlassian.com/software/jira).
 
@@ -180,18 +186,18 @@ Bridges can be used to connect your Matrix installation with third-party communi
 
 - [Setting up Heisenbridge bouncer-style IRC bridging](configuring-playbook-bridge-heisenbridge.md)
 
+- [Setting up a Matrix <-> Meshtastic bridge](configuring-playbook-bridge-meshtastic-relay.md)
+
 - [Setting up WeChat bridging](configuring-playbook-bridge-wechat.md)
 
 ### Bots
 
 Bots provide various additional functionality to your installation.
 
-- [Setting up baibot](configuring-playbook-bot-baibot.md) — a bot through which you can talk to various [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) services ([OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) and [others](https://github.com/etkecc/baibot/blob/main/docs/providers.md))
+- [Setting up baibot](configuring-playbook-bot-baibot.md) — a bot through which you can talk to various [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) services (the privacy-first [Venice](configuring-playbook-bot-baibot.md#venice) we recommend, [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/), and [others](https://github.com/etkecc/baibot/blob/main/docs/providers.md))
 
 - [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) — a bot to remind you about stuff
 
-- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) — a bot to create and manage registration tokens to invite users
-
 - [Setting up maubot](configuring-playbook-bot-maubot.md) — a plugin-based Matrix bot system
 
 - [Setting up Honoroit](configuring-playbook-bot-honoroit.md) — a helpdesk bot
@@ -202,6 +208,8 @@ Bots provide various additional functionality to your installation.
 
 - [Setting up Draupnir for all/D4A](configuring-playbook-appservice-draupnir-for-all.md) — like the [Draupnir bot](configuring-playbook-bot-draupnir.md) mentioned above, but running in appservice mode and supporting multiple instances
 
+- [Setting up Meowlnir](configuring-playbook-bot-meowlnir.md) — a moderation tool/bot which speaks the same policy list protocol as Draupnir and Mjolnir, but runs in appservice mode and can override policies coming from lists you do not control
+
 - [Setting up Buscarron](configuring-playbook-bot-buscarron.md) — a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room
 
 ### Administration
@@ -259,10 +267,14 @@ Various services that don't fit any other categories.
 
 - [Setting up the Sliding Sync proxy](configuring-playbook-sliding-sync-proxy.md) for clients which require Sliding Sync support (like old Element X versions, before it got switched to Simplified Sliding Sync)
 
+- [Setting up Appservice Kakaotalk bridging](configuring-playbook-bridge-appservice-kakaotalk.md) (removed; the upstream repository has become unreachable and the component could only be installed by self-building it)
+
 - [Setting up Appservice Slack bridging](configuring-playbook-bridge-appservice-slack.md) (removed; this component has been discontinued)
 
 - [Setting up Appservice Webhooks bridging](configuring-playbook-bridge-appservice-webhooks.md) (deprecated; the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be [installed using this playbook](configuring-playbook-bridge-hookshot.md))
 
+- [Setting up Beeper LinkedIn bridging](configuring-playbook-bridge-beeper-linkedin.md) (unmaintained; the [upstream repository](https://github.com/beeper/linkedin) has been archived. Consider [setting up Mautrix LinkedIn bridging](configuring-playbook-bridge-mautrix-linkedin.md))
+
 - [Setting up the Dimension integration manager](configuring-playbook-dimension.md) ([unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299); after [installing](installing.md))
 
 - [Setting up Email2Matrix](configuring-playbook-email2matrix.md) (removed; the author suggests taking a look at [Postmoogle](https://github.com/etkecc/postmoogle) as a replacement, which can also be [installed using this playbook](configuring-playbook-bridge-postmoogle.md))
@@ -275,6 +287,12 @@ Various services that don't fit any other categories.
 
 - [Setting up matrix-bot-chatgpt](configuring-playbook-bot-chatgpt.md) (unmaintained; the bridge's author suggests taking a look at [baibot](https://github.com/etkecc/baibot) as a replacement, which can also be [installed using this playbook](configuring-playbook-bot-baibot.md))
 
+- [Setting up matrix-ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md) (removed; the repository of the source code has been removed)
+
+- [Setting up matrix-registration](configuring-playbook-matrix-registration.md) (removed; this component has been unmaintained)
+
+- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) (removed; this component has been unmaintained)
+
 - [Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md) (deprecated in favor of the Messenger/Instagram bridge with [mautrix-meta-messenger](configuring-playbook-bridge-mautrix-meta-messenger.md))
 
 - [Setting up Mautrix Instagram bridging](configuring-playbook-bridge-mautrix-instagram.md) (deprecated in favor of the Messenger/Instagram bridge with [mautrix-meta-instagram](configuring-playbook-bridge-mautrix-meta-instagram.md))

docs/configuring-well-known.md

@@ -104,6 +104,14 @@ All you need to do is:
 
 - set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Element Web) may fail to work. Setting up headers for the `/.well-known/matrix/server` file is not necessary, as this file is only consumed by non-browsers, which don't care about CORS.
 
+- make sure the files are served with a `Content-Type: application/json` HTTP header. You can verify this by running `curl -i https://example.com/.well-known/matrix/client`. Some web servers serve extensionless files as plain text or even offer them as downloads, which breaks stricter clients such as Element X ([manifesting as errors like `MISSING_MATRIX_RTC_FOCUS`](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/4763)). On Apache-based hosting, you can force the correct content type by placing an `.htaccess` file next to the files:
+
+  ```apache
+  <FilesMatch "^(client|server|support)$">
+      ForceType application/json
+  </FilesMatch>
+  ```
+
 This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server. It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known files and you may need to notice that and copy them over again.
 
 #### (Option 2): **Setting up reverse-proxying** of the well-known files from the base domain's server to the Matrix server
@@ -112,7 +120,9 @@ This option is less fragile and generally better.
 
 On the base domain's server (e.g. `example.com`), you can set up reverse-proxying (or simply a 302 redirect), so that any access for the `/.well-known/matrix` location prefix is forwarded to the Matrix domain's server (e.g. `matrix.example.com`).
 
-With this method, you **don't need** to add special HTTP headers for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) reasons (like `Access-Control-Allow-Origin`), because your Matrix server (where requests ultimately go) will be configured by this playbook correctly.
+With reverse-proxying, you **don't need** to add special HTTP headers for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) reasons (like `Access-Control-Allow-Origin`), because your Matrix server (where requests ultimately go) will be configured by this playbook correctly.
+
+If you use a 302 redirect instead, be aware that browsers apply CORS checks to every response in the redirect chain, so the redirect response itself must also carry an `Access-Control-Allow-Origin: *` header. Otherwise, web-based Matrix clients (like Element Web) may fail to work even though the final destination sets the header correctly.
 
 **For nginx**, it would be something like this:
 
@@ -155,6 +165,23 @@ example.com {
 }
 ```
 
+**Note**: Caddy does not process directives in the order they appear in the Caddyfile, but according to its own [directive order](https://caddyserver.com/docs/caddyfile/directives#directive-order). Notably, `redir` is evaluated before `reverse_proxy`, so a `redir` elsewhere in the same site block (a common way to send the base domain to `www.example.com` or to another site) takes precedence and breaks the well-known reverse-proxying. In such cases, wrap the directives in [`handle`](https://caddyserver.com/docs/caddyfile/directives/handle) blocks to enforce the intended priority:
+
+```caddy
+example.com {
+	handle /.well-known/matrix/* {
+		reverse_proxy https://matrix.example.com {
+			header_up Host {upstream_hostport}
+		}
+	}
+
+	handle {
+		# Everything else, e.g. a redirect to some other site
+		redir https://www.example.com{uri}
+	}
+}
+```
+
 **For HAProxy**, it would be something like this:
 
 ```haproxy

docs/container-images.md

@@ -28,6 +28,7 @@ We try to stick to official images (provided by their respective projects) as mu
 | [Synapse](configuring-playbook-synapse.md) | [element-hq/synapse](https://ghcr.io/element-hq/synapse) | ✅ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network |
 | [Conduit](configuring-playbook-conduit.md) | [matrixconduit/matrix-conduit](https://hub.docker.com/r/matrixconduit/matrix-conduit) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements |
 | [continuwuity](configuring-playbook-continuwuity.md) | [continuwuation/continuwuity](https://forgejo.ellis.link/continuwuation/continuwuity) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. continuwuity is a continuation of conduwuit. |
+| [Tuwunel](configuring-playbook-tuwunel.md) | [matrix-construct/tuwunel](https://ghcr.io/matrix-construct/tuwunel) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Tuwunel is the official successor to conduwuit. |
 | [Dendrite](configuring-playbook-dendrite.md) | [matrixdotorg/dendrite-monolith](https://hub.docker.com/r/matrixdotorg/dendrite-monolith/) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse. |
 
 ## Clients
@@ -39,6 +40,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
@@ -65,8 +67,6 @@ Extend and modify how users are authenticated on your homeserver.
 | [matrix-synapse-rest-auth](configuring-playbook-rest-auth.md) | (N/A) | ❌ | REST authentication password provider module |
 | [matrix-synapse-shared-secret-auth](configuring-playbook-shared-secret-auth.md) | (N/A) | ❌ | Password provider module |
 | [matrix-synapse-ldap3](configuring-playbook-ldap-auth.md) (advanced) | (N/A) | ❌ | LDAP Auth password provider module |
-| [matrix-ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md) | [activism.international/matrix_ldap_registration_proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy/container_registry) | ❌ | Proxy that handles Matrix registration requests and forwards them to LDAP |
-| [matrix-registration](configuring-playbook-matrix-registration.md) | [zeratax/matrix-registration](https://hub.docker.com/r/devture/zeratax-matrix-registration/) | ❌ | Simple python application to have a token based Matrix registration |
 | [Matrix User Verification Service](configuring-playbook-user-verification-service.md) | [matrixdotorg/matrix-user-verification-service](https://hub.docker.com/r/atrixdotorg/matrix-user-verification-service) | ❌ | Service to verify details of a user based on an Open ID token |
 | [synapse-simple-antispam](configuring-playbook-synapse-simple-antispam.md) (advanced) | (N/A) | ❌ | Spam checker module |
 
@@ -91,6 +91,8 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) | [mautrix/slack](https://mau.dev/mautrix/slack/container_registry) | ❌ | Bridge to [Slack](https://slack.com/) |
 | [mautrix-telegram](configuring-playbook-bridge-mautrix-telegram.md) | [mautrix/telegram](https://mau.dev/mautrix/telegram/container_registry) | ❌ | Bridge to [Telegram](https://telegram.org/) |
 | [mautrix-gmessages](configuring-playbook-bridge-mautrix-gmessages.md) | [mautrix/gmessages](https://mau.dev/mautrix/gmessages/container_registry) | ❌ | Bridge to [Google Messages](https://messages.google.com/) |
+| [mautrix-gvoice](configuring-playbook-bridge-mautrix-gvoice.md) | [mautrix/gvoice](https://mau.dev/mautrix/gvoice/container_registry) | ❌ | Bridge to [Google Voice](https://voice.google.com/) |
+| [mautrix-linkedin](configuring-playbook-bridge-mautrix-linkedin.md) | [mautrix/linkedin](https://mau.dev/mautrix/linkedin/container_registry) | ❌ | Bridge to [LinkedIn](https://www.linkedin.com/) |
 | [mautrix-whatsapp](configuring-playbook-bridge-mautrix-whatsapp.md) | [mautrix/whatsapp](https://mau.dev/mautrix/whatsapp/container_registry) | ❌ | Bridge to [WhatsApp](https://www.whatsapp.com/) |
 | [mautrix-wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) | [mautrix/wsproxy](https://mau.dev/mautrix/wsproxy/container_registry) | ❌ | Bridge to Android SMS or Apple iMessage |
 | [mautrix-twitter](configuring-playbook-bridge-mautrix-twitter.md) | [mautrix/twitter](https://mau.dev/mautrix/twitter/container_registry) | ❌ | Bridge to [Twitter](https://twitter.com/) |
@@ -98,8 +100,8 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | mautrix-meta (for [Messenger](configuring-playbook-bridge-mautrix-meta-messenger.md) and [Instagram](configuring-playbook-bridge-mautrix-meta-instagram.md)) | [mautrix/meta](https://mau.dev/mautrix/meta/container_registry) | ❌ | Bridge to [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) |
 | [mautrix-signal](configuring-playbook-bridge-mautrix-signal.md) | [mautrix/signal](https://mau.dev/mautrix/signal/container_registry) | ❌ | Bridge to [Signal](https://www.signal.org/) |
 | [beeper-linkedin](configuring-playbook-bridge-beeper-linkedin.md) | [beeper/linkedin](https://ghcr.io/beeper/linkedin) | ❌ | Bridge to [LinkedIn](https://www.linkedin.com/) |
+| [beeper-line](configuring-playbook-bridge-beeper-line.md) | [crispyduck/beeper-line](https://hub.docker.com/r/crispyduck/beeper-line) | ❌ | Bridge to [LINE](https://line.me/) |
 | [matrix-appservice-irc](configuring-playbook-bridge-appservice-irc.md) | [matrixdotorg/matrix-appservice-irc](https://hub.docker.com/r/matrixdotorg/matrix-appservice-irc) | ❌ | Bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) |
-| [matrix-appservice-kakaotalk](configuring-playbook-bridge-appservice-kakaotalk.md) | Self-building | ❌ | Bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) |
 | [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) | [matrix-org/matrix-appservice-discord](https://ghcr.io/matrix-org/matrix-appservice-discord) | ❌ | Bridge to [Discord](https://discordapp.com/) |
 | [matrix-hookshot](configuring-playbook-bridge-hookshot.md) | [halfshot/matrix-hookshot](https://hub.docker.com/r/halfshot/matrix-hookshot) | ❌ | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular |
 | [matrix-sms-bridge](configuring-playbook-bridge-matrix-bridge-sms.md) | [folivonet/matrix-sms-bridge](https://hub.docker.com/repository/docker/folivonet/matrix-sms-bridge) | ❌ | Bridge to SMS |
@@ -107,6 +109,7 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [Heisenbridge](configuring-playbook-bridge-heisenbridge.md) | [hif1/heisenbridge](https://hub.docker.com/r/hif1/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) |
 | [mx-puppet-groupme](configuring-playbook-bridge-mx-puppet-groupme.md) | [xangelix/mx-puppet-groupme](https://hub.docker.com/r/xangelix/mx-puppet-groupme) | ❌ | Bridge to [GroupMe](https://groupme.com/) |
 | [matrix-steam-bridge](configuring-playbook-bridge-steam.md) | [jasonlaguidice/matrix-steam-bridge](https://github.com/jasonlaguidice/matrix-steam-bridge/pkgs/container/matrix-steam-bridge) | ❌ | Bridge to [Steam](https://steampowered.com/) |
+| [matrix-rustpush-bridge](configuring-playbook-bridge-rustpush.md) | [jasonlaguidice/imessage](https://github.com/jasonlaguidice/imessage/pkgs/container/imessage) | ❌ | Bridge to [iMessage](https://support.apple.com/messages) via Apple Push Notification service |
 | [mx-puppet-steam](configuring-playbook-bridge-mx-puppet-steam.md) | [icewind1991/mx-puppet-steam](https://hub.docker.com/r/icewind1991/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) |
 | [Postmoogle](configuring-playbook-bridge-postmoogle.md) | [etke.cc/postmoogle](https://github.com/etkecc/postmoogle/container_registry) | ❌ | Email to Matrix bridge |
 
@@ -118,11 +121,11 @@ Bots provide various additional functionality to your installation.
 | ------- | --------------- | -------- | ----------- |
 | [baibot](configuring-playbook-bot-baibot.md) | [etke.cc/baibot](https://ghcr.io/etkecc/baibot) | ❌ | Bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you |
 | [matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) | [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) | ❌ | Bot for scheduling one-off & recurring reminders and alarms |
-| [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) | [moanos/matrix-registration-bot](https://hub.docker.com/r/moanos/matrix-registration-bot/) | ❌ | Bot for invitations by creating and managing registration tokens |
 | [maubot](configuring-playbook-bot-maubot.md) | [dock.mau.dev/maubot/maubot](https://mau.dev/maubot/maubot/container_registry) | ❌ | Plugin-based Matrix bot system |
 | [Honoroit](configuring-playbook-bot-honoroit.md) | [etke.cc/honoroit](https://github.com/etkecc/honoroit/container_registry) | ❌ | Helpdesk bot |
 | [Mjolnir](configuring-playbook-bot-mjolnir.md) | [matrixdotorg/mjolnir](https://hub.docker.com/r/matrixdotorg/mjolnir) | ❌ | Moderation tool for Matrix |
 | [Draupnir](configuring-playbook-bot-draupnir.md) | [gnuxie/draupnir](https://hub.docker.com/r/gnuxie/draupnir) | ❌ | Moderation tool for Matrix (Fork of Mjolnir) |
+| [Meowlnir](configuring-playbook-bot-meowlnir.md) | [maunium/meowlnir](https://mau.dev/maunium/meowlnir/container_registry) | ❌ | Moderation tool for Matrix, running in appservice mode |
 | [Buscarron](configuring-playbook-bot-buscarron.md) | [etke.cc/buscarron](https://ghcr.io/etkecc/buscarron) | ❌ | Web forms (HTTP POST) to Matrix |
 
 ## Administration
@@ -133,7 +136,7 @@ Services that help you in administrating and monitoring your Matrix installation
 | ------- | --------------- | -------- | ----------- |
 | [matrix-alertmanager-receiver](configuring-playbook-alertmanager-receiver.md) | [metio/matrix-alertmanager-receiver](https://hub.docker.com/r/metio/matrix-alertmanager-receiver)  | ❌ | Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) client |
 | [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) | [element-hq/matrix-authentication-service](https://ghcr.io/element-hq/matrix-authentication-service) | ❌ | OAuth 2.0 and OpenID Provider server |
-| [synapse-admin](configuring-playbook-synapse-admin.md) | [etke.cc/synapse-admin](https://ghcr.io/etkecc/synapse-admin) | ❌ | Web UI tool for administrating users and rooms on your Matrix server |
+| [Ketesa](configuring-playbook-ketesa.md) | [etkecc/ketesa](https://ghcr.io/etkecc/ketesa) | ❌ | Fully-featured web UI for administrating your Matrix homeserver — users, rooms, media, sessions, and more |
 | [Metrics and Graphs](configuring-playbook-prometheus-grafana.md) | [prom/prometheus](https://hub.docker.com/r/prom/prometheus/) | ❌ | [Prometheus](https://prometheus.io) time-series database server |
 | [Metrics and Graphs](configuring-playbook-prometheus-grafana.md) | [prom/node-exporter](https://hub.docker.com/r/prom/node-exporter/) | ❌ | Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter |
 | [Metrics and Graphs](configuring-playbook-prometheus-grafana.md) | [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) | ❌ | Graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/element-hq/synapse/tree/master/contrib/grafana) and [Node Exporter](https://github.com/rfrail3/grafana-dashboards) |
@@ -152,10 +155,10 @@ Various services that don't fit any other categories.
 | [synapse_auto_compressor](configuring-playbook-synapse-auto-compressor.md) | [mb-saces/rust-synapse-tools](https://gitlab.com/mb-saces/rust-synapse-tools/container_registry) | ❌ | Cli tool that automatically compresses Synapse's `state_groups` database table in background |
 | [Matrix Corporal](configuring-playbook-matrix-corporal.md) (advanced) | [devture/matrix-corporal](https://hub.docker.com/r/devture/matrix-corporal/) | ❌ | Reconciliator and gateway for a managed Matrix server |
 | [Etherpad](configuring-playbook-etherpad.md) | [etherpad/etherpad](https://hub.docker.com/r/etherpad/etherpad/) | ❌ | Open source collaborative text editor |
-| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/web](https://hub.docker.com/r/jitsi/web) | ❌ | [Jitsi](https://jitsi.org/) web UI |
-| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/jicofo](https://hub.docker.com/r/jitsi/jicofo) | ❌ | [Jitsi](https://jitsi.org/) Focus component |
-| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/prosody](https://hub.docker.com/r/jitsi/prosody) | ❌ | [Jitsi](https://jitsi.org/) Prosody XMPP server component |
-| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/jvb](https://hub.docker.com/r/jitsi/jvb) | ❌ | [Jitsi](https://jitsi.org/) Video Bridge component |
+| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/web](https://github.com/jitsi/docker-jitsi-meet/pkgs/container/web) | ❌ | [Jitsi](https://jitsi.org/) web UI |
+| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/jicofo](https://github.com/jitsi/docker-jitsi-meet/pkgs/container/jicofo) | ❌ | [Jitsi](https://jitsi.org/) Focus component |
+| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/prosody](https://github.com/jitsi/docker-jitsi-meet/pkgs/container/prosody) | ❌ | [Jitsi](https://jitsi.org/) Prosody XMPP server component |
+| [Jitsi](configuring-playbook-jitsi.md) | [jitsi/jvb](https://github.com/jitsi/docker-jitsi-meet/pkgs/container/jvb) | ❌ | [Jitsi](https://jitsi.org/) Video Bridge component |
 | [Cactus Comments](configuring-playbook-cactus-comments.md) | [cactuscomments/cactus-appservice](https://hub.docker.com/r/cactuscomments/cactus-appservice/) | ❌ | Federated comment system built on Matrix |
 | [Cactus Comments](configuring-playbook-cactus-comments.md) | [joseluisq/static-web-server](https://hub.docker.com/r/joseluisq/static-web-server) | ❌ | Federated comment system built on Matrix |
 | [Pantalaimon](configuring-playbook-pantalaimon.md) | [matrixdotorg/pantalaimon](https://hub.docker.com/r/matrixdotorg/pantalaimon) | ❌ | E2EE aware proxy daemon |
@@ -177,6 +180,9 @@ The list of the deprecated or unmaintained services is available [here](configur
 | [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) | [matrixdotorg/matrix-appservice-slack](https://hub.docker.com/r/matrixdotorg/matrix-appservice-slack) | ❌ | Bridge to [Slack](https://slack.com/) |
 | [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md) | [turt2live/matrix-appservice-webhooks](https://hub.docker.com/r/turt2live/matrix-appservice-webhooks) | ❌ | Bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.) |
 | [matrix-chatgpt-bot](configuring-playbook-bot-chatgpt.md) | [matrixgpt/matrix-chatgpt-bot](https://ghcr.io/matrixgpt/matrix-chatgpt-bot) | ❌ | Accessing ChatGPT via your favourite Matrix client |
+| [matrix-ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md) | [activism.international/matrix_ldap_registration_proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy/container_registry) | ❌ | Proxy that handles Matrix registration requests and forwards them to LDAP |
+| [matrix-registration](configuring-playbook-matrix-registration.md) | [zeratax/matrix-registration](https://hub.docker.com/r/devture/zeratax-matrix-registration/) | ❌ | Simple python application to have a token based Matrix registration |
+| [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) | [moanos/matrix-registration-bot](https://hub.docker.com/r/moanos/matrix-registration-bot/) | ❌ | Bot for invitations by creating and managing registration tokens |
 | [mautrix-facebook](configuring-playbook-bridge-mautrix-facebook.md) | [mautrix/facebook](https://mau.dev/mautrix/facebook/container_registry) | ❌ | Bridge to [Facebook](https://facebook.com/) |
 | [mautrix-instagram](configuring-playbook-bridge-mautrix-instagram.md) | [mautrix/instagram](https://mau.dev/mautrix/instagram/container_registry) | ❌ | Bridge to [Instagram](https://instagram.com/) |
 | [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) | [mx-puppet/discord/mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord/container_registry) | ❌ | Bridge to [Discord](https://discordapp.com/) |

docs/faq.md

@@ -456,6 +456,12 @@ If it is correctly specified, look Traefik's logs (`journalctl -fu matrix-traefi
 
 ## Miscellaneous
 
+### The role to manage the service which I deploy has been removed from the playbook. Does this mean that the service can no longer be used on my server?
+
+Not necessarily. Removing the role from the playbook does not always mean that the service has been deprecated by the upstream developers, so as long as the resource such as the Docker image is available, you should be able to keep running it by reverting the specific commit which has removed the role. This essentially means that you will need to maintain your own version of the playbook.
+
+Please keep in mind that you will occasionally need to fix code conflicts if any.
+
 ### I would like to see this favorite service of mine integrated and become available on my Matrix server. How can I request it?
 
 You can freely create an issue for feature request on the repository at GitHub [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/new/choose). Note this is a community project with no financial backing, and there is not assurance that your request would be eventually picked up by others and the requested feature would become available. The easiest way to get a feature into this project is to just develop it yourself.

docs/howto-server-delegation.md

@@ -23,7 +23,7 @@ Both methods have their place and will continue to do so. You only need to use j
 
 For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file. However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation.
 
-**Note**: as an alternative, it is possible to install the server such that it uses only the `matrix.example.com` domain (instead of identifying as the shorter base domain — `example.com`). This should be helpful if you are not in control of anything on the base domain (`example.com`). In this case, you would not need to configure server delegation, but you would need to add other configuration. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ.
+**Note**: as an alternative, it is possible to install the server such that it uses only the `matrix.example.com` domain (instead of identifying as the shorter base domain — `example.com`). This should be helpful if you are not in control of anything on the base domain (`example.com`). In this case, you would not need to configure server delegation, but you would need to add other configuration. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain) on our FAQ.
 
 ## Server Delegation via a well-known file
 

docs/howto-srv-server-delegation.md

@@ -26,7 +26,7 @@ The up-to-date list can be accessed on [traefik's documentation](https://doc.tra
 
 **Note**: the changes below instruct you how to do this for a basic Synapse installation. You will need to adapt the variable name and the content of the labels:
 
-- if you're using another homeserver implementation (e.g. [Conduit](./configuring-playbook-conduit.md), [continuwuity](./configuring-playbook-continuwuity.md) or [Dendrite](./configuring-playbook-dendrite.md))
+- if you're using another homeserver implementation (e.g. [Conduit](./configuring-playbook-conduit.md), [continuwuity](./configuring-playbook-continuwuity.md), [Tuwunel](./configuring-playbook-tuwunel.md) or [Dendrite](./configuring-playbook-dendrite.md))
 - if you're using [Synapse with workers enabled](./configuring-playbook-synapse.md#load-balancing-with-workers) (`matrix_synapse_workers_enabled: true`). In that case, it's actually the `matrix-synapse-reverse-proxy-companion` service which has Traefik labels attached
 
 Also, all instructions below are from an older version of the playbook and may not work anymore.
@@ -49,8 +49,8 @@ This is because the Matrix specification expects the federation endpoint to be s
 ```yaml
 # To let Traefik know which domains' certificates to serve
 matrix_synapse_container_labels_additional_labels: |
-  traefik.http.routers.matrix-synapse-federation-api.tls.domains.main="example.com"
-  traefik.http.routers.matrix-synapse-federation-api.tls.domains.sans="*.example.com"
+  traefik.http.routers.matrix-synapse-public-federation-api.tls.domains.main="example.com"
+  traefik.http.routers.matrix-synapse-public-federation-api.tls.domains.sans="*.example.com"
 ```
 
 ### Configure the DNS-01 challenge for let's encrypt
@@ -137,8 +137,8 @@ matrix_synapse_container_labels_public_federation_api_traefik_rule: PathPrefix(`
 
 # To let Traefik know which domains' certificates to serve
 matrix_synapse_container_labels_additional_labels: |
-  traefik.http.routers.matrix-synapse-federation-api.tls.domains.main="example.com"
-  traefik.http.routers.matrix-synapse-federation-api.tls.domains.sans="*.example.com"
+  traefik.http.routers.matrix-synapse-public-federation-api.tls.domains.main="example.com"
+  traefik.http.routers.matrix-synapse-public-federation-api.tls.domains.sans="*.example.com"
 
 # Add a new ACME configuration without having to disable the default one, since it would have a wide range of side effects
 traefik_configuration_extension_yaml: |

docs/importing-postgres.md

@@ -25,6 +25,11 @@ The migration might be a good moment, to "reset" a not properly working bridge.
 
 Before doing the actual import, **you need to upload your Postgres dump file to the server** (any path is okay).
 
+> [!WARNING]
+> Do not import into a database that already contains tables (e.g. one that a service has already initialized and used). As the [official Synapse backup guide](https://element-hq.github.io/synapse/latest/usage/administration/backups.html) puts it: at best this will error, at worst it will lead to subtle database inconsistencies. Import into an empty (freshly created) database instead.
+
+**Note for Synapse users restoring an older backup**: if the server kept running (and users kept chatting) after the backup you are restoring was made, truncate the `e2e_one_time_keys_json` table after importing and before starting Synapse. Restoring an older backup can otherwise cause already-used one-time keys to be re-issued, leading to message decryption errors for your users. You can do this by [getting a database terminal](maintenance-postgres.md#getting-a-database-terminal), connecting to the Synapse database (`\c synapse`) and running `TRUNCATE e2e_one_time_keys_json;`. Clients will generate and upload fresh one-time keys automatically.
+
 ## Importing
 
 To import, run this command (make sure to replace `SERVER_PATH_TO_POSTGRES_DUMP_FILE` with a file path on your server):

docs/importing-synapse-media-store.md

@@ -13,6 +13,8 @@ You can manually import your `media_store` files from a previous installation of
 
 Before doing the actual data restore, **you need to upload your media store directory to the server** (any path is okay).
 
+You also need the [rsync](https://rsync.samba.org/) utility installed **on the server**, as the import performs a server-side `rsync` synchronization. The playbook does not install it for you. On most distributions, it is available as a package called `rsync`.
+
 If you are [storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional), restoring with this tool is not possible right now.
 
 As an alternative, you can perform a manual restore using the [AWS CLI tool](https://aws.amazon.com/cli/) (e.g. `aws s3 sync /path/to/server/media_store/. s3://name-of-bucket/`)

docs/installing.md

@@ -1,13 +1,13 @@
 <!--
-SPDX-FileCopyrightText: 2018 - 2023 Slavi Pantaleev
-SPDX-FileCopyrightText: 2018 - 2024 MDAD project contributors
 SPDX-FileCopyrightText: 2018 Aaron Raimist
+SPDX-FileCopyrightText: 2018-2023 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018-2024 MDAD project contributors
 SPDX-FileCopyrightText: 2019 Edgars Voroboks
 SPDX-FileCopyrightText: 2019 Michael Haak
 SPDX-FileCopyrightText: 2020 Kevin Lanni
-SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 Mitja Jež
 SPDX-FileCopyrightText: 2024 Nikita Chernyi
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
@@ -27,7 +27,7 @@ To update your playbook directory and all upstream Ansible roles (defined in the
 - either: `just update`
 - or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
 
-If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
+If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly after updating the playbook: `git pull; rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
 
 For details about `just` commands, take a look at: [Running `just` commands](just.md).
 
@@ -41,6 +41,8 @@ If you **don't** use SSH keys for authentication, but rather a regular password,
 
 If you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to all Ansible commands.
 
+Instead of typing the sudo password on each run (`-K`) or storing it in plain text in the inventory hosts file, you can also pull it from the [pass](https://www.passwordstore.org/) password manager by adding `ansible_become_password='{{ lookup("community.general.passwordstore", "path/to/password") }}'` to your host line. See the [passwordstore lookup documentation](https://docs.ansible.com/ansible/latest/collections/community/general/passwordstore_lookup.html) for more details.
+
 There 2 ways to start the installation process — depending on whether you're [Installing a brand new server (without importing data)](#installing-a-brand-new-server-without-importing-data) or [Installing a server into which you'll import old data](#installing-a-server-into-which-youll-import-old-data).
 
 **Note**: if you are migrating from an old server to a new one, take a look at [this guide](maintenance-migrating.md) instead. This is an easier and more straightforward way than installing a server and importing old data into it.
@@ -150,6 +152,12 @@ After completing the installation, you can:
   * or come say Hi in our support room — [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting.
 - or help make this playbook better by contributing (code, documentation, or [coffee/beer](https://liberapay.com/s.pantaleev/donate))
 
+### Installing native Matrix clients on your computer
+
+As the playbook's aim is to help you to install and manage Matrix services on your server, if you are looking for dedicated native Matrix clients which run on your computer, you need to install ones by yourself. There is a convenient list which introduces known Matrix clients on this page: <https://matrix.org/ecosystem/clients/>
+
+If you feel overwhelmed by the variety and the number of the available clients, you might want to install [**Komai**](https://github.com/etkecc/komai), a desktop-first Matrix chat application maintained by the team behind the playbook. It is stable, and just works without quirks!
+
 ### ⚠️ Keep the playbook and services up-to-date
 
 While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.

docs/maintenance-migrating.md

@@ -37,7 +37,7 @@ cd /etc/systemd/system/ && systemctl disable --now matrix*
 
 ## Copy data directory to the new server
 
-After you've confirmed that all services were stopped, copy the `/matrix` directory from the old server to the new server. When copying, make sure to preserve ownership and permissions (use `cp -p` or `rsync -ar`)!
+After you've confirmed that all services were stopped, copy the `/matrix` directory from the old server to the new server. When copying, make sure to preserve ownership and permissions (use `cp -p` or `rsync -a`)!
 
 ## Adjust DNS records
 

docs/maintenance-postgres.md

@@ -76,6 +76,8 @@ If you are using an [external Postgres server](configuring-playbook-external-pos
 
 Restoring a backup made this way can be done by [importing it](importing-postgres.md).
 
+**Note for Synapse users**: the [official Synapse backup guide](https://element-hq.github.io/synapse/latest/usage/administration/backups.html) recommends that the `e2e_one_time_keys_json` table either not be backed up, or be truncated after restoring (before Synapse is started). The full-server dump command above does include it, so if you ever restore a backup that is older than the server's current state, remember to truncate that table as described in [the importing guide](importing-postgres.md).
+
 ## Upgrading PostgreSQL
 
 Unless you are using an [external Postgres server](configuring-playbook-external-postgres.md), this playbook initially installs Postgres for you.

docs/maintenance-synapse.md

@@ -105,6 +105,9 @@ Cache autotuning is **enabled by default** and controlled via the following vari
 
 You can **learn more about cache-autotuning and the global cache factor settings** in the [Synapse's documentation on caches and associated values](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#caches-and-associated-values).
 
+> [!NOTE]
+> These limits apply **per Synapse process**. If you have [workers](configuring-playbook-synapse.md#load-balancing-with-workers) enabled, the main process and every worker each apply the configured limits independently, so the theoretical aggregate cache memory usage gets multiplied by the number of processes. When running many workers on a memory-constrained server, consider setting these variables to lower, explicitly chosen values.
+
 To **disable cache auto-tuning**, unset all values:
 
 ```yaml