Update dependency livekit_server to v1.13.4-0

`agru` likes to open a TUI by default and shows what is done there,
then auto-closes and you don't get to see what it did.

.codespellrc

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

.config/ansible-lint.yml

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2022 - 2023 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 ---
 
 use_default_rules: true

.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-0
+
+# 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/FUNDING.yml

@@ -1,3 +1,8 @@
+# SPDX-FileCopyrightText: 2020 - 2021 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2022 Marko Weltzer
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 ---
 # These are supported funding model platforms
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -34,7 +34,7 @@ A clear and concise description of what you expected to happen.
 
 **Ansible:**
 If your problem appears to be with Ansible, tell us:
-- where you run Ansible -- e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
+- where you run Ansible — e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
 - what version of Ansible you're running (see `ansible --version`)
 
 <!--

.github/ISSUE_TEMPLATE/bug_report.md.license

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later

.github/ISSUE_TEMPLATE/config.yml

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2024 Suguru Hirahara
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 ---
 blank_issues_enabled: false
 contact_links:

.github/ISSUE_TEMPLATE/feature_request.md.license

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later

.github/ISSUE_TEMPLATE/i-need-help.md

@@ -28,7 +28,7 @@ Make sure to remove any secret values before posting your vars.yml file publicly
 
 **Ansible:**
 If your problem appears to be with Ansible, tell us:
-- where you run Ansible -- e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
+- where you run Ansible — e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
 - what version of Ansible you're running (see `ansible --version`)
 
 **Problem description**:

.github/ISSUE_TEMPLATE/i-need-help.md.license

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later

.github/dependabot.yaml

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2022 Marko Weltzer
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 ---
 version: 2
 updates:

.github/renovate.json

@@ -1,12 +1,17 @@
 {
 	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
 	"extends": [
-		"config:base"
+		"config:recommended"
 	],
-	"labels": ["dependencies"],
+	"labels": [
-	"regexManagers": [
+		"dependencies"
+	],
+	"customManagers": [
 		{
-			"fileMatch": ["defaults/main.yml$"],
+			"customType": "regex",
+			"managerFilePatterns": [
+				"/defaults/main.yml$/"
+			],
 			"matchStrings": [
 				"# renovate: datasource=(?<datasource>[a-z-.]+?) depName=(?<depName>[^\\s]+?)(?: (?:lookupName|packageName)=(?<packageName>[^\\s]+?))?(?: versioning=(?<versioning>[a-z-0-9]+?))?\\s+[A-Za-z0-9_]+?(?:_version|_tag)\\s*:\\s*[\"']?(?<currentValue>.+?)[\"']?\\s"
 			]
@@ -14,14 +19,40 @@
 	],
 	"packageRules": [
 		{
-			"matchSourceUrlPrefixes": [
+			"ignoreUnstable": false,
-				"https://github.com/devture/com.devture.ansible.role",
+			"versioning": "loose",
-				"https://github.com/mother-of-all-self-hosting"
+			"matchSourceUrls": [
-			],
+				"https://github.com/devture/com.devture.ansible.role{/,}**",
-			"ignoreUnstable": false
+				"https://github.com/mother-of-all-self-hosting{/,}**"
-		}
-	],
-	"ignoreDeps": [
-		"ghcr.io/matrixgpt/matrix-chatgpt-bot"
 			]
+		},
+		{
+			"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

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2024 Suguru Hirahara
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 ---
 name: 'Close stale issues and PRs'
 on:  # yamllint disable-line rule:truthy
@@ -15,7 +19,7 @@ jobs:
     if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v9
+      - uses: actions/stale@v10
         with:
           ######################################################################
           # Issues/PRs

.github/workflows/lock-threads.yml

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2017 - 2023 Armin Sebastian
+#
+# SPDX-License-Identifier: MIT
+
+---
+name: 'Lock Threads'
+on:  # yamllint disable-line rule:truthy
+  # Use this to do a dry run from a pull request
+  # pull_request:
+  schedule:
+    - cron: '0 * * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: lock-threads
+
+jobs:
+  action:
+    if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dessant/lock-threads@v6
+        with:
+          add-issue-labels: 'outdated'
+          process-only: 'issues, prs'

.github/workflows/matrix.yml

@@ -1,26 +1,45 @@
+# SPDX-FileCopyrightText: 2022 Marko Weltzer
+# SPDX-FileCopyrightText: 2022 Nikita Chernyi
+# SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 ---
 name: Matrix CI
 
-on:  # yamllint disable-line rule:truthy
+on: [push, pull_request]  # yamllint disable-line rule:truthy
-  push:
+
-  pull_request:
+permissions:
+  contents: read
 
 jobs:
-  yamllint:
+  prek:
-    name: yamllint
+    name: Run prek hooks
     runs-on: ubuntu-latest
+    container:
+      image: docker.io/archlinux:base-devel
+
     steps:
+      # git must be installed before checkout so it does a proper clone
+      # (with .git directory) instead of a tarball download.
+      - name: Install git
+        run: pacman -Sy --noconfirm git
+
       - name: Check out
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
-      - name: Run yamllint
+
-        uses: frenck/action-yamllint@v1.5.0
+      - name: Restore prek cache
-  ansible-lint:
+        uses: actions/cache@v6
-    name: ansible-lint
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out
-        uses: actions/checkout@v4
-      - name: Run ansible-lint
-        uses: ansible-community/ansible-lint-action@v6.17.0
         with:
-          path: roles/custom
+          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

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2024 Suguru Hirahara
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+name: Update translations
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - master
+    paths:  # See include_patterns on conf.py
+      - 'docs/*.md'
+      - 'i18n/README.md'
+      - '*.md'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
+    name: Update translations
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      # Setting up recommended prerequisites
+      # See: i18n/README.md
+      - uses: astral-sh/setup-uv@v8.3.2
+      - uses: extractions/setup-just@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.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.
+          branch: create-pull-request/i18n
+          commit-message: Automatic translations update
+          delete-branch: true
+          labels: docs
+          sign-commits: true
+          title: Automatic translations update

.gitignore

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

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+---
+
+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-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.3
+    hooks:
+      - id: codespell
+        args: ["--skip=*.po,*.pot,i18n/"]
+  - repo: https://github.com/fsfe/reuse-tool  # https://reuse.software/dev/#pre-commit-hook
+    rev: v6.2.0
+    hooks:
+      - id: reuse
+  - repo: https://github.com/ansible/ansible-lint
+    rev: v26.6.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.license

@@ -0,0 +1,14 @@
+SPDX-FileCopyrightText: 2018 - 2024 MDAD project contributors
+SPDX-FileCopyrightText: 2018 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 Aaron Raimist
+SPDX-FileCopyrightText: 2019 Thomas Kuehne
+SPDX-FileCopyrightText: 2020 John Goerzen
+SPDX-FileCopyrightText: 2020 Julian Foad
+SPDX-FileCopyrightText: 2021 Agustin Ferrario
+SPDX-FileCopyrightText: 2021 Dan Arnfield
+SPDX-FileCopyrightText: 2022 Jost Alemann
+SPDX-FileCopyrightText: 2023 Felix Stupp
+SPDX-FileCopyrightText: 2023 Julian-Samuel Gebühr
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later

LICENSES/CC0-1.0.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

LICENSES/MIT.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software"), to deal in the Software without restriction, including 
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the 
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 
+USE OR OTHER DEALINGS IN THE SOFTWARE.

Makefile

@@ -1,8 +1,15 @@
-.PHONY: roles lint
+# SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+.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

@@ -1,10 +1,10 @@
-[![Support room on Matrix](https://img.shields.io/matrix/matrix-docker-ansible-deploy:devture.com.svg?label=%23matrix-docker-ansible-deploy%3Adevture.com&logo=matrix&style=for-the-badge&server_fqdn=matrix.devture.com)](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate)
+[![Support room on Matrix](https://img.shields.io/matrix/matrix-docker-ansible-deploy:devture.com.svg?label=%23matrix-docker-ansible-deploy%3Adevture.com&logo=matrix&style=for-the-badge&server_fqdn=matrix.devture.com&fetchMode=summary)](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate) [![REUSE status](https://api.reuse.software/badge/github.com/spantaleev/matrix-docker-ansible-deploy)](https://api.reuse.software/info/github.com/spantaleev/matrix-docker-ansible-deploy)
 
 # Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker
 
 ## 🎯 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)).
 
@@ -52,7 +52,8 @@ 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) |
-| [Conduwuit](https://conduwuit.puppyirl.gay/) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduwuit is a fork of Conduit. | [Link](docs/configuring-playbook-conduwuit.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,7 +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
 
@@ -73,12 +77,12 @@ Services that run on the server to make the various parts of your installation w
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
 | [PostgreSQL](https://www.postgresql.org/)| ✅ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
-| [coturn](https://github.com/coturn/coturn) | ✅ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
+| [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. [Using your own webserver](docs/configuring-playbook-own-webserver.md) is also possible. | [Link](docs/configuring-playbook-traefik.md) |
-| [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md) | [Link](docs/configuring-playbook-traefik.md) |
 | [Let's Encrypt](https://letsencrypt.org/) | ✅ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
 | [Exim](https://www.exim.org/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
-| [ma1sd](https://github.com/ma1uta/ma1sd) | ❌ | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
+| [coturn](https://github.com/coturn/coturn) | ❌ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
 | [ddclient](https://github.com/linuxserver/docker-ddclient) | ❌ | Dynamic DNS | [Link](docs/configuring-playbook-dynamic-dns.md) |
+| Matrix RTC stack | ❌ | Supporting components ([LiveKit Server](docs/configuring-playbook-livekit-server.md) and [LiveKit JWT Service](docs/configuring-playbook-livekit-jwt-service.md)) for in-app audio/video calls for Matrix clients | [Link](docs/configuring-playbook-matrix-rtc.md) |
 
 ### Authentication
 
@@ -89,10 +93,8 @@ 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) | ❌ | A proxy that handles Matrix registration requests and forwards them to LDAP. | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.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) |
-| [matrix-registration](https://github.com/ZerataX/matrix-registration) | ❌ | A simple python application to have a token based Matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
+| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | Spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
-| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (UVS) | ❌ | 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) | ❌ | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
 
 ### File Storage
 
@@ -102,7 +104,7 @@ Use alternative file storage to the default `media_store` folder.
 | ---- | -------- | ----------- | ------------- |
 | [Goofys](https://github.com/kahing/goofys) | ❌ | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3-goofys.md) |
 | [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) | ❌ | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3.md) |
-| [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) | ❌ | matrix-media-repo is a highly customizable multi-domain media repository for Matrix. Intended for medium to large deployments, this media repo de-duplicates media while being fully compliant with the specification. | [Link](docs/configuring-playbook-matrix-media-repo.md) |
+| [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) | ❌ | Highly customizable multi-domain media repository for Matrix. Intended for medium to large deployments, this media repo de-duplicates media while being fully compliant with the specification. | [Link](docs/configuring-playbook-matrix-media-repo.md) |
 
 ### Bridges
 
@@ -114,29 +116,26 @@ 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-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) |
 | [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-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) | ❌ | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-appservice-slack.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) |
-| [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) | ❌ | Bridge to [Skype](https://www.skype.com) | [Link](docs/configuring-playbook-bridge-go-skype-bridge.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-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) | ❌ | Bridge to [Slack](https://slack.com) | [Link](docs/configuring-playbook-bridge-mx-puppet-slack.md) |
-| [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) | ❌ | Bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-instagram.md) |
-| [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) | ❌ | Bridge for Twitter-DMs ([Twitter](https://twitter.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-twitter.md) |
-| [mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) | ❌ | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-discord.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://github.com/icewind1991/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.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) |
-| [Email2Matrix](https://github.com/devture/email2matrix) | ❌ | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
 | [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) |
 
 ### Bots
@@ -145,13 +144,12 @@ Bots provide various additional functionality to your installation.
 
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
-| [baibot](https://github.com/etkecc/baibot) | ❌ | A 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) |
+| [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) |
-| [maubot](https://github.com/maubot/maubot) | ❌ | A 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) |
-| [Honoroit](https://github.com/etkecc/honoroit) | ❌ | A 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) |
-| [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | A 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))|
-| [Draupnir](https://github.com/the-draupnir-project/Draupnir) | ❌ | A 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))|
 | [Buscarron](https://github.com/etkecc/buscarron) | ❌ | Web forms (HTTP POST) to Matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
 
 ### Administration
@@ -162,8 +160,8 @@ 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) | ❌ | A 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-nginxlog.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) |
 | [synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) | ❌ | Export the usage statistics of a Synapse homeserver to be scraped by Prometheus. | [Link](docs/configuring-playbook-synapse-usage-exporter.md) |
@@ -174,16 +172,16 @@ Various services that don't fit any other categories.
 
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
-| [sliding-sync](https://github.com/matrix-org/sliding-sync)| ❌ | (Superseded by Simplified Sliding Sync integrated into Synapse > `1.114` and Conduit > `0.6.0`) Sliding Sync support for clients which require it (e.g. old Element X versions before Simplified Sliding Sync was developed) | [Link](docs/configuring-playbook-sliding-sync-proxy.md) |
+| [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) | ❌ | Cli tool that automatically compresses `state_groups` database table in background | [Link](docs/configuring-playbook-synapse-auto-compressor.md) |
-| [synapse_auto_accept_invite](https://github.com/matrix-org/synapse-auto-accept-invite) | ❌ | A Synapse module to automatically accept invites. | [Link](docs/configuring-playbook-synapse-auto-accept-invite.md) |
-| [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) | ❌ | A cli tool that automatically compresses `state_groups` database table in background. | [Link](docs/configuring-playbook-synapse-auto-compressor.md) |
 | [Matrix Corporal](https://github.com/devture/matrix-corporal) (advanced) | ❌ | Reconciliator and gateway for a managed Matrix server | [Link](docs/configuring-playbook-matrix-corporal.md) |
-| [Etherpad](https://etherpad.org) | ❌ | An open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
+| [Matrix.to](https://github.com/matrix-org/matrix.to) | ❌ | Simple URL redirection service for the Matrix ecosystem | [Link](docs/configuring-playbook-matrixto.md) |
-| [Jitsi](https://jitsi.org/) | ❌ | An open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
+| [Etherpad](https://etherpad.org) | ❌ | Open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
-| [Cactus Comments](https://cactus.chat) | ❌ | A federated comment system built on Matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
+| [Jitsi](https://jitsi.org/) | ❌ | Open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
-| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | ❌ | An E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
+| [Cactus Comments](https://cactus.chat) | ❌ | Federated comment system built on Matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
+| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | ❌ | E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
 | [Sygnal](https://github.com/matrix-org/sygnal) | ❌ | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
 | [ntfy](https://ntfy.sh) | ❌ | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
+| [Element Call](https://github.com/element-hq/element-call) | ❌ | A native Matrix video conferencing application | [Link](docs/configuring-playbook-element-call.md) |
 
 ## 🆕 Changes
 

README.md.license

@@ -0,0 +1,34 @@
+SPDX-FileCopyrightText: 2017 - 2025 MDAD project contributors
+SPDX-FileCopyrightText: 2017 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 - 2021 Aaron Raimist
+SPDX-FileCopyrightText: 2019 - 2020 Hugues Morisset
+SPDX-FileCopyrightText: 2019 Edgars Voroboks
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2020 Björn Marten
+SPDX-FileCopyrightText: 2020 Lee Verberne
+SPDX-FileCopyrightText: 2020 Marcel Partap
+SPDX-FileCopyrightText: 2020 Matthew Croughan
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 Alexandar Mechev
+SPDX-FileCopyrightText: 2021 Béla Becker
+SPDX-FileCopyrightText: 2021 Cody Neiman
+SPDX-FileCopyrightText: 2021 Marcus Proest
+SPDX-FileCopyrightText: 2021 Matthew Cengia
+SPDX-FileCopyrightText: 2021 Prasiddh Pooskur
+SPDX-FileCopyrightText: 2021 Toni Spets
+SPDX-FileCopyrightText: 2021 Yannick Goossens
+SPDX-FileCopyrightText: 2022 - 2023 Cody Wyatt Neiman
+SPDX-FileCopyrightText: 2022 - 2025 Nikita Chernyi
+SPDX-FileCopyrightText: 2022 Andrew Morgan
+SPDX-FileCopyrightText: 2022 Christos Karamolegkos
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Julian Foad
+SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
+SPDX-FileCopyrightText: 2022 Kim Brose
+SPDX-FileCopyrightText: 2023 - 2024 Michael Hollister
+SPDX-FileCopyrightText: 2023 Joe Kappus
+SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
+SPDX-FileCopyrightText: 2023 Shreyas Ajjarapu
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later

REUSE.toml

@@ -7,9 +7,23 @@ version = 1
 # Computer-generated files and other files which cannot be copyrighted
 [[annotations]]
 path = [
+    ".github/renovate.json",
+    "collections/requirements.yml",
     "i18n/.gitignore",
+    "i18n/PUBLISHED_LANGUAGES",
     "i18n/requirements.txt",
-    "i18n/PUBLISHED_LANGUAGES"
+    "roles/custom/**/*.repo",
+    ".codespellrc",
+    ".editorconfig",
+    ".envrc",
+    ".gitattributes",
+    ".gitignore",
+    ".pre-commit-config.yaml",
+    ".yamllint",
+    "ansible.cfg",
+    "flake.lock",
+    "flake.nix",
+    "requirements.yml"
 ]
 SPDX-FileCopyrightText = "NONE"
 SPDX-License-Identifier = "CC0-1.0"
@@ -21,5 +35,5 @@ path = [
     "i18n/**/*.pot"
 ]
 precedence = "aggregate"
-SPDX-FileCopyrightText = "Slavi Pantaleev, MDAD community members"
+SPDX-FileCopyrightText = "2024 - 2025 Slavi Pantaleev, MDAD project contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"

YEAR-IN-REVIEW.md

@@ -1,10 +1,17 @@
+<!--
+SPDX-FileCopyrightText: 2023 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # 2023
 
 2023 was a year filled with many changes for matrix-docker-ansible-deploy. In this post, we're looking backward at some of the major changes that happened this year, as well as taking a glimpse of what's ahead in 2024.
 
 2023 is probably [the year of AI](https://journal.everypixel.com/2023-the-year-of-ai), with millions of people jumping aboard [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/chatgpt) train. matrix-docker-ansible-deploy is no stranger to this and 2023 began with a PR from [bertybuttface](https://github.com/bertybuttface) who added support for [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#chatgpt-support)). While OpenAI's chat GPT website was frequently overloaded in the past, their API was up which made using this bot both convenient and more reliable.
 
-AI aside, with the playbook's focus being containers, we're **doubling down on being "container native"** and becoming more interoperable for people hosting other containers on the Matrix server. In [2022](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/YEAR-IN-REVIEW.md#2022), we've announced a few sibling Ansible playbooks, their use of [Traefik](https://doc.traefik.io/traefik/) and the possiblity of matrix-docker-ansible-deploy also switching to this reverse-proxy. This prediction materialized quickly. The **largest change** in the playbook in 2023 happened way back in February - matrix-docker-ansible-deploy [starting the switch from nginx to Traefik](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-reverse-proxy-configuration-changes-and-initial-traefik-support) and then quickly [making Treafik the default reverse-proxy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#traefik-is-the-default-reverse-proxy-now). As noted in the changelog entries, we envisioned a quick and complete elimination of `matrix-nginx-proxy`, but at the end of 2023, it hasn't happened yet. The playbook is already using Traefik as the front-most reverse-proxy, but nginx (via `matrix-nginx-proxy`) is still around - it has taken a step back and is only used internally for new setups. Work got to a stall due to:
+AI aside, with the playbook's focus being containers, we're **doubling down on being "container native"** and becoming more interoperable for people hosting other containers on the Matrix server. In [2022](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/YEAR-IN-REVIEW.md#2022), we've announced a few sibling Ansible playbooks, their use of [Traefik](https://doc.traefik.io/traefik/) and the possibility of matrix-docker-ansible-deploy also switching to this reverse-proxy. This prediction materialized quickly. The **largest change** in the playbook in 2023 happened way back in February - matrix-docker-ansible-deploy [starting the switch from nginx to Traefik](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-reverse-proxy-configuration-changes-and-initial-traefik-support) and then quickly [making Treafik the default reverse-proxy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#traefik-is-the-default-reverse-proxy-now). As noted in the changelog entries, we envisioned a quick and complete elimination of `matrix-nginx-proxy`, but at the end of 2023, it hasn't happened yet. The playbook is already using Traefik as the front-most reverse-proxy, but nginx (via `matrix-nginx-proxy`) is still around - it has taken a step back and is only used internally for new setups. Work got to a stall due to:
 
 *   complexity: untangling the overly large and messy `matrix-nginx-proxy` component is difficult
 *   the current setup became "good enough" because nginx has become an internal implementation detail for those who have migrated to Traefik. Traefik is already the default public reverse-proxy and gives better possibilities to people wishing to run other web-exposed containers on their Matrix server via [Docker Compose](https://docs.docker.com/compose/), other Ansible playbooks like [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) (more about this one, below) or any other way.
@@ -69,7 +76,7 @@ When it comes to the `matrix-docker-ansible-deploy` Ansible playbook, 2022 was t
 
 Support for the following new **bridges** was added:
 
-*   [Postmoogle](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#postmoogle-email-bridge-support) for bi-directional email bridging, which supersedes my old and simplistic [email2matrix](https://github.com/devture/email2matrix) one-way bridge-bot
+*   [Postmoogle](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#postmoogle-email-bridge-support) for bi-directional email bridging, which supersedes my old and simplistic [Email2Matrix](https://github.com/devture/email2matrix) one-way bridge-bot
 *   [mautrix-discord](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#mautrix-discord-support)
 *   [go-skype-bridge](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#go-skype-bridge-bridging-support)
 *   [matrix-appservice-kakaotalk](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-appservice-kakaotalk-support)

ansible.cfg

@@ -1,6 +1,6 @@
 [defaults]
 retry_files_enabled = False
-stdout_callback = yaml
+result_format = yaml
 
 [connection]
 pipelining = True

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/ansible-all-hosts.sh

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+
+# SPDX-FileCopyrightText: 2022 - 2024 MDAD project contributors
+# SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 #
 # Run the playbook on multiple hosts with different credentials with this script
 # It defaults to ansible tags "setup-all,start". You can pass alternative tags

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,4 +1,9 @@
 #!/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.
@@ -25,14 +30,24 @@ 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/matrix_bridge_mautrix_meta_messenger_/matrix_bridge_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_bridge_mautrix_meta_instagram_meta_mode: \(.*\)/matrix_bridge_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
+sed --in-place 's/matrix_bridge_mautrix_meta_instagram_identifier: \(.*\)/matrix_bridge_mautrix_meta_instagram_identifier: matrix-mautrix-meta-instagram/g' $instagram_role_path/defaults/main.yml
 
-echo "# matrix-mautrix-meta-instagram" > $instagram_role_path/README.md
+# 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

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

@@ -1,6 +1,15 @@
+<!--
+SPDX-FileCopyrightText: 2018 - 2021 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 Aaron Raimist
+SPDX-FileCopyrightText: 2019 Lyubomir Popov
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Table of Contents
 
-## ⬇️ Installaton guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->
+## ⬇️ Installation guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->
 
 There are two installation guides available for beginners and advanced users.
 
@@ -10,7 +19,7 @@ There are two installation guides available for beginners and advanced users.
 
     - [Prerequisites](prerequisites.md)
 
-    - [Configuring your DNS settings](configuring-dns.md)
+    - [Configuring DNS settings](configuring-dns.md)
 
     - [Getting the playbook](getting-the-playbook.md)
 
@@ -27,23 +36,23 @@ NOTE:
 
 You can check useful documentation for configuring components here: [Configuring the playbook](configuring-playbook.md)
 
-- [Administration](configuring-playbook.md#administration) - services that help you in administrating and monitoring your Matrix installation
+- [Administration](configuring-playbook.md#administration) — services that help you in administrating and monitoring your Matrix installation
 
-- [Authentication and user-related](configuring-playbook.md#authentication-and-user-related) - extend and modify how users are authenticated on your homeserver
+- [Authentication and user-related](configuring-playbook.md#authentication-and-user-related) — extend and modify how users are authenticated on your homeserver
 
-- [Bots](configuring-playbook.md#bots) - bots provide various additional functionality to your installation
+- [Bots](configuring-playbook.md#bots) — bots provide various additional functionality to your installation
 
-- [Bridges](configuring-playbook.md#bridging-other-networks) - bridges can be used to connect your Matrix installation with third-party communication networks
+- [Bridges](configuring-playbook.md#bridging-other-networks) — bridges can be used to connect your Matrix installation with third-party communication networks
 
-- [Clients](configuring-playbook.md#clients) - web clients for Matrix that you can host on your own domains
+- [Clients](configuring-playbook.md#clients) — web clients for Matrix that you can host on your own domains
 
-- [Core service adjustments](configuring-playbook.md#core-service-adjustments) - backbone of your Matrix system
+- [Core service adjustments](configuring-playbook.md#core-service-adjustments) — backbone of your Matrix system
 
-- [File Storage](configuring-playbook.md#file-storage) - use alternative file storage to the default `media_store` folder
+- [File Storage](configuring-playbook.md#file-storage) — use alternative file storage to the default `media_store` folder
 
 <!-- NOTE: sort list items above alphabetically -->
 
-- [Other specialized services](configuring-playbook.md#other-specialized-services) - various services that don't fit any other categories
+- [Other specialized services](configuring-playbook.md#other-specialized-services) — various services that don't fit any other categories
 
 ## 👨‍🔧 Maintenance
 
@@ -51,8 +60,6 @@ If your server and services experience issues, feel free to come to [our support
 
 <!-- NOTE: sort list items alphabetically -->
 
-- [Checking if services work](maintenance-checking-services.md)
-
 - [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
 
 - [PostgreSQL maintenance](maintenance-postgres.md)
@@ -63,12 +70,14 @@ If your server and services experience issues, feel free to come to [our support
 
 ## Other documentation pages <!-- NOTE: this header's title and the section below need optimization -->
 
-- ℹ️ **[FAQ](faq.md)** - various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook
+- ℹ️ **[FAQ](faq.md)** — various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook
 
 <!-- NOTE: sort list items under faq.md alphabetically -->
 
 - [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)
@@ -81,6 +90,10 @@ 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)
+
+- [Using Ansible for the playbook](ansible.md)

docs/alternative-architectures.md

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Horvath Gergely
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Alternative architectures
 
 As stated in the [Prerequisites](prerequisites.md), currently only `amd64` (`x86_64`) is fully supported.

docs/ansible.md

@@ -1,5 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Aaron Raimist
+SPDX-FileCopyrightText: 2020 Hanno J. Gödecke
+SPDX-FileCopyrightText: 2022 Kai Biebel
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-# Running this playbook
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Using Ansible for the playbook
 
 This playbook is meant to be run using [Ansible](https://www.ansible.com/).
 
@@ -11,10 +20,13 @@ To manually check which version of Ansible you're on, run: `ansible --version`.
 
 For the **best experience**, we recommend getting the **latest version of Ansible available**.
 
-We're not sure what's the minimum version of Ansible that can run this playbook successfully. The lowest version that we've confirmed (on 2022-11-26) to be working fine is: `ansible-core` (`2.11.7`) combined with `ansible` (`4.10.0`).
+We're not sure what's the minimum version of Ansible that can run this playbook successfully. The lowest version that we suspect (on 2025-09-03) to be working fine is: `ansible-core` (`2.15.1`).
 
 If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
 
+> [!WARNING]
+> One reason for the version requirement being as such is that the playbook by default installs Docker for you using [this Docker role](https://github.com/geerlingguy/ansible-role-docker) which [has a hard requirement on Ansible v2.15.1](https://github.com/geerlingguy/ansible-role-docker/commit/7f44a1d9ad8132819ea9852918bca5dab8757cd0). If you install Docker yourself another way, you can tell the playbook to skip running this role (by adding `matrix_playbook_docker_installation_enabled: false` to your `vars.yml` configuration). It may then be possible to get the playbook running on an older version of Ansible. Still, this is a complication and your mileage may vary. We recommend [upgrading Ansible](#upgrading-ansible) instead of going into uncharted territory.
+
 ## Upgrading Ansible
 
 Depending on your distribution, you may be able to upgrade Ansible in a few different ways:
@@ -29,12 +41,17 @@ If using the `pip` method, do note that the `ansible-playbook` binary may not be
 
 ## Using Ansible via Docker
 
-Alternatively, you can run Ansible inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
+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).
 
-This ensures that you're using a very recent Ansible version, which is less likely to be incompatible with the playbook.
+This ensures that:
+
+- you're using a very recent Ansible version, which is less likely to be incompatible with the playbook
+- you also get access to the [agru](https://github.com/etkecc/agru) tool for quicker Ansible role installation (when running `just roles`) compared to `ansible-galaxy`
 
 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:
@@ -46,50 +63,54 @@ Once you have a working Docker installation on the server, **clone the playbook*
 
 You would then need to add `ansible_connection=community.docker.nsenter` to the host line in `inventory/hosts`. This tells Ansible to connect to the "remote" machine by switching Linux namespaces with [nsenter](https://man7.org/linux/man-pages/man1/nsenter.1.html), instead of using SSH.
 
-Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `ansible-playbook --connection=community.docker.nsenter …`
+Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `just install-all --connection=community.docker.nsenter` (or `ansible-playbook --connection=community.docker.nsenter …`).
 
 Run this from the playbook's directory:
 
 ```sh
-docker run -it --rm \
+docker run \
+-it \
+--rm \
 --privileged \
 --pid=host \
 -w /work \
--v `pwd`:/work \
+--mount type=bind,src=`pwd`,dst=/work \
 --entrypoint=/bin/sh \
-docker.io/devture/ansible:2.18.1-r0-0
+ghcr.io/devture/ansible:14.0.0-r0-0
 ```
 
 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.
 
 First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
 
-Finally, you can execute `ansible-playbook …` (or `ansible-playbook --connection=community.docker.nsenter …`) commands as per normal now.
+Finally, you can execute `just` or `ansible-playbook …` (e.g. `ansible-playbook --connection=community.docker.nsenter …`) commands as per normal now.
 
 ### Running Ansible in a container on another computer (not the Matrix server)
 
 Run this from the playbook's directory:
 
 ```sh
-docker run -it --rm \
+docker run \
+-it \
+--rm \
 -w /work \
--v `pwd`:/work \
+--mount type=bind,src=`pwd`,dst=/work \
--v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
+--mount type=bind,src=$HOME/.ssh/id_ed25519,dst=/root/.ssh/id_ed25519,ro \
 --entrypoint=/bin/sh \
-docker.io/devture/ansible:2.18.1-r0-0
+ghcr.io/devture/ansible:14.0.0-r0-0
 ```
 
-The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`). If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part.
+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.
 
 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.
 
 First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
 
-Finally, you execute `ansible-playbook …` commands as per normal now.
+Finally, you execute `just` or `ansible-playbook …` commands as per normal now.
 
 #### If you don't use SSH keys for authentication
 
-If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
+If you don't use SSH keys for authentication, simply remove that whole line (`--mount type=bind,src$HOME/.ssh/id_ed25519,dst=/root/.ssh/id_ed25519,ro`).
 
 To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it …` command), run:
 
@@ -101,7 +122,7 @@ Then, to be asked for the password whenever running an  `ansible-playbook` comma
 
 #### Resolve directory ownership issues
 
-Because you're `root` in the container running Ansible and this likely differs fom the owner (your regular user account) of the playbook directory outside of the container, certain playbook features which use `git` locally may report warnings such as:
+Because you're `root` in the container running Ansible and this likely differs from the owner (your regular user account) of the playbook directory outside of the container, certain playbook features which use `git` locally may report warnings such as:
 
 > fatal: unsafe repository ('/work' is owned by someone else)
 > To add an exception for this directory, call:

docs/assets/obtain_admin_access_token_element_web.png.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
+
+SPDX-License-Identifier: AGPL-3.0-or-later

docs/configuring-captcha.md

@@ -1,3 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Justin Croonenberghs
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 (Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
 
 # Overview
@@ -6,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
@@ -52,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-dns.md

@@ -1,6 +1,23 @@
-# Configuring your DNS settings
+<!--
+SPDX-FileCopyrightText: 2018 - 2024 MDAD project contributors
+SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Edgars Voroboks
+SPDX-FileCopyrightText: 2020 - 2021 Aaron Raimist
+SPDX-FileCopyrightText: 2020 Marcel Partap
+SPDX-FileCopyrightText: 2020 Rónán Duddy
+SPDX-FileCopyrightText: 2021 Yannick Goossens
+SPDX-FileCopyrightText: 2022 Julian Foad
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2023 Johan Swetzén
+SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-<sup>[Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Configuring DNS settings
+
+<sup>[Prerequisites](prerequisites.md) > Configuring DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
 
 To set up Matrix on your domain, you'd need to do some DNS configuration.
 
@@ -9,11 +26,14 @@ To set up Matrix on your domain, you'd need to do some DNS configuration.
 To serve the base domain (`example.com`) and [Element Web](configuring-playbook-client-element-web.md) with the default subdomain, adjust DNS records as below.
 
 | Type  | Host      | Priority | Weight | Port | Target               |
-| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------|
+| ----- | --------- | -------- | ------ | ---- | ---------------------|
-| A     | `matrix`                     | -        | -      | -    | `matrix-server-IP`   |
+| A     | `matrix`  | -        | -      | -    | `matrix-server-IPv4` |
+| AAAA  | `matrix`  | -        | -      | -    | `matrix-server-IPv6` |
 | CNAME | `element` | -        | -      | -    | `matrix.example.com` |
 
-As the table illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your server's IP address (DNS `A` record or `CNAME` record is fine).
+As the table illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your server's IPv4/IPv6 address.
+
+If you don't have IPv6 connectivity yet, you can skip the `AAAA` record. For more details about IPv6, see the [Configuring IPv6](./configuring-ipv6.md) documentation page.
 
 The `element.example.com` subdomain is necessary, because this playbook installs the [Element Web](https://github.com/element-hq/element-web) client for you by default. If you'd rather instruct the playbook not to install Element Web (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.example.com` DNS record.
 

docs/configuring-ipv6.md

@@ -0,0 +1,191 @@
+<!--
+SPDX-FileCopyrightText: 2025 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+# Configuring IPv6
+
+Since 2025-03-08, the [default example configuration](../examples/vars.yml) for the playbook recommends enabling [IPv6](https://en.wikipedia.org/wiki/IPv6) support for Docker's container networks.
+
+**If you have IPv6 support on your server/network** (see [How do I check if my server has IPv6 connectivity?](#how-do-i-check-if-my-server-has-ipv6-connectivity)), then [enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook) would give you:
+
+- 📥 incoming IPv6 connectivity to the server via the server's IPv6 address/addresses (containers won't have their own individual publicly accessible IPs)
+- 📤 outgoing IPv6 connectivity from the server via the server's IPv6 address/addresses (containers won't exit via their own individual IPv6 address)
+- 🔄 IPv6 connectivity for cross-container communication
+
+**If you still don't have IPv6 support on your server/network**, then enabling IPv6 support for the playbook will only enable IPv6 connectivity for cross-container communication and shouldn't affect your server's incoming/outgoing communication. You may also be interested in reading if [there's a performance penalty to enabling IPv6 if the server/network doesn't support IPv6 connectivity?](#is-there-a-performance-penalty-to-enabling-ipv6-if-the-server-network-doesn-t-support-ipv6-connectivity)
+
+As such, **we recommend that you follow the default example configuration and leave IPv6 support for Docker enabled in all cases**.
+
+Enabling IPv6 consists of 2 steps:
+
+- [Enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook)
+- [Configuring DNS records for IPv6](#configuring-dns-records-for-ipv6)
+
+💡 If you've followed a recent version of our documentation, you would have already done these steps, so there's nothing else to do.
+
+## Enabling IPv6 support for the playbook
+
+You can enable IPv6 support for all components' Docker container networks by using the following `vars.yml` configuration:
+
+```yml
+# Controls whether container networks will be created with IPv6 support.
+#
+# If you also have IPv6 support on your server/network and AAAA DNS records pointing to the server,
+# enabling this will effectively give you full public IPv6 connectivity (powered by NAT66).
+#
+# We recommend leaving this enabled even if you don't currently have IPv6 connectivity on your server/network.
+# This way, once you eventually get IPv6 connectivity, you won't have to change anything (besides DNS records).
+#
+# Flipping this setting later on requires manual work (stopping services, deleting and recreating all container networks).
+#
+# In the future, this setting will likely default to `true`, so if you really want IPv6 disabled, explicitly set this to `false`.
+#
+# People managing Docker themselves and running an older Docker version will need additional configuration.
+#
+# Learn more in `docs/configuring-ipv6.md`.
+devture_systemd_docker_base_ipv6_enabled: true
+```
+
+Doing this:
+
+- all container networks will be IPv6-enabled
+
+- NAT66 will be used, so that:
+  - containers will get [Unique Local Addresses (ULA)](https://en.wikipedia.org/wiki/Unique_local_address)
+  - the outgoing IPv6 address for containers will be the same as the one on the server
+  - traffic destined for the IPv6 address of the server will be forwarded to the containers that handle (and publish) that specific port
+
+> [!WARNING]
+> Without enabling this and assuming you have IPv6 `AAAA` DNS records pointing to the server (see [Configuring DNS records for IPv6](#configuring-dns-records-for-ipv6)), IPv6 traffic will still be handled, but NAT64 will be used instead of NAT66.
+> As such, containers will only have an IPv4 address and all IPv6 traffic that reaches them will seem to originate from a local IP. Containers also won't be able to make outgoing (even cross-container) IPv6 requests.
+
+To confirm connectivity, see the following other resources:
+
+- [How do I check if my server has IPv6 connectivity?](#how-do-i-check-if-my-server-has-ipv6-connectivity)
+- [How do I check outgoing IPv6 connectivity for containers?](#how-do-i-check-outgoing-ipv6-connectivity-for-containers)
+- [How do I check incoming IPv6 connectivity for containers?](#how-do-i-check-incoming-ipv6-connectivity-for-containers)
+- [How do I confirm if my container networks are IPv6-enabled?](#how-do-i-confirm-if-my-container-networks-are-ipv6-enabled)
+- Ensure that the [Federation Tester](https://federationtester.matrix.org/) reports that your server is reachable over IPv6.
+
+## Configuring DNS records for IPv6
+
+[Enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook) tells you how to prepare for IPv6 on the container (Docker) side.
+
+For full public IPv6 connectivity (and not just IPv6 connectivity for containers inside the container networks) you also need to **ensure that your domain names** (e.g. `matrix.example.com` and others) have IPv6 (`AAAA`) DNS records pointing to the server's IPv6 address.
+
+Also see the [Configuring DNS settings](configuring-dns.md) documentation page for more details.
+
+### A note about old Docker
+
+With our [default example configuration](../examples/vars.yml), the playbook manages Docker for you and installs a modern-enough version.
+
+Docker versions newer than 27.0.1 enable IPv6 integration at the Docker daemon level out of the box. This still requires that networks are created with IPv6 support as described in the [Enabling IPv6 support for the playbook](#enabling-ipv6-support-for-the-playbook) section above.
+
+**If you're on an old Docker version** (Docker 27.0.0 or older) for some reason, it's likely that your Docker installation is not enabled for IPv6 at all. In such a case:
+
+- if Docker is managed by the playbook, you can tell it to force-enable IPv6 via `devture_systemd_docker_base_ipv6_daemon_options_changing_enabled: true`
+
+- if Docker is managed by you manually, you can add `{"experimental": true, "ip6tables": true}` to the Docker daemon options and restart the Docker service (`docker.service`).
+
+### Frequently Asked Questions
+
+#### How do I check if my server has IPv6 connectivity?
+
+##### With curl
+
+You can run `curl https://icanhazip.com` and see if it returns an [IPv6 address](https://en.wikipedia.org/wiki/IPv6_address) (an address with `:` characters in it, like `2001:db8:1234:5678::1`). If it does, then your server has IPv6 connectivity and prefers it over using IPv4. This is common.
+
+If you see an IPv4 address instead (e.g. `1.2.3.4`), it may be that your server prefers IPv4 over IPv6 or that your network does not support IPv6. You can try forcing `curl` to use IPv6 by running `curl -6 https://icanhazip.com` and see if it returns an IPv6 address.
+
+##### With other network utilities
+
+You can run `ip -6 addr` to see if you have any IPv6 addresses assigned to your server, besides the link-local (`fe80::*`) addresses that everyone has (unless they have force-disabled IPv6 support on their system).
+
+If you do have an IPv6 address, it's still worth [using curl](#with-curl) to confirm that your server can successfully make outgoing requests over IPv6.
+
+#### What does the `devture_systemd_docker_base_ipv6_enabled` setting actually do?
+
+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).
+
+#### I've changed the `devture_systemd_docker_base_ipv6_enabled` setting, but it doesn't seem to have any effect.
+
+If you're using an older Docker version (Docker 27.0.0 or older), see [A note about old Docker](#a-note-about-old-docker).
+
+If you've previously installed with one `devture_systemd_docker_base_ipv6_enabled` value and then changed it to another, you need to:
+
+- stop all services (`just stop-all`)
+- delete all container networks on the server: `docker network rm $(docker network ls -q)`
+- re-run the playbook fully: `just install-all`
+
+#### How do I confirm if my container networks are IPv6-enabled?
+
+You can list container networks by running `docker network ls` on the server.
+
+For each container network (e.g. `matrix-homeserver`), you can check if it has IPv6 connectivity by running a command like this: `docker network inspect matrix-homeserver`.
+
+Ensure that there's an IPv6 subnet/gateway in the `IPAM.Config` section. If yes, you may wish to proceed with [How do I check outgoing IPv6 connectivity for containers?](#how-do-i-check-outgoing-ipv6-connectivity-for-containers)
+
+If there's no IPv6 subnet/gateway in the `IPAM.Config` section, this container network was not created with IPv6 support.
+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).
+
+#### How do I check outgoing IPv6 connectivity for containers?
+
+```sh
+docker run --rm --network=matrix-homeserver quay.io/curl/curl:latest curl -6 https://icanhazip.com
+```
+
+💡 This one-off container is connected to the `matrix-homeserver` container network, not to the default Docker bridge network. The default Docker `bridge` network does not have IPv6 connectivity by default (yet) and is not influenced by the `devture_systemd_docker_base_ipv6_enabled` setting, so using that network (by omitting `--network=..` from the command above) will not show an IPv6 address
+
+✅ If this command returns an IPv6 address, you're all good.
+
+❌ If this command doesn't return an IPv6 address, it may be that:
+
+- your container network does not have IPv6 connectivity. See [How do I confirm if my container networks are IPv6-enabled?](#how-do-i-confirm-if-my-container-networks-are-ipv6-enabled) for more details.
+
+- your server does not have IPv6 connectivity. See [How do I check if my server has IPv6 connectivity?](#how-do-i-check-if-my-server-has-ipv6-connectivity) for more details. If you do have IPv6 connectivity, then the issue is with Docker's IPv6 configuration. Otherwise, you need to check your server's network configuration/firewall/routing and get back to configuring the playbook later on.
+
+#### How do I check incoming IPv6 connectivity for containers?
+
+Only containers that publish ports will be exposed (reachable) publicly on the server's own IPv6 address. Containers will not get their own individual public IPv6 address.
+
+For this playbook, a commonly exposed container is the Traefik reverse-proxy container (unless [you're using your own webserver](./configuring-playbook-own-webserver.md)).
+
+You can either do something like `curl -6 https://matrix.example.com` from an IPv6-enabled host (including the server itself) and see if it works.
+
+An alternative is to use the [IPv6 Port Checker](https://port.tools/port-checker-ipv6/) with a hostname of `matrix.example.com` and a port of `443`.
+
+💡 Trying to connect to `matrix.example.com` via IPv6 requires that you have already [configured the DNS records for IPv6](#configuring-dns-records-for-ipv6) as described above. If you wish to eliminate DNS as a potential issue, you can also try connecting to the server's own IPv6 address directly: `curl -6 -H 'Host: matrix.example.com' https://[2001:db8:1234:5678::1]` (we pass a `Host` header to tell Traefik which host we'd like it to serve).
+
+#### Why enable IPv6 if my network doesn't support it yet?
+
+Because when your network does get support for IPv6 later on (even if that's 5 years away), you won't have to change anything besides [configuring the DNS records for IPv6](#configuring-dns-records-for-ipv6).
+
+#### Can I use a custom subnet for IPv6?
+
+Not easily.
+
+The playbook and the various roles only support passing an `enable_ipv6` flag (`true` or `false` value depending on the `devture_systemd_docker_base_ipv6_enabled` Ansible variable) when creating the Docker container networks.
+
+There's no support for passing a custom subnet for IPv4 and IPv6. We let Docker auto-generate the subnets for us.
+
+You can either create a Pull Request that adds support for this to the various playbook roles, or you can manually recreate the networks from the command-line (e.g. `docker network rm matrix-homeserver && docker network create --ipv6 --subnet=2001:db8:1234:5678::/64 matrix-homeserver`).
+
+#### Can I use Global Unicast Addresses (GUA) for IPv6?
+
+No. You cannot have GUA addresses where each container is individually addressable over the public internet.
+
+The playbook only supports NAT66, which should be good enough for most use cases.
+
+Having containers get IPv6 addresses from your own GUA subnet requires complex configuration (ndp-proxy, etc.) and is not supported.
+
+You may find [this Reddit post](https://www.reddit.com/r/ipv6/comments/1alpzmb/comment/kphpw11/) interesting.
+
+#### Is there a performance penalty to enabling IPv6 if the server/network doesn't support IPv6 connectivity?
+
+Probably a tiny one, as services may try to make (unsuccessful) outgoing requests over IPv6.
+
+In practice, it's probably negligible.

docs/configuring-playbook-alertmanager-receiver.md

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2025 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Prometheus Alertmanager integration via matrix-alertmanager-receiver (optional)
 
 The playbook can install and configure the [matrix-alertmanager-receiver](https://github.com/metio/matrix-alertmanager-receiver) service for you. It's a [client](https://prometheus.io/docs/alerting/latest/clients/) for Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), allowing you to deliver alerts to Matrix rooms.
@@ -26,7 +34,8 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertma
 
 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.
+> [!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.
 
 ### Join to rooms as the bot manually
 
@@ -65,8 +74,6 @@ matrix_alertmanager_receiver_config_matrix_room_mapping:
   some-room-name: "!qporfwt:{{ matrix_domain }}"
 ```
 
-See `roles/custom/matrix-alertmanager-receiver/defaults/main.yml` for additional configuration variables.
-
 ### Adjusting the matrix-alertmanager-receiver URL (optional)
 
 By tweaking the `matrix_alertmanager_receiver_hostname` and `matrix_alertmanager_receiver_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
@@ -83,22 +90,27 @@ If you've changed the default hostname, you may need to create a CNAME record fo
 
 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-alertmanager-receiver/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-alertmanager-receiver/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_alertmanager_receiver_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,ensure-matrix-users-created,start
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -122,3 +134,16 @@ route:
 ```
 
 where `URL_HERE` looks like `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name` or `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!qporfwt:example.com`.
+
+## 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-alertmanager-receiver`.
+
+### 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, warn, info, debug
+matrix_alertmanager_receiver_container_process_argument_log_level: debug
+```

docs/configuring-playbook-appservice-double-puppet.md

@@ -1,3 +1,10 @@
+<!--
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Appservice Double Puppet (optional)
 
 The playbook can install and configure the Appservice Double Puppet service for you. It is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
@@ -28,16 +35,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 

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

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2024 - 2026 Catalan Lover <catalanlover@protonmail.com>
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Draupnir for All/D4A (optional)
 
 The playbook can install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool for you in appservice mode.
@@ -6,59 +14,88 @@ 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).
 
-As noted in the Draupnir install instructions the control room is sensitive. **Anyone in this room can control the bot so it is important that you only invite trusted users to this room.**
+> [!WARNING]
-
+> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
-### Set an alias to the management room
-
-Next, set an alias to the management 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_master_control_room_alias: "MANAGEMENT_ROOM_ALIAS_HERE"
+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
+
+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
 
-You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable.
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-appservice-draupnir-for-all/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_appservice_draupnir_for_all_configuration_extension_yaml` variable
 
 For example, to change Draupnir's `protectAllJoinedRooms` option to `true`, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_appservice_draupnir_for_all_extension_yaml: |
+matrix_appservice_draupnir_for_all_configuration_extension_yaml: |
   # Your custom YAML configuration goes here.
-  # This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_yaml`).
+  # This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_configuration_yaml`).
   #
   # You can override individual variables from the default configuration, or introduce new ones.
   #
   # If you need something more special, you can take full control by
-  # completely redefining `matrix_appservice_draupnir_for_all_yaml`.
+  # completely redefining `matrix_appservice_draupnir_for_all_configuration_yaml`.
   protectAllJoinedRooms: true
 ```
 
@@ -87,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 succesfully 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` recomendation. Using the chat is recomended.
+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-backup-borg.md

@@ -1,143 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 - 2025 Nikita Chernyi
+SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up BorgBackup (optional)
 
 The playbook can install and configure [BorgBackup](https://www.borgbackup.org/) (short: Borg) with [borgmatic](https://torsion.org/borgmatic/) for you.
 
 BorgBackup is a deduplicating backup program with optional compression and encryption. That means your daily incremental backups can be stored in a fraction of the space and is safe whether you store it at home or on a cloud service.
 
-## Prerequisites
+The [Ansible role for BorgBackup](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg) 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 BorgBackup, you can check them via:
-
+- 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/main/docs/configuring-backup-borg.md) online
-### Set up a remote server for storing backups
+- 📁 `roles/galaxy/backup_borg/docs/configuring-backup-borg.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
-
-You will need a remote server where BorgBackup will store the backups. There are hosted, BorgBackup compatible solutions available, such as [BorgBase](https://www.borgbase.com).
-
-### Check the Postgres version
-
-By default, if you're using the integrated Postgres database server (as opposed to [an external Postgres server](configuring-playbook-external-postgres.md)), backups with BorgBackup will also include dumps of your Postgres database.
-
-Unless you disable the Postgres-backup support, make sure that the Postgres version of your homeserver's database is compatible with borgmatic. You can check the compatible versions [here](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/main/defaults/main.yml).
-
-An alternative solution for backing up the Postgres database is [postgres backup](configuring-playbook-postgres-backup.md). If you decide to go with another solution, you can disable Postgres-backup support for BorgBackup using the `backup_borg_postgresql_enabled` variable.
-
-### Create a new SSH key
-
-Run the command below on any machine to create a new SSH key:
-
-```sh
-ssh-keygen -t ed25519 -N '' -f matrix-borg-backup -C matrix
-```
-
-You don't need to place the key in the `.ssh` folder.
-
-### Add the public key
-
-Next, add the **public** part of this SSH key (the `matrix-borg-backup.pub` file) to your BorgBackup provider/server.
-
-If you are using a hosted solution, follow their instructions. If you have your own server, copy the key to it with the command like below:
-
-```sh
-# Example to append the new PUBKEY contents, where:
-# - PUBKEY is path to the public key
-# - USER is a ssh user on a provider / server
-# - HOST is a ssh host of a provider / server
-cat PUBKEY | ssh USER@HOST 'dd of=.ssh/authorized_keys oflag=append conv=notrunc'
-```
-
-The **private** key needs to be added to `backup_borg_ssh_key_private` on your `inventory/host_vars/matrix.example.com/vars.yml` file as below.
-
-## Adjusting the playbook configuration
-
-To enable BorgBackup, add the following configuration to your `vars.yml` file (adapt to your needs):
-
-```yaml
-backup_borg_enabled: true
-
-# Set the repository location, where:
-# - USER is a ssh user on a provider / server
-# - HOST is a ssh host of a provider / server
-# - REPO is a BorgBackup repository name
-backup_borg_location_repositories:
- - ssh://USER@HOST/./REPO
-
-# Generate a strong password used for encrypting backups. You can create one with a command like `pwgen -s 64 1`.
-backup_borg_storage_encryption_passphrase: "PASSPHRASE"
-
-# Add the content of the **private** part of the SSH key you have created.
-# Note: the whole key (all of its belonging lines) under the variable needs to be indented with 2 spaces.
-backup_borg_ssh_key_private: |
-  -----BEGIN OPENSSH PRIVATE KEY-----
-  TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
-  xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
-  bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
-  RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
-  ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
-  -----END OPENSSH PRIVATE KEY-----
-```
-
-**Note**: `REPO` will be initialized on backup start, for example: `matrix`. See [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls) for the syntax.
-
-### Set backup archive name (optional)
-
-You can specify the backup archive name format. To set it, add the following configuration to your `vars.yml` file (adapt to your needs):
-
-```yaml
-backup_borg_storage_archive_name_format: matrix-{now:%Y-%m-%d-%H%M%S}
-```
-
-### Configure retention policy (optional)
-
-It is also possible to configure a retention strategy. To configure it, add the following configuration to your `vars.yml` file (adapt to your needs):
-
-```yaml
-backup_borg_retention_keep_hourly: 0
-backup_borg_retention_keep_daily: 7
-backup_borg_retention_keep_weekly: 4
-backup_borg_retention_keep_monthly: 12
-backup_borg_retention_keep_yearly: 2
-```
-
-### Edit the backup schedule (optional)
-
-By default the backup will run 4 a.m. every day based on the `backup_borg_schedule` variable. It is defined in the format of systemd timer calendar.
-
-To edit the schedule, add the following configuration to your `vars.yml` file (adapt to your needs):
-
-```yaml
-backup_borg_schedule: "*-*-* 04:00:00"
-```
-
-**Note**: the actual job may run with a delay. See `backup_borg_schedule_randomized_delay_sec` [here](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/f5d5b473d48c6504be10b3d946255ef5c186c2a6/defaults/main.yml#L50) for its default value.
-
-### Set include and/or exclude directories (optional)
-
-`backup_borg_location_source_directories` defines the list of directories to back up. It's set to `{{ matrix_base_data_path }}` by default, which is the base directory for every service's data, such as Synapse, Postgres and the bridges.
-
-You might also want to exclude certain directories or file patterns from the backup using the `backup_borg_location_exclude_patterns` variable.
-
-### Extending the configuration
-
-There are some additional things you may wish to configure about the component.
-
-Take a look at:
-
-- [backup_borg role](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg)'s [`defaults/main.yml`](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg/blob/main/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 `backup_borg_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
-```
-
-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.
-
-## Manually start a backup
-
-Sometimes it can be helpful to run the backup as you'd like, avoiding to wait until 4 a.m., like when you test your configuration.
-
-If you want to run the backup immediately, log in to the server with SSH and run `systemctl start matrix-backup-borg`.
-
-This will not return until the backup is done, so it can possibly take a long time. Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

docs/configuring-playbook-base-domain-serving.md

@@ -1,3 +1,10 @@
+<!--
+SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Serving the base domain (optional)
 
 By default, this playbook sets up services on your Matrix server (`matrix.example.com`), but has it configured so that it presents itself as the base domain (`example.com`). To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up server delegation / redirection.

docs/configuring-playbook-bot-baibot.md

@@ -1,3 +1,10 @@
+<!--
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up baibot (optional)
 
 <p align="center">
@@ -7,7 +14,7 @@
 
 🤖 [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.
 
@@ -32,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`.
 #
@@ -123,7 +149,7 @@ Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is op
 
 You are **not required** to define agents [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration) via Ansible. **To get started quickly**, you can **skip this section and define agents at runtime via chat commands** (following the bot's guidance).
 
-Privileged users (like the [👮‍♂️ Administrator](#️-administrator-configuration), but potentially others too - see the upstream [🔒 access](https://github.com/etkecc/baibot/blob/main/docs/access.md) documentation) can **define agents dynamically at any time** via chat commands.
+Privileged users (like the [👮‍♂️ Administrator](#️-administrator-configuration), but potentially others too — see the upstream [🔒 access](https://github.com/etkecc/baibot/blob/main/docs/access.md) documentation) can **define agents dynamically at any time** via chat commands.
 
 The Ansible role includes preset variables for easily enabling some [🤖 agents](https://github.com/etkecc/baibot/blob/main/docs/agents.md) on various [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md) (e.g. OpenAI, etc).
 
@@ -133,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
 
@@ -235,7 +292,13 @@ matrix_bot_baibot_config_agents_static_definitions_openai_config_api_key: "YOUR_
 # matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
 
 # If you'd like to use another text-generation agent, uncomment and adjust:
-# matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_model_id: gpt-4o
+# matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_model_id: gpt-4.1
+
+# Uncomment below to enable OpenAI's built-in tools.
+# These tools are disabled by default. Enabling them may incur additional costs.
+# See: https://github.com/etkecc/baibot/blob/61d18b2/docs/features.md#%EF%B8%8F-built-in-tools-openai-only
+# matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_tools_web_search: true
+# matrix_bot_baibot_config_agents_static_definitions_openai_config_text_generation_tools_code_interpreter: true
 ```
 
 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/openai`.
@@ -250,7 +313,7 @@ You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot
 
 This provider allows you to use OpenAI-compatible API services like [OpenRouter](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openrouter), [Together AI](https://github.com/etkecc/baibot/blob/main/docs/providers.md#together-ai), etc.
 
-Some of these popular services already have **shortcut** providers (see [supported providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md#supported-providers) leading to this one behind the scenes - this make it easier to get started.
+Some of these popular services already have **shortcut** providers (see [supported providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md#supported-providers) leading to this one behind the scenes — this make it easier to get started.
 
 As of this moment, the playbook does not include presets for any of these services, so you'll need to [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset).
 
@@ -305,7 +368,7 @@ Because these are [statically](https://github.com/etkecc/baibot/blob/main/docs/c
 
 💡 To figure out what to put in the `config` section, refer to the [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md) page, which contains **sample configuration YAML for each provider**.
 
-As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md), defining them means they exist. To actually make use of them, they need to be configured as handlers globally or in a specific room - see [Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models).
+As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md), defining them means they exist. To actually make use of them, they need to be configured as handlers globally or in a specific room — see [Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models).
 
 💡 You may also wish to use these new agents for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
 
@@ -342,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.
@@ -374,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
 
@@ -396,11 +461,13 @@ Send `!bai help` to the bot in the room to see the available commands.
 
 You can also refer to the upstream [baibot](https://github.com/etkecc/baibot) project's documentation.
 
-## Debugging
+## Troubleshooting
 
-As with all other services, you can find service logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-bot-baibot`
+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-baibot`.
 
-The default logging level for this service is `info`, but you can increase it to `debug` (or even `trace`) with the following additional configuration:
+### Increase logging verbosity
+
+The default logging level for this service is `info`. If you want to increase the verbosity to `debug` (or even `trace`), add the following configuration to your `vars.yml` file and re-run the playbook:
 
 ```yaml
 # Adjust the bot's own logging level.

docs/configuring-playbook-bot-buscarron.md

@@ -1,9 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Buscarron (optional)
 
 The playbook can install and configure [Buscarron](https://github.com/etkecc/buscarron) for you.
 
 Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.
 
+See the project's [documentation](https://github.com/etkecc/buscarron/blob/main/README.md) to learn what it does and why it might be useful to you.
+
 ## Adjusting DNS records
 
 By default, this playbook installs Buscarron on the `buscarron.` subdomain (`buscarron.example.com`) and requires you to create a CNAME record for `buscarron`, which targets `matrix.example.com`.
@@ -54,6 +64,14 @@ After changing the domain, **you may need to adjust your DNS** records to point
 
 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-buscarron/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
 ## 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:
@@ -71,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
 
@@ -95,4 +113,14 @@ Here is an example for the `contact` form:
 
 If you get banned, you'd need to restart the process by running the playbook with `--tags=start` or running `systemctl restart matrix-bot-buscarron` on the server.
 
-You can also refer to the upstream [documentation](https://github.com/etkecc/buscarron).
+## 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-buscarron`.
+
+### 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
+matrix_bot_buscarron_loglevel: DEBUG
+```

docs/configuring-playbook-bot-chatgpt.md

@@ -1,77 +1,25 @@
-# Setting up matrix-bot-chatgpt (optional, unmaintained)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2023 - 2024 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-**Note**: [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) is now an archived (**unmaintained**) project. Talking to ChatGPT (and many other LLM providers) can happen via the much more featureful [baibot](https://github.com/etkecc/baibot), which can be installed using [this playbook](configuring-playbook-bot-baibot.md). Consider using that bot instead of this one.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-The playbook can install and configure [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) for you.
+# Setting up matrix-chatgpt-bot (optional, removed)
 
-Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client!
+🪦 The playbook used to be able to install and configure [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot), but no longer includes this component.
 
-## Prerequisites
+While not a 1:1 replacement, the bot'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).
 
-### Obtain an OpenAI API key
+## Uninstalling matrix-chatgpt-bot manually
 
-To use the bot, you'd need to obtain an API key from [https://platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys).
+If you still have the matrix-chatgpt-bot 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:
-
-### 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):
 
 ```sh
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+systemctl disable --now matrix-bot-chatgpt.service
+
+rm -rf /matrix/chatgpt
 ```
-
-### Obtain an access token and create encryption keys
-
-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.
-
-To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [Element documentation](https://element.io/help#encryption6).
-
-## 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 `API_KEY_HERE` with the API key retrieved [here](#obtain-an-openai-api-key) and `ACCESS_TOKEN_HERE` with the access token created [here](#obtain-an-access-token-and-create-encryption-keys), respectively.
-
-```yaml
-matrix_bot_chatgpt_enabled: true
-
-matrix_bot_chatgpt_openai_api_key: 'API_KEY_HERE'
-
-# Uncomment and adjust this part if you'd like to use a username different than the default
-# matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt'
-
-matrix_bot_chatgpt_matrix_access_token: 'ACCESS_TOKEN_HERE'
-
-# Configuring the system promt used, needed if the bot is used for special tasks.
-# More information: https://github.com/mustvlad/ChatGPT-System-Prompts
-matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.'
-```
-
-## 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.
-
-## Usage
-
-To use the bot, invite it to the room you specified on your `vars.yml` file (`/invite @bot.chatgpt:example.com` where `example.com` is your base domain, not the `matrix.` domain).
-
-After the bot joins the room, you can send a message to it. When you do so, use the prefix if you configured it or mention the bot.
-
-You can also refer to the upstream [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot).

docs/configuring-playbook-bot-draupnir.md

@@ -1,3 +1,13 @@
+<!--
+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
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Draupnir (optional)
 
 The playbook can install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation bot for you.
@@ -6,48 +16,85 @@ 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 skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
+If your 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)
 
-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. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
+As of Draupnir 3.1.0, Zero Touch Deployment of Draupnir bot mode requires you to supply the following:
 
-If you make the management room encrypted (E2EE), then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
+- 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.
 
-Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`.
+Zero Touch Deployment is the officially preferred installation method for new deployments of Draupnir as of 3.1.0.
 
-Finally invite the `@bot.draupnir:example.com` account that the playbook will create for you to the management room. Please note that clients can issue a warning that your attempting to invite a user that doesnt have a profile and might not exist. This warning is expected as your inviting the bot before its user account exists.
+### 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.
+
+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
 
-Decide whether you want to support having an Encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled.
+Decide whether you want to support having an encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled.
 
-Refer to Draupnir's [Documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more information on why you might or might not care about encryption support for protected rooms.
+Refer to Draupnir's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more details about why you might want to care about encryption support for protected rooms.
 
-**Note**: Draupnir does not support running with Pantalaimon as it would break all workflows that involve answering prompts with reactions.
+### Disable Pantalaimon for Draupnir (since v2.0.0; optional)
+
+It is known that running Draupnir along with Pantalaimon breaks all workflows that involve answering prompts with reactions.
+
+If you are updating Draupnir from v1.x.x and have enabled Pantalaimon for it, you can disable Pantalaimon in favor of the native E2EE support. To disable Pantalaimon, remove the configuration `matrix_bot_draupnir_pantalaimon_use: true` from your `vars.yml` file.
+
+**Note**: because the management room is still encrypted, disabling it without enabling the native E2EE support will break the management room.
 
 ### Native E2EE support
 
-To enable the native E2EE support, you need to obtain an access token for Draupnir.
+To enable the native E2EE support, you need to obtain an access token for Draupnir and set it on your `vars.yml` file.
 
 Note that native E2EE requires a clean access token that has not touched E2EE so curl is recommended as a method to obtain it. **The access token obtained via Element Web does not work with it**. Refer to the documentation on [how to obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl).
 
-To enable the native E2EE support, add the following configuration to your `vars.yml` file:
+To enable the native E2EE support, add the following configuration to your `vars.yml` file. Make sure to replace `CLEAN_ACCESS_TOKEN_HERE` with the access token you obtained just now.
 
 ```yaml
-# Enables the native E2EE Support
+# Enables the native E2EE support
-matrix_bot_draupnir_enable_experimental_rust_crypto: true
+matrix_bot_draupnir_config_experimentalRustCrypto: true
 
-# Access Token the bot uses to login.
+# Access token which the bot will use for logging in.
 # Comment out `matrix_bot_draupnir_login_native` when using this option.
-matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"
+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`.
+### 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
@@ -57,47 +104,82 @@ matrix_bot_draupnir_enabled: true
 # matrix_bot_draupnir_login: bot.draupnir
 
 # Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
-# If creating the user on your own and using `matrix_bot_draupnir_access_token` to login you can comment out this line.
+# If creating the user on your own and using `matrix_bot_draupnir_config_accessToken` to login you can comment out this line.
 matrix_bot_draupnir_password: PASSWORD_FOR_THE_BOT
 
-# Comment out if using `matrix_bot_draupnir_enable_experimental_rust_crypto: true` or `matrix_bot_draupnir_access_token` to login.
+# Comment out if using `matrix_bot_draupnir_config_experimentalRustCrypto: true` or `matrix_bot_draupnir_config_accessToken` to login.
 matrix_bot_draupnir_login_native: true
 
-matrix_bot_draupnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
+matrix_bot_draupnir_config_managementRoom: "MANAGEMENT_ROOM_ID_HERE"
 ```
 
-Before Proceeding run the playbook with the following command to make sure the Draupnir user has been created.
+### 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.
+
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created
 ```
 
-### Make sure the account is free from rate limiting
+**Note**: the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a heavily recomended step. If you do not configure it, Draupnir performance will be degraded.**
+Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
+
+### 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.**
 
 This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally.
 
-To expose the APIs publicly, add the following configuration to your `vars.yml` file:
+**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 [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
+
+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
 ```
 
-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).
+#### Obtain an access token for admin account
 
-**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).
+Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
-To discharge rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.draupnir:example.com` with the MXID of your Draupnir:
+> [!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.
+
+#### Run the `curl` command
+
+To disable rate limiting, run the following command on systems that ship curl. Before running it, make sure to replace:
+
+- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account
+- `example.com` with your base domain
+- `@bot.draupnir:example.com` with the MXID of your Draupnir bot user
 
 ```sh
-curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit
+curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit
 ```
 
-### Obtain an access token
+**Notes**:
 
-Manual access to Synapse's Admin API requires an access token. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+- 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.
-⚠️ **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.
 
 ### Abuse Reports
 
@@ -106,18 +188,37 @@ Draupnir can receive reports in the management room.
 The bot can intercept the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver. If you are using Traefik, this playbook can set this up for you:
 
 ```yaml
-matrix_bot_draupnir_abuse_reporting_enabled: true
+matrix_bot_draupnir_config_web_abuseReporting: true
 ```
 
-<!--
+### Enabling synapse-http-antispam support
-NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
 
-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. 
+Certain protections in Draupnir require the [synapse-http-antispam](https://github.com/maunium/synapse-http-antispam) module and a Synapse homeserver plus homeserver admin status to function. This module can be enabled in the playbook via setting `matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled` to `true` and making sure that Draupnir admin API access is enabled.
--->
+
+```yaml
+# Enables the integration between Draupnir and synapse-http-antispam module.
+matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled: true
+
+# Enables draupnir to access Synapse admin APIs. This is required for the module functionality to take full effect.
+matrix_bot_draupnir_admin_api_enabled: true
+```
+
+These protections need to be manually activated. Consulting the [enabling protections](#enabling-built-in-protections) guide and/or upstream documentation can be helpful.
+
+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:
+
+```yaml
+matrix_bot_draupnir_configuration_extension_yaml: |
+  pollReports: true
+```
 
 ### Extending the configuration
 
-You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable.
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-draupnir/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_draupnir_configuration_extension_yaml` variable
 
 For example, to change Draupnir's `acceptInvitesFromSpace` option to `!qporfwt:example.com`, add the following configuration to your `vars.yml` file:
 
@@ -137,7 +238,7 @@ matrix_bot_draupnir_configuration_extension_yaml: |
 
 Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable Mjolnir if you're doing migration.
 
-Note that Pantalaimon is unsupported by Draupnir so it is recommended to consult the instructions to enable [the native E2EE support](#native-e2ee-support).
+Note that Draupnir supports E2EE natively, so you can enable it instead of Pantalaimon. It is recommended to consult the instruction [here](#native-e2ee-support).
 
 That is all you need to do due to that Draupnir can complete migration on its own.
 
@@ -158,6 +259,8 @@ 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 [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_draupnir_password` to let the bot know its new password.
+
 ## Usage
 
 You can refer to the upstream [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) for additional ways to use and configure Draupnir and for a more detailed usage guide.
@@ -186,9 +289,12 @@ For Draupnir to do its job, you need to [give it permissions](https://the-draupn
 
 We recommend **subscribing to a public [policy list](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists)** using the [watch command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists#using-draupnirs-watch-command-to-subscribe-to-policy-rooms).
 
-Polcy lists are maintained in Matrix rooms. A popular policy list is maintained in the public `#community-moderation-effort-bl:neko.dev` room.
+Policy lists are maintained in Matrix rooms. Popular ones maintained in the public are:
 
-You can tell Draupnir to subscribe to it by sending the following command to the Management Room: `!draupnir watch #community-moderation-effort-bl:neko.dev`
+- `#community-moderation-effort-bl:neko.dev`
+- `#huginn-muninn-active-threats:feline.support`
+
+You can tell Draupnir to subscribe to each of these by sending the following command to the Management Room: `!draupnir watch POLICY_LIST_ADDRESS_HERE` (e.g. `!draupnir watch #community-moderation-effort-bl:neko.dev`)
 
 #### Creating your own policy lists and rules
 
@@ -203,7 +309,7 @@ The simplest and most useful entity to target is `user`. Below are a few example
 To create rules, you run commands in the Management Room (**not** in the policy list room).
 
 - (ban a single user on a given homeserver): `!draupnir ban @charles:example.com my-bans Rude to others`
-- (ban all users on a given homeserver by using a [wildcard](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#wildcards)): `!draupnir ban @*:example.org my-bans Spam server - all users are fake`
+- (ban all users on a given homeserver by using a [wildcard](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#wildcards)): `!draupnir ban @*:example.org my-bans Spam server, all users are fake`
 
 As a result of running these commands, you may observe:
 
@@ -214,14 +320,14 @@ You can undo bans with the [unban command](https://the-draupnir-project.github.i
 
 ### Enabling built-in protections
 
-You can also **turn on various built-in [protections](https://the-draupnir-project.github.io/draupnir-documentation/protections)** like `JoinWaveShortCircuit` ("If X amount of users join in Y time, set the room to invite-only").
+You can also **turn on various built-in [protections](https://the-draupnir-project.github.io/draupnir-documentation/protections)** like `JoinWaveShortCircuitProtection` ("If X amount of users join in Y time, set the room to invite-only").
 
 To **see which protections are available and which are enabled**, send a `!draupnir protections` command to the Management Room.
 
-To **see the configuration options for a given protection**, send a `!draupnir protections show PROTECTION_NAME` (e.g. `!draupnir protections show JoinWaveShortCircuit`).
+To [**see the configuration options for a given protection**](https://the-draupnir-project.github.io/draupnir-documentation/protections/configuring-protections#displaying-the-protection-settings), send a `!draupnir protections show PROTECTION_NAME` (e.g. `!draupnir protections show JoinWaveShortCircuitProtection`).
 
-To **set a specific option for a given protection**, send a command like this: `!draupnir config set PROTECTION_NAME.OPTION VALUE` (e.g. `!draupnir config set JoinWaveShortCircuit.timescaleMinutes 30`).
+To [**set a specific option for a given protection**](https://the-draupnir-project.github.io/draupnir-documentation/protections/configuring-protections#changing-protection-settings), send a command like this: `!draupnir protections config set PROTECTION_NAME OPTION VALUE` (e.g. `!draupnir protections config set JoinWaveShortCircuitProtection timescaleMinutes 30`).
 
-To **enable a given protection**, send a command like this: `!draupnir enable PROTECTION_NAME` (e.g. `!draupnir enable JoinWaveShortCircuit`).
+To [**enable a given protection**](https://the-draupnir-project.github.io/draupnir-documentation/protections/block-invitations-on-server-protection#enabling-the-protection), send a command like this: `!draupnir protections enable PROTECTION_NAME` (e.g. `!draupnir protections enable JoinWaveShortCircuitProtection`).
 
-To **disable a given protection**, send a command like this: `!draupnir disable PROTECTION_NAME` (e.g. `!draupnir disable JoinWaveShortCircuit`).
+To **disable a given protection**, send a command like this: `!draupnir protections disable PROTECTION_NAME` (e.g. `!draupnir protections disable JoinWaveShortCircuitProtection`).

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

@@ -1,247 +1,26 @@
-# Setting up Go-NEB (optional, unmaintained)
+<!--
+SPDX-FileCopyrightText: 2019-2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Yannick Goossens
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2023-2025 MDAD project contributors
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
 
-**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.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
+# Setting up Go-NEB (optional, removed)
 
-Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
+🪦 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.
 
-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.
+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).
 
-## Prerequisites
+## Uninstalling Go-NEB manually
 
-### Register the bot account
+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:
-
-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):
 
 ```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.
-
-## 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,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.
-
-## 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).

docs/configuring-playbook-bot-honoroit.md

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Honoroit (optional)
 
 The playbook can install and configure [Honoroit](https://github.com/etkecc/honoroit) for you.
@@ -45,6 +53,14 @@ If you've changed the default hostname, you may need to create a CNAME record fo
 
 When setting, replace `example.com` with your own.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-honoroit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
 ## 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:
@@ -62,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
 
@@ -73,3 +89,15 @@ After the bot joins the room, any Matrix user can send a message to it to start
 Send `!ho help` to the bot in the room to see the available commands.
 
 You can also refer to the upstream [documentation](https://github.com/etkecc/honoroit#features).
+
+## 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-honoroit`.
+
+### Increase logging verbosity
+
+If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_bot_honoroit_loglevel: 'DEBUG'
+```

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

@@ -1,65 +1,34 @@
-# Setting up matrix-registration-bot (optional)
+<!--
+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: 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
 
-The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-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.
+# Setting up matrix-registration-bot (optional, removed)
 
-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.
+🪦 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.
 
-## Adjusting the playbook configuration
+## Uninstalling the component manually
 
-To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+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:
-
-```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
-```
-
-The bot account will be created automatically.
-
-## 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 [troublshooting 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:
 
 ```sh
-just run-tags bot-matrix-registration-bot-clean-cache
+systemctl disable --now matrix-bot-matrix-registration-bot.service
+
+rm -rf /matrix/matrix-registration-bot
 ```

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

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up matrix-reminder-bot (optional)
 
 The playbook can install and configure [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for you.
@@ -23,6 +31,15 @@ matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
 matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
 ```
 
+### 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-reminder-bot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bot-matrix-reminder-bot/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_matrix_reminder_bot_configuration_extension_yaml` variable
+
 ## Installing
 
 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@@ -40,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
 
@@ -53,3 +70,18 @@ Basic usage is like this: `!remindme in 2 minutes; This is a test`
 Send `!help reminders` to the room to see the bot's help menu for additional commands.
 
 You can also refer to the upstream [Usage documentation](https://github.com/anoadragon453/matrix-reminder-bot#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-bot-matrix-reminder-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
+matrix_bot_matrix_reminder_bot_configuration_extension_yaml: |
+  logging:
+    # Valid values: ERROR, WARNING, INFO, DEBUG
+    level: DEBUG
+```

docs/configuring-playbook-bot-maubot.md

@@ -1,3 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Fabio Bonelli
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up maubot (optional)
 
 The playbook can install and configure [maubot](https://github.com/maubot/maubot) for you.
@@ -47,6 +58,15 @@ If you've changed the default hostname, you may need to create a CNAME record fo
 
 When setting, replace `example.com` with your own.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-maubot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bot-maubot/templates/config.yaml.j2` for the bot's default configuration
+
 ## Customizing the maubot container image
 
 Certain [maubot plugins](https://plugins.mau.bot/) require additional dependencies to be installed.
@@ -83,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
 
@@ -100,4 +120,18 @@ This can be done via `mbc login` then `mbc auth` (see the [maubot documentation]
 
 Alternatively, you can refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). Be aware that you'd better use the **Obtain an access token via curl** method (not **Obtain an access token via Element Web**) as the latter will causes issues to your bot in encrypted rooms. Read [more](https://docs.mau.fi/maubot/usage/basic.html#creating-clients).
 
-⚠️ **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.
+> [!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.
+
+## 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-maubot`.
+
+### 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
+# Valid values: CRITICAL, ERROR, WARNING, INFO, DEBUG
+matrix_bot_maubot_logging_level: DEBUG
+```

docs/configuring-playbook-bot-mjolnir.md

@@ -1,3 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2024 MDAD project contributors
+SPDX-FileCopyrightText: 2021 Aaron Raimist
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Marko Weltzer
+SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mjolnir (optional)
 
 The playbook can install and configure the [Mjolnir](https://github.com/matrix-org/mjolnir) moderation bot for you.
@@ -24,7 +35,8 @@ If you would like Mjolnir to be able to deactivate users, move aliases, shutdown
 
 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.
+> [!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.
 
 ### Make sure the account is free from rate limiting
 
@@ -32,37 +44,57 @@ If your homeserver's implementation is Synapse, you will need to prevent it from
 
 This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally.
 
+**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 [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 `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
 ```
 
-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).
+#### Obtain an access token for admin account
 
-**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).
+Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). If you have made Mjolnir an admin, you can just use the Mjolnir token.
 
-To discharge rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.mjolnir:example.com` with the MXID of your Mjolnir:
+> [!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.
+
+#### Run the `curl` command
+
+To disable rate limiting, run the following command on systems that ship curl. Before running it, make sure to replace:
+
+- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account
+- `example.com` with your base domain
+- `@bot.mjolnir:example.com` with the MXID of your Mjolnir bot user
 
 ```sh
-curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit
+curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit
 ```
 
-You can obtain an access token for a homeserver admin account in the same way as you can do so for Mjolnir itself. If you have made Mjolnir an admin, you can just use the Mjolnir token.
+**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.
 
 ### Create a management room
 
-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. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
+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.
 
-If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)).
+> [!WARNING]
+> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
 
-Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`.
+It is possible to make the management room encrypted (E2EE). If doing so, then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)).
+
+Once you have created the room you need to copy the room ID so you can specify it on your `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`.
 
 Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room.
 
 ## 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`.
+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 just now.
 
 ```yaml
 # Enable Mjolnir
@@ -131,7 +163,11 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
 
 ### Extending the configuration
 
-You can configure additional options by adding the `matrix_bot_mjolnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-mjolnir/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_mjolnir_configuration_extension_yaml` variable
 
 For example, to change Mjolnir's `recordIgnoredInvites` option to `true`, add the following configuration to your `vars.yml` file:
 
@@ -153,19 +189,31 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,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 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
 
 You can refer to the upstream [documentation](https://github.com/matrix-org/mjolnir) for additional ways to use and configure Mjolnir. Check out their [quickstart guide](https://github.com/matrix-org/mjolnir#quickstart-guide) for some basic commands you can give to the bot.
+
+## 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-mjolnir`.
+
+### 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, WARN, INFO, DEBUG
+matrix_bot_mjolnir_configuration_extension_yaml: |
+  logLevel: "DEBUG"
+```

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

@@ -1,6 +1,15 @@
+<!--
+SPDX-FileCopyrightText: 2019 - 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 - 2023 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Jim Myhrberg
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Appservice Discord bridging (optional)
 
-**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.
+**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge supported by the playbook.
 - For using as a Bot we are recommend the Appservice Discord bridge (the one being discussed here), because it supports plumbing.
 - For personal use we recommend the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge, because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
 
@@ -17,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_bridge_appservice_discord_enabled: true
-matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
+matrix_bridge_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
-matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
+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.
@@ -28,29 +37,35 @@ matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
 #   use_appservice_legacy_authorization: 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-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_bridge_appservice_discord_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,ensure-matrix-users-created,start
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
 
-- 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.
 
 ## Self-Service Bridging (Manual)
 
 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.
@@ -76,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.
 
@@ -99,3 +114,18 @@ There's the Discord bridge's guide for [setting privileges on bridge managed roo
 docker exec -it matrix-appservice-discord \
 /bin/sh -c 'cp /cfg/registration.yaml /tmp/discord-registration.yaml && cd /tmp && node /build/tools/adminme.js -c /cfg/config.yaml -m "!qporfwt:example.com" -u "@alice:example.com" -p 100'
 ```
+
+## 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-discord`.
+
+### 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 (adapt to your needs) and re-run the playbook:
+
+```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

@@ -1,3 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2019 - 2021 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 MDAD project contributors
+SPDX-FileCopyrightText: 2020 Lee Verberne
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Appservice IRC bridging (optional)
 
 **Note**: bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) can also happen via the [Heisenbridge](configuring-playbook-bridge-heisenbridge.md) bridge supported by the playbook.
@@ -11,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
@@ -60,23 +69,48 @@ matrix_appservice_irc_ircService_servers:
       lineLimit: 3
 ```
 
+### 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-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_bridge_appservice_irc_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,ensure-matrix-users-created,start
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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 `@irc_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+## 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-irc`.
+
+### Configuring for logging
+
+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_bridge_appservice_irc_configuration_extension_yaml: |
+  logging:
+    # Level to log on console/logfile.
+    # Valid values: error, warn, info, debug
+    level: "debug"
+    # The file location to log to. This is relative to the project directory.
+    logfile: "debug.log"
+    # The file location to log errors to. This is relative to the project directory.
+    errfile: "errors.log"
+```

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

@@ -1,57 +1,26 @@
-# Setting up Appservice Kakaotalk bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 - 2026 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 MDAD project contributors
 
-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.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-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.
+# Setting up Appservice Kakaotalk bridging (optional, removed)
 
-⚠️ **Warning**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
+🪦 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.
 
-## Prerequisite (optional)
+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.
 
-### Enable Shared Secret Auth
+## Uninstalling the component manually
 
-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.
+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:
 
-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,ensure-matrix-users-created,start
+systemctl disable --now matrix-appservice-kakaotalk.service
+
+systemctl disable --now matrix-appservice-kakaotalk-node.service
+
+rm -rf /matrix/appservice-kakaotalk
 ```
-
-**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.
-
-## 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.

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

@@ -1,136 +1,38 @@
-# Setting up Appservice Slack bridging (optional)
+<!--
+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 Udo Rader
+SPDX-FileCopyrightText: 2020 jens quade
+SPDX-FileCopyrightText: 2021 Joel Bennett
+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 Fabio Bonelli
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
 
-**Notes**:
+SPDX-License-Identifier: AGPL-3.0-or-later
-- Bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook.
+-->
-- Currently (as of November, 2024) **this component is not available for new installation unless you have already created a classic Slack application** (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
 
-The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
+# Setting up Appservice Slack bridging (optional, removed)
 
-See the project's [documentation](https://github.com/matrix-org/matrix-appservice-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
+🪦 The playbook used to be able to install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack), but no longer includes this component, as it had been unavailable for new installation since 2024, and was finally abandoned because the public Matrix.org Slack bridge has been decommissioned on January 14th, 2026.
 
-## Prerequisites
+**Note**: Bridging to [Slack](https://slack.com) can also happen via the [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridge supported by the playbook.
 
-### Create a Classic Slack App
+## Uninstalling the component manually
 
-First, you need to create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
+If you still have matrix-appservice-slack 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:
 
-Name the app "matrixbot" (or anything else you'll remember). Select the team/workspace this app will belong to. Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
-
-Then, click on Event Subscriptions and enable them and use the request url: `https://matrix.example.com/appservice-slack`.
-
-Add the following events as `Bot User Events` and save:
-
-- team_domain_change
-- message.channels
-- message.groups (if you want to bridge private channels)
-- reaction_added
-- reaction_removed
-
-Next, click on "OAuth & Permissions" and add the following scopes:
-
-- chat:write:bot
-- users:read
-- reactions:write
-- files:write:user (if you want to bridge files)
-
-**Note**: In order to make Slack files visible to Matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
-
-Click on "Install App" and "Install App to Workspace". Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
-
-### Create an administration control room on Matrix
-
-Create a new Matrix room to act as the administration control room.
-
-Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
-
-## 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_slack_enabled: true
-matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
-
-# Uncomment to enable puppeting (optional, but recommended)
-# matrix_appservice_slack_puppeting_enabled: true
-# matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
-# matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
-
-# Uncomment to enable Team Sync (optional)
-# See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
-# matrix_appservice_slack_team_sync_enabled: true
-```
-
-Other configuration options are available via the `matrix_appservice_slack_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,ensure-matrix-users-created,start
+systemctl disable --now matrix-appservice-slack.service
+
+rm -rf /matrix/appservice-slack
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_appservice_slack;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to send `/invite @slackbot:example.com` to invite the bridge bot user into the admin room.
-
-If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
-
-- Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like `!qporfwt:example.com`.
-- Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
-- Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
-- Issue a link command in the administration control room with these collected values as arguments:
-
-    with file bridging:
-
-    ```
-    link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
-    ```
-
-    without file bridging:
-
-    ```
-    link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
-    ```
-
-    These arguments can be shortened to single-letter forms:
-
-    ```
-    link -I CHANNELID -R !qporfwt:example.com -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
-    ```
-
-### Unlinking
-
-Channels can be unlinked again by sending this:
-
-```
-unlink --room !qporfwt:example.com
-```
-
-Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
-
-## Troubleshooting
-
-As always, check the logs: `journalctl -fu matrix-appservice-slack`
-
-### Linking: "Room is now pending-name"
-
-This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
-
-### Messages work from Matrix to Slack, but not the other way around
-
-Check you logs, if they say something like
-
-`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
-
-then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.

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

@@ -1,87 +1,30 @@
-# Setting up Appservice Webhooks bridging (optional, deprecated)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2020 - 2023 MDAD project contributors
+SPDX-FileCopyrightText: 2020 Björn Marten
+SPDX-FileCopyrightText: 2020 iLyas Bakouch
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Kim Brose
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-**Note**: This bridge has been deprecated. 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 bridge instead of this one.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you. This bridge provides support for Slack-compatible webhooks.
+# Setting up Appservice Webhooks bridging (optional, removed)
 
-See the project's [documentation](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md) to learn what it does and why it might be useful to you.
+🪦 The playbook used to be able to install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks), but no longer includes this component, as it has been deprecated since more than several years.
 
-## Adjusting the playbook configuration
+You may wish to use [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) instead.
 
-To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+## Uninstalling the bridge manually
 
-```yaml
+If you still have matrix-appservice-webhooks 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:
-matrix_appservice_webhooks_enabled: true
-matrix_appservice_webhooks_api_secret: '<your_secret>'
-
-# Uncomment to increase the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
-# matrix_appservice_webhooks_log_level: 'verbose'
-
-# 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.
-#
-# matrix_synapse_configuration_extension_yaml: |
-#   use_appservice_legacy_authorization: true
-```
-
-## 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.
-
-## Usage
-
-To use the bridge, you need to invite the bridge bot user to your room in either way.
-
-- Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
-- Add the bridge bot to a private channel (personal channels imply you being an administrator)
-
-You then need to send a message to the bridge bot to receive a private message including the webhook link:
-
-```
-!webhook
-```
-
-The JSON body for posting messages will have to look like this:
-
-```json
-{
-    "text": "Hello world!",
-    "format": "plain",
-    "displayName": "My Cool Webhook",
-    "avatar_url": "http://i.imgur.com/IDOBtEJ.png"
-}
-```
-
-You can test this via curl like so:
 
 ```sh
-curl --header "Content-Type: application/json" \
+systemctl disable --now matrix-appservice-webhooks.service
---data '{
+
-"text": "Hello world!",
+rm -rf /matrix/appservice-webhooks
-"format": "plain",
-"displayName": "My Cool Webhook",
-"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
-}' \
-<the webhook link you've gotten from the bridge bot>
 ```
-
-### Setting Webhooks with Dimension integration manager
-
-If you're using the [Dimension integration manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge with it.
-
-To configure it, open the Dimension integration manager, and go to "Settings" and "Bridges", then select edit action for "Webhook Bridge".
-
-On the UI, press "Add self-hosted Bridge" button and populate "Provisioning URL"  and "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.

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

@@ -1,3 +1,13 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Alexandar Mechev
+SPDX-FileCopyrightText: 2022 Cody Wyatt Neiman
+SPDX-FileCopyrightText: 2023 Kuba Orlik
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Beeper Linkedin bridging (optional)
 
 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.
@@ -19,7 +29,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
@@ -36,16 +46,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -55,6 +61,16 @@ You then need to send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to e
 
 ## 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-beeper-linkedin`.
+
+### 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_bridge_beeper_linkedin_logging_level: DEBUG
+```
+
 ### Bridge asking for 2FA even if you don't have 2FA enabled
 
 If you don't have 2FA enabled and are logging in from a strange IP for the first time, LinkedIn will send an email with a one-time code. You can use this code to authorize the bridge session. In my experience, once the IP is authorized, you will not be asked again.

docs/configuring-playbook-bridge-go-skype-bridge.md

@@ -1,52 +1,26 @@
-# Setting up Go Skype Bridge bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-The playbook can install and configure [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you, for bridging to [Skype](https://www.skype.com/). This bridge was created based on [mautrix-whatsapp](https://github.com/mautrix/whatsapp) and can be configured in a similar way to it.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-See the project's [documentation](https://github.com/kelaresg/go-skype-bridge/blob/master/README.md) to learn what it does and why it might be useful to you.
+# Setting up Go Skype Bridge bridging (optional, removed)
 
-## Prerequisite (optional)
+🪦 The playbook used to be able to install and configure [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge), but no longer includes this component, as Skype has been discontinued since May 2025.
 
-### Enable Shared Secret Auth
+## Uninstalling the bridge manually
 
-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.
+If you still have the Go Skype bridge 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:
 
-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_go_skype_bridge_enabled: true
-```
-
-### 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), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
-
-**Note**: when following the guide to configure the bridge, make sure to replace `_mautrix_SERVICENAME_` in the variable names with `_go_skype_bridge_`.
-
-## 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
+systemctl disable --now matrix-go-skype-bridge.service
+
+rm -rf /matrix/go-skype-bridge
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_go_skype_bridge;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

docs/configuring-playbook-bridge-heisenbridge.md

@@ -1,8 +1,16 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Toni Spets
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Heisenbridge bouncer-style IRC bridging (optional)
 
 **Note**: bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) can also happen via the [matrix-appservice-irc](configuring-playbook-bridge-appservice-irc.md) bridge supported by the playbook.
 
-The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) - the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you.
+The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) — the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you.
 
 See the project's [documentation](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
 
@@ -17,48 +25,52 @@ 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_bridge_heisenbridge_hostname: heisenbridge.example.com
-matrix_heisenbridge_path_prefix: /
+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`.
 
 When setting, replace `example.com` with your own.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-heisenbridge/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
 ## 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,ensure-matrix-users-created,start
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -69,3 +81,7 @@ Help is available for all commands with the `-h` switch.
 You can also learn the basics by watching [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
 
 If you encounter issues or feel lost you can join the project room at [#heisenbridge:vi.fi](https://matrix.to/#/#heisenbridge:vi.fi) for help.
+
+## 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-heisenbridge`.

docs/configuring-playbook-bridge-hookshot.md

@@ -1,3 +1,13 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 Kim Brose
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Paul Tötterman
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up matrix-hookshot (optional)
 
 The playbook can install and configure [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) for you.
@@ -6,8 +16,6 @@ Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from softw
 
 See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) to learn what it does and why it might be useful to you.
 
-**Note**: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however was deprecated by its author.
-
 ## Prerequisites
 
 ### Download GitHub app private key (optional)
@@ -21,24 +29,39 @@ 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_experimental_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 also 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). If you are using Synapse, enable them by also adding this to your `vars.yml` file:
+>
+> ```yaml
+> matrix_synapse_experimental_features_msc2409_to_device_messages_enabled: true
+> matrix_synapse_experimental_features_msc3202_transaction_extensions_enabled: true
+> ```
+>
+> These are experimental homeserver-wide features (as is Hookshot's encryption support itself), so enable them deliberately.
 
-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
 
-You can configure additional options by adding the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables.
+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_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.
 
@@ -83,58 +106,84 @@ 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 |
+| - | `/hookshot/webhooks/` | `matrix_bridge_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
-| generic | `/hookshot/webhooks/webhook` | `matrix_hookshot_generic_endpoint` | Generic webhooks |
+| generic | `/hookshot/webhooks/webhook` | `matrix_bridge_hookshot_generic_endpoint` | Generic webhooks |
-| github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
+| github oauth | `/hookshot/webhooks/oauth` | `matrix_bridge_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
-| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | Jira OAuth |
+| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_bridge_hookshot_jira_oauth_endpoint` | Jira OAuth |
-| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
+| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_bridge_hookshot_figma_endpoint` | Figma |
-| provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
+| appservice | `/hookshot/_matrix/app/` | `matrix_bridge_hookshot_appservice_endpoint` | Matrix server |
-| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
+| widgets | `/hookshot/widgetapi/` | `matrix_bridge_hookshot_widgets_endpoint` | Widgets |
-| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
-| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and exposure enabled via `matrix_hookshot_metrics_proxying_enabled` or `matrix_metrics_exposure_enabled`. Read more in the [Metrics section](#metrics) below. | Prometheus |
 
-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)).
+- 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_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
+- 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_username }}"
+    owner: "{{ matrix_user_name }}"
-    group: "{{ matrix_user_groupname }}"
+    group: "{{ matrix_group_name }}"
 ```
 
 For more information, see the documentation in the [default configuration of the aux role](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml).
 
-### Provisioning API
+### Enable metrics
 
-The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
+The playbook can enable and configure the metrics of the service for you.
-
-### Metrics
 
 Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
 
-To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This only exposes metrics over the container network, however.
+To enable the metrics, add the following configuration to your `vars.yml` file:
 
-**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:
+```yaml
+# Expose metrics (locally, on the container network).
+matrix_bridge_hookshot_metrics_enabled: true
+```
 
-- either enabling metrics exposure for Hookshot via `matrix_hookshot_metrics_proxying_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:
-- or enabling metrics exposure for all services via `matrix_metrics_exposure_enabled: true`
 
-Whichever one you go with, by default metrics are exposed publicly **without** password-protection. See [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for details about password-protection for metrics.
+```yaml
+matrix_bridge_hookshot_metrics_proxying_enabled: true
+```
 
-### Collision with matrix-appservice-webhooks
+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:
 
-If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_userIdPrefix: '_webhooks_'`).
+```yaml
+matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
+matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
+```
+
+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.
+
+#### Enable Grafana (optional)
+
+Probably you wish to enable Grafana along with Prometheus for generating graphs of the metrics.
+
+To enable Grafana, see [this section](configuring-playbook-prometheus-grafana.md#adjusting-the-playbook-configuration-grafana) for instructions.
+
+## 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-hookshot`.
+
+### 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: error, warn, info, debug
+matrix_bridge_hookshot_logging_level: debug
+```

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

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2020 MDAD project contributors
+SPDX-FileCopyrightText: 2020 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Matrix SMS bridging (optional)
 
 The playbook can install and configure [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for you.
@@ -13,43 +21,50 @@ 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_bridge_sms_default_region: DE
-matrix_sms_bridge_default_timezone: Europe/Berlin
+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_bridge_sms_provider_android_baseurl: https://192.168.24.24:9090
-matrix_sms_bridge_provider_android_username: admin
+matrix_bridge_sms_provider_android_username: admin
-matrix_sms_bridge_provider_android_password: supeSecretPassword
+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_bridge_sms_provider_android_truststore_local_path: android-sms-gateway-server.p12
-matrix_sms_bridge_provider_android_truststore_password: 123
+matrix_bridge_sms_provider_android_truststore_password: 123
-
 ```
 
+### Extending the configuration
+
+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_bridge_sms_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,ensure-matrix-users-created,start
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
 Read the [user guide](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md#user-guide) to see how this bridge works.
+
+## 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-sms-bridge`.

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

@@ -0,0 +1,74 @@
+<!--
+SPDX-FileCopyrightText: 2025 MDAD project contributors
+SPDX-FileCopyrightText: 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Mautrix Bluesky 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-bluesky](https://github.com/mautrix/bluesky) for you, which provides a bridge to [Bluesky](https://bsky.social/about).
+
+See the project's [documentation](https://github.com/mautrix/bluesky/blob/master/README.md) 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) 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_mautrix_bluesky_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
+```
+
+**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 `@blueskybot: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/go/bluesky/authentication.html).
+
+After logging in, the bridge will create portal rooms for recent chats. Portal rooms for other chats will be created as you receive messages.
+
+## 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-bluesky`.
+
+### 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_bluesky_logging_level: 'debug'
+```

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

@@ -1,3 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 MDAD project contributors
+SPDX-FileCopyrightText: 2022 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2023 Nikita Chernyi
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up a Generic Mautrix Bridge (optional)
 
 The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, discord, signal, googlechat, etc.), as well as many other (non-mautrix) bridges. This is a common guide for configuring mautrix bridges.
@@ -12,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. **`matrix_mautrix_facebook_*` and `matrix_mautrix_instagram_*` variables belong to the deprecated components and do not control the new bridge** ([mautrix-meta](https://github.com/mautrix/meta)), which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md).
+**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)
 
@@ -34,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
@@ -58,8 +67,8 @@ matrix_bridges_encryption_default: true
 **Alternatively**, for a specific bridge:
 
 ```yaml
-matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
+matrix_bridge_mautrix_SERVICENAME_bridge_encryption_enabled: true
-matrix_mautrix_SERVICENAME_bridge_encryption_default: true
+matrix_bridge_mautrix_SERVICENAME_bridge_encryption_default: true
 ```
 
 ### Enable relay mode (optional)
@@ -77,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
@@ -106,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)
@@ -114,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)
@@ -122,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.
@@ -136,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
 
@@ -144,16 +182,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -192,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

@@ -1,10 +1,20 @@
+<!--
+SPDX-FileCopyrightText: 2018 Hugues Morisset
+SPDX-FileCopyrightText: 2018-2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021, 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Abílio Costa
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Marko Weltzer
+SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Discord bridging (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
 
-**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridges supported by the playbook.
+**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridge supported by the playbook.
-- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.
-- For personal use with a discord account we recommend the `mautrix-discord` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
 
 The playbook can install and configure [mautrix-discord](https://github.com/mautrix/discord) for you.
 
@@ -12,9 +22,9 @@ See the project's [documentation](https://docs.mau.fi/bridges/go/discord/index.h
 
 ## Prerequisites
 
-There are 2 ways to login to discord using this bridge, either by [scanning a QR code](#method-1-login-using-qr-code-recommended) using the Discord mobile app **or** by using a [Discord token](#method-2-login-using-discord-token-not-recommended).
+There are 3 ways to login to discord using this bridge, either by [scanning a QR code](https://docs.mau.fi/bridges/go/discord/authentication.html#qr-login) using the Discord mobile app, by using a [Discord token](https://docs.mau.fi/bridges/go/discord/authentication.html#token-login), **or** by using a [Discord bot token](https://docs.mau.fi/bridges/go/discord/authentication.html#bot-token-login).
 
-If this is a dealbreaker for you, consider using one of the other Discord bridges supported by the playbook: [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) or [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md). These come with their own complexity and limitations, however, so we recommend that you proceed with this one if possible.
+⚠️ QR code login is considered a self-bot and is forbidden by Discord. It can result in an account termination. See the [Discord policy](https://support.discord.com/hc/en-us/articles/115002192352-Automated-User-Accounts-Self-Bots).
 
 ### Enable Appservice Double Puppet or Shared Secret Auth (optional)
 
@@ -29,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
@@ -45,16 +55,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -71,3 +77,28 @@ If you'd like to bridge guilds, send `guilds status` to see the list of guilds,
 After bridging, spaces will be created automatically, and rooms will be created if necessary when messages are received. You can also pass `--entire` to the bridge command to immediately create all rooms.
 
 If you want to manually bridge channels, invite the bot to the room you want to bridge, and run `!discord bridge CHANNEL_ID_HERE` to bridge the room. Make sure to replace `CHANNEL_ID_HERE` with the channel's ID.
+
+### Enable relay
+
+The bridge supports using Discord's webhook feature to relay messages from Matrix users who haven't logged into the bridge.
+
+In a room that has already been bridged, run `!discord set-relay --create`. The bridge will then create a webhook in the bridged discord channel and begin relaying messages. If the discord user does not have access to manage webhooks, run `!discord set-relay --url <url>` with the url of an already created webhook. (See Discords [Intro to webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks))
+
+More information on relaying is available on the [official documentation](https://docs.mau.fi/bridges/go/discord/relay.html).
+
+## 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-discord`.
+
+### 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_discord_logging_level: 'debug'
+```
+
+### Command requires room admin rights when user is creator
+
+[MSC4289](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4289-privilege-creators.md), introduced in [room version 12](https://spec.matrix.org/unstable/rooms/v12/), gives creators an infinitley high powerlevel. At the time of implementation, mautrix-discord and similar applications may not identify creators as or above admins. Either a separate admin user will need to manage the bridge or the room version should be less than version 12.

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

@@ -1,82 +1,32 @@
-# Setting up Mautrix Facebook bridging (optional, deprecated)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2019 Hugues Morisset
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2021 Aaron Raimist
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 László Várady
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-**Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md). Consider using that bridge instead of this one.
+# Setting up Mautrix Facebook bridging (optional, removed)
 
-The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you.
+🪦 The playbook used to be able to install and configure [mautrix-facebook](https://github.com/mautrix/facebook), but no longer includes this component, as it has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge.
 
-See the project's [documentation](https://github.com/mautrix/facebook/blob/master/README.md) to learn what it does and why it might be useful to you.
+The mautrix-meta bridge can be [installed using this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md).
 
-## Prerequisite (optional)
+## Uninstalling the bridge manually
 
-### Enable Shared Secret Auth
+If you still have the bridge 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:
-
-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_mautrix_facebook_enabled: true
-```
-
-### 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), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-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,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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-You then need to send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account.
-
-If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
-
-## Troubleshooting
-
-### Facebook rejecting login attempts and forcing you to change password
-
-If your Matrix server is in a wildly different location than where you usually use your Facebook account from, the bridge's login attempts may be outright rejected by Facebook. Along with that, Facebook may even force you to change the account's password.
-
-If you happen to run into this problem while [setting up bridging](#usage), try to first get a successful session up by logging in to Facebook through the Matrix server's IP address.
-
-The easiest way to do this may be to use [sshuttle](https://sshuttle.readthedocs.io/) to proxy your traffic through the Matrix server.
-
-Example command for proxying your traffic through the Matrix server:
 
 ```sh
-sshuttle -r root@matrix.example.com:22 0/0
+systemctl disable --now matrix-mautrix-facebook.service
+
+rm -rf /matrix/mautrix-facebook
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_mautrix_facebook;'
 ```
-
-Once connected, you should be able to verify that you're browsing the web through the Matrix server's IP by checking [icanhazip](https://icanhazip.com/).
-
-Then proceed to log in to [Facebook/Messenger](https://www.facebook.com/).
-
-Once logged in, proceed to [set up bridging](#usage).
-
-If that doesn't work, enable 2FA (see: [Facebook help page on enabling 2FA](https://www.facebook.com/help/148233965247823)) and try to login again with a new password, and entering the 2FA code when prompted, it may take more then one try, in between attempts, check facebook.com to see if they are requiring another password change

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

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2023 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2023 Shreyas Ajjarapu
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Google Messages bridging (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
@@ -19,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
@@ -35,16 +43,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -53,3 +57,16 @@ To use the bridge, you need to start a chat with `@gmessagesbot:example.com` (wh
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/gmessages/authentication.html).
 
 After logging in, the bridge will create portal rooms for recent chats.
+
+## 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-gmessages`.
+
+### 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_gmessages_logging_level: 'debug'
+```

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

@@ -1,3 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Google Chat bridging (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
@@ -21,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
@@ -37,16 +46,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -54,4 +59,16 @@ To use the bridge, you need to start a chat with `@googlechatbot:example.com` (w
 
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
 
-After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
+After logging in, the bridge will create portal rooms for recent chats. Portal rooms for other chats will be created as you receive messages.
+
+## 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-googlechat`.
+
+### 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_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-hangouts.md

@@ -1,58 +1,27 @@
-# Setting up Mautrix Hangouts bridging (optional, deprecated)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-💡 **Note**: This bridge has been deprecated in favor of [Google Chat bridge](https://github.com/mautrix/googlechat), which can be installed using [this playbook](configuring-playbook-bridge-mautrix-googlechat.md). Installing the mautrix-hangouts bridge is **no longer possible**. For now, this documentation page remains here for historical purposes.
+# Setting up Mautrix Hangouts bridging (optional, removed)
 
-The playbook can install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts) for you.
+🪦 The playbook used to be able to install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts), but no longer includes this component, because Google Hangouts has been discontinued since the 1st of November 2022.
 
-## Prerequisite (optional)
+You may wish to use the [Google Chat bridge](https://github.com/mautrix/googlechat) instead.
 
-### Enable Shared Secret Auth
+## Uninstalling the bridge manually
 
-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.
+If you still have the Hangouts bridge 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:
 
-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 [Google Hangouts](https://hangouts.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_mautrix_hangouts_enabled: true
-```
-
-### 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), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-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,ensure-matrix-users-created,start
+systemctl disable --now matrix-mautrix-hangouts.service
+
+rm -rf /matrix/mautrix-hangouts
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_mautrix_hangouts;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-You then need to send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.
-
-Automatic login may not work. If it does not, reload the page and select the "Manual login" checkbox before starting. Manual login involves logging into your Google account normally and then manually getting the OAuth token from browser cookies with developer tools.
-
-Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages.

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

@@ -1,46 +1,33 @@
-# Setting up Mautrix Instagram bridging (optional, deprecated)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2019 Hugues Morisset
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2021 Aaron Raimist
+SPDX-FileCopyrightText: 2021 Marcus Proest
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 László Várady
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-**Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-instagram.md). Consider using that bridge instead of this one.
+# Setting up Mautrix Instagram bridging (optional, removed)
 
-The playbook can install and configure [mautrix-instagram](https://github.com/mautrix/instagram) for you.
+🪦 The playbook used to be able to install and configure [mautrix-instagram](https://github.com/mautrix/instagram), but no longer includes this component, as it has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge.
 
-See the project's [documentation](https://github.com/mautrix/instagram/blob/master/README.md) to learn what it does and why it might be useful to you.
+The mautrix-meta bridge can be [installed using this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md).
 
-## Adjusting the playbook configuration
+## Uninstalling the bridge manually
 
-To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+If you still have the bridge 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:
 
-```yaml
-matrix_mautrix_instagram_enabled: true
-```
-
-### 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), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-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,ensure-matrix-users-created,start
+systemctl disable --now matrix-mautrix-instagram.service
+
+rm -rf /matrix/mautrix-instagram
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_mautrix_instagram;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-You then need to send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account.

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

@@ -1,3 +1,10 @@
+<!--
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Instagram bridging via Mautrix Meta (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
@@ -16,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.
@@ -34,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.
@@ -51,16 +58,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -69,3 +72,16 @@ To use the bridge, you need to start a chat with `@instagrambot:example.com` (wh
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
 
 After logging in, the bridge will sync recent chats.
+
+## 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-meta-instagram`.
+
+### 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
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
+matrix_bridge_mautrix_meta_instagram_logging_min_level: debug
+```

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

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Johan Swetzén
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Messenger bridging via Mautrix Meta (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
@@ -33,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.
@@ -45,10 +53,10 @@ As mentioned above, the [mautrix-meta](https://github.com/mautrix/meta) bridge s
 The bridge can pull your Messenger messages via 3 different methods:
 
 - (`facebook`) Facebook via `facebook.com`
-- (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) - does not currently proxy media downloads
+- (`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
+- (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.).
 
@@ -64,16 +72,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -84,3 +88,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
 After logging in, the bridge will sync recent chats.
 
 **Note**: given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there.
+
+## 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-meta-messenger`.
+
+### 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
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
+matrix_bridge_mautrix_meta_messenger_logging_min_level: debug
+```

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

@@ -1,3 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 Hugues Morisset
+SPDX-FileCopyrightText: 2020 - 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2020 Sabine Laszakovits
+SPDX-FileCopyrightText: 2021 Julian Foad
+SPDX-FileCopyrightText: 2021 Wolfgang Winter
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Marko Weltzer
+SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Benjamin Kampmann
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Signal bridging (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
@@ -12,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
 
@@ -25,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
@@ -40,16 +56,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -60,3 +72,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
 After logging in, the bridge will bridge chats as you receive messages.
 
 **Note**: Signal does not support any kind of message history (even on official apps), so the bridge won't backfill any messages.
+
+## 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-signal`.
+
+### 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_signal_logging_level: 'debug'
+```

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

@@ -1,11 +1,16 @@
+<!--
+SPDX-FileCopyrightText: 2023 Cody Wyatt Neiman
+SPDX-FileCopyrightText: 2023 Stuart Mumford
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Slack bridging (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
 
-**Note**: bridging to [Slack](https://slack.com/) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) bridges supported by the playbook.
-- For using as a Bot we recommend the [Appservice Slack](configuring-playbook-bridge-appservice-slack.md), because it supports plumbing. Note that it is not available for new installation unless you have already created a classic Slack application, because the creation of classic Slack applications, which this bridge makes use of, has been discontinued.
-- For personal use with a slack account we recommend the `mautrix-slack` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Slack bridges supported by the playbook.
-
 The playbook can install and configure [mautrix-slack](https://github.com/mautrix/slack) for you.
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/slack/index.html) to learn what it does and why it might be useful to you.
@@ -16,7 +21,7 @@ See the [features and roadmap](https://github.com/mautrix/slack/blob/main/ROADMA
 
 For using this bridge, you would need to authenticate by **providing your username and password** (legacy) or by using a **token login**. See more information in the [docs](https://docs.mau.fi/bridges/go/slack/authentication.html).
 
-Note that neither of these methods are officially supported by Slack. [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) uses a Slack bot account which is the only officially supported method for bridging a Slack channel.
+Note that neither of these methods are officially supported by Slack.
 
 ### Enable Appservice Double Puppet (optional)
 
@@ -29,15 +34,14 @@ 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
 
 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), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
-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
 
@@ -45,16 +49,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -63,3 +63,16 @@ To use the bridge, you need to start a chat with `@slackbot:example.com` (where
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/slack/authentication.html).
 
 If you authenticated using a token, the recent chats will be bridged automatically (depending on the `conversation_count` setting). Otherwise (i.e. logging with the Discord application), the chats the bot is in will be bridged automatically.
+
+## 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-slack`.
+
+### 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_slack_logging_level: 'debug'
+```

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

@@ -1,10 +1,23 @@
+<!--
+SPDX-FileCopyrightText: 2018 - 2026 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 Hugues Morisset
+SPDX-FileCopyrightText: 2019 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2021 Panagiotis Georgiadis
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Iikka Järvenpää
+SPDX-FileCopyrightText: 2022 Marko Weltzer
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Telegram 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-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
 
@@ -12,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_bridge_mautrix_telegram_enabled: true
-matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
+matrix_bridge_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
-matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
+matrix_bridge_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
 ```
 
 ### Relaying
 
-### Enable relay-bot (optional)
+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.
-
-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
-```
 
 ### 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
@@ -75,21 +61,30 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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 `@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
+
+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-telegram`.
+
+### 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_telegram_logging_level: debug
+```

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

@@ -1,9 +1,16 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Matthew Cengia
+SPDX-FileCopyrightText: 2022 Aaron Raimist
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Twitter bridging (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
 
-**Note**: bridging to [Twitter](https://twitter.com/) can also happen via the [mx-puppet-twitter](configuring-playbook-bridge-mx-puppet-twitter.md) bridge supported by the playbook.
-
 The playbook can install and configure [mautrix-twitter](https://github.com/mautrix/twitter) for you.
 
 See the project's [documentation](https://github.com/mautrix/twitter/blob/master/README.md) to learn what it does and why it might be useful to you.
@@ -21,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
@@ -37,16 +44,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -54,4 +57,17 @@ To use the bridge, you need to start a chat with `@twitterbot:example.com` (wher
 
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/twitter/authentication.html).
 
-After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
+After logging in, the bridge will create portal rooms for recent chats. Portal rooms for other chats will be created as you receive messages.
+
+## 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-twitter`.
+
+### 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_twitter_logging_level: 'debug'
+```

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

@@ -1,3 +1,16 @@
+<!--
+SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 Hugues Morisset
+SPDX-FileCopyrightText: 2021 - 2025 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Marko Weltzer
+SPDX-FileCopyrightText: 2023 James Collier
+SPDX-FileCopyrightText: 2023 Kuba Orlik
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Whatsapp bridging (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
@@ -21,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
@@ -36,16 +49,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
@@ -56,3 +65,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
 Approximately in a minute after logging in, the bridge will create portal rooms for recent chats.
 
 **Note**: your linked devices will be logged out if you don’t use your phone for over 14 days (see the official FAQ entry [here](https://faq.whatsapp.com/general/download-and-installation/about-linked-devices)). The bridge will warn you if it doesn't receive any data from the phone over 12 days.
+
+## 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-whatsapp`.
+
+### 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_whatsapp_logging_level: 'debug'
+```

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

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2023 Johan Swetzén
+SPDX-FileCopyrightText: 2023 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage (optional)
 
 <sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
@@ -17,53 +25,53 @@ 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_bridge_mautrix_wsproxy_androidsms_appservice_token: 'secret token from bridge'
-matrix_mautrix_androidsms_homeserver_token: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_androidsms_homeserver_token: 'secret token from bridge'
-matrix_mautrix_imessage_appservice_token: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_imessage_appservice_token: 'secret token from bridge'
-matrix_mautrix_imessage_homeserver_token: 'secret token from bridge'
+matrix_bridge_mautrix_wsproxy_imessage_homeserver_token: 'secret token from bridge'
-matrix_mautrix_wsproxy_syncproxy_shared_secret: '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_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_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.
+
 ### 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), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
 
-### 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.
-
-Example additional configuration for your `vars.yml` file:
-
-```yaml
-# Change the default hostname
-matrix_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.
-
 ## 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,ensure-matrix-users-created,start
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
-Follow the [mautrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).
+Follow the [mautrix-imessage documentation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).
+
+## 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-wsproxy`.

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-discord.md

@@ -1,46 +1,31 @@
-# Setting up MX Puppet Discord bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2020 Hugues Morisset
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md)and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.   
+SPDX-License-Identifier: AGPL-3.0-or-later
-- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.  
+-->
-- For personal use with a discord account we recommend the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge, because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
 
-The playbook can install and configure [mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) for you.
+# Setting up MX Puppet Discord bridging (optional, removed)
 
-See the project's [documentation](https://gitlab.com/mx-puppet/discord/mx-puppet-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
+🪦 The playbook used to be able to install and configure [mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord), but no longer includes this component, as it has been unmaintained for a long time.
 
-## Adjusting the playbook configuration
+You may wish to use the [Mautrix Discord bridge](https://github.com/mautrix/discord) instead.
 
-To enable the [Discord](https://discordapp.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+## Uninstalling the bridge manually
 
-```yaml
+If you still have the MX Puppet Discord bridge 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:
-matrix_mx_puppet_discord_enabled: true
-```
 
-## 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
+systemctl disable --now matrix-mx-puppet-discord.service
+
+rm -rf /matrix/mx-puppet-discord
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_mx_puppet_discord;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `Discord Puppet Bridge` with the handle `@_discordpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-discord [documentation](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) for more information about how to configure the bridge.
-
-Once logged in, send `list` to the bot user to list the available rooms.
-
-Clicking rooms in the list will result in you receiving an invitation to the bridged room.
-
-Send `help` to the bot to see the available commands.

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

@@ -1,3 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2021 Cody Neiman
+SPDX-FileCopyrightText: 2021 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 Cody Wyatt Neiman
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up MX Puppet GroupMe bridging (optional)
 
 The playbook can install and configure [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) for you.
@@ -9,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
@@ -18,16 +27,12 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 

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

@@ -1,48 +1,30 @@
-# Setting up MX Puppet Instagram bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2020 Hugues Morisset
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-The playbook can install and configure [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) for you.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-This allows you to bridge Instagram DirectMessages into Matrix.
+# Setting up MX Puppet Instagram bridging (optional, removed)
 
-## Adjusting the playbook configuration
+🪦 The playbook used to be able to install and configure [mx-puppet-instagram](https://gitlab.com/mx-puppet/instagram/mx-puppet-instagram), but no longer includes this component, as it has been unmaintained for a long time.
 
-To enable the [Instagram](https://www.instagram.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+You may wish to use the [Mautrix Meta](https://github.com/mautrix/meta) Messenger/Instagram bridge instead.
 
-```yaml
+## Uninstalling the bridge manually
-matrix_mx_puppet_instagram_enabled: true
-```
 
-## Installing
+If you still have the MX Puppet Instagram bridge 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:
 
-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
+systemctl disable --now matrix-mx-puppet-instagram.service
+
+rm -rf /matrix/mx-puppet-instagram
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_mx_puppet_instagram;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `Instagram Puppet Bridge` with the handle `@_instagrampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-Send `link <username> <password>` to the bridge bot to link your instagram account.
-
-The `list` commands shows which accounts are linked and which `puppetId` is associated.
-
-For double-puppeting, you probably want to issue these commands:
-
-- `settype $puppetId puppet` to enable puppeting for the link (instead of relaying)
-- `setautoinvite $puppetId 1` to automatically invite you to chats
-- `setmatrixtoken $accessToken` to set the access token to enable puppeting from the other side (the "double" in double puppeting)
-
-If you are linking only one Instagram account, your `$puppetId` is probably 1, but use the `list` command find out.
-
-Send `help` to the bot to see the available commands. At the time of writing, not every command is fully implemented.

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

@@ -1,5 +1,13 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Rodrigo Belem
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up MX Puppet Skype bridging (optional, removed)
 
-The playbook used to be able to install and configure [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype), but no longer includes this component, because it has been broken and unmaintained for a long time.
+🪦 The playbook used to be able to install and configure [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype), but no longer includes this component, because it has been broken and unmaintained for a long time.
 
-Bridging to [Skype](https://www.skype.com/) can also happen via the [go-skype-bridge](configuring-playbook-bridge-go-skype-bridge.md) bridge supported by the playbook.
+The playbook used to be able to install and configure [go-skype-bridge](configuring-playbook-bridge-go-skype-bridge.md) as alternative to this bridge, but no longer includes this component, because Skype has been discontinued since May 2025.

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

@@ -1,51 +1,33 @@
-# Setting up MX Puppet Slack bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2020 Rodrigo Belem
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 Marcel Ackermann
+SPDX-FileCopyrightText: 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Jim Myhrberg
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-**Note**: bridging to [Slack](https://slack.com) can also happen via the [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook. Note that `matrix-appservice-slack` is not available for new installation unless you have already created a classic Slack application, because the creation of classic Slack applications, which this bridge makes use of, has been discontinued.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-The playbook can install and configure [mx-puppet-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) for you.
+# Setting up MX Puppet Slack bridging (optional, removed)
 
-See the project's [documentation](https://gitlab.com/mx-puppet/slack/mx-puppet-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
+🪦 The playbook used to be able to install and configure [mx-puppet-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack), but no longer includes this component, as it has been unmaintained for a long time.
 
-## Prerequisite
+You may wish to use the [Mautrix Slack bridge](https://github.com/mautrix/slack) instead.
 
-Follow the [OAuth credentials](https://gitlab.com/mx-puppet/slack/mx-puppet-slack#option-2-oauth) instructions to create a new Slack app, setting the redirect URL to `https://matrix.example.com/slack/oauth`.
+## Uninstalling the bridge manually
 
-## Adjusting the playbook configuration
+If you still have the MX Puppet Slack bridge 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:
 
-To enable the [Slack](https://slack.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_mx_puppet_slack_enabled: true
-# Client ID must be quoted so YAML does not parse it as a float.
-matrix_mx_puppet_slack_oauth_client_id: "<SLACK_APP_CLIENT_ID>"
-matrix_mx_puppet_slack_oauth_client_secret: "<SLACK_APP_CLIENT_SECRET>"
-```
-
-## 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
+systemctl disable --now matrix-mx-puppet-slack.service
+
+rm -rf /matrix/mx-puppet-slack
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_mx_puppet_slack;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `Slack Puppet Bridge` with the handle `@_slackpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-slack [documentation](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) for more information about how to configure the bridge.
-
-Once logged in, send `list` to the bot user to list the available rooms.
-
-Clicking rooms in the list will result in you receiving an invitation to the bridged room.
-
-Send `help` to the bot to see the available commands.

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

@@ -1,15 +1,26 @@
-# Setting up MX Puppet Steam bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2020 - 2021 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Hugues Morisset
+SPDX-FileCopyrightText: 2020 Panagiotis Vasilopoulos
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-The playbook can install and configure [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) for you.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-See the project's [documentation](https://github.com/icewind1991/mx-puppet-steam/blob/master/README.md) to learn what it does and why it might be useful to you.
+# Setting up MX Puppet Steam bridging (optional, deprecated)
+
+**Note**: This bridge has been deprecated in favor of the [matrix-steam-bridge](https://github.com/jasonlaguidice/matrix-steam-bridge) bridge for Steam, which can be [installed using this playbook](configuring-playbook-bridge-steam.md). Consider using that bridge instead of this one.
+
+The playbook can install and configure [mx-puppet-steam](https://codeberg.org/icewind/mx-puppet-steam) for you.
+
+See the project's [documentation](https://codeberg.org/icewind/mx-puppet-steam/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
 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
@@ -18,22 +29,18 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
 
 <!-- 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
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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 `Steam Puppet Bridge` with the handle `@_steampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-steam [documentation](https://github.com/icewind1991/mx-puppet-steam) for more information about how to configure the bridge.
+Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-steam [documentation](https://codeberg.org/icewind/mx-puppet-steam) for more information about how to configure the bridge.
 
 Once logged in, send `list` to the bot user to list the available rooms.
 

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

@@ -1,53 +1,29 @@
-# Setting up MX Puppet Twitter bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Eduardo Beltrame
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-**Note**: bridging to [Twitter](https://twitter.com/) can also happen via the [mautrix-twitter](configuring-playbook-bridge-mautrix-twitter.md) bridge supported by the playbook.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-The playbook can install and configure [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) for you.
+# Setting up MX Puppet Twitter bridging (optional, removed)
 
-See the project's [documentation](https://github.com/Sorunome/mx-puppet-twitter/blob/master/README.md) to learn what it does and why it might be useful to you.
+🪦 The playbook used to be able to install and configure [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter), but no longer includes this component, as it has been unmaintained for a long time.
 
-## Prerequisite
+You may wish to use the [Mautrix Twitter bridge](https://github.com/mautrix/twitter) instead.
 
-Make an app on [developer.twitter.com](https://developer.twitter.com/en/apps).
+## Uninstalling the bridge manually
 
-## Adjusting the playbook configuration
+If you still have the MX Puppet Twitter bridge 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:
 
-To enable the [Twitter](https://twitter.com) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_mx_puppet_twitter_enabled: true
-matrix_mx_puppet_twitter_consumer_key: ''
-matrix_mx_puppet_twitter_consumer_secret: ''
-matrix_mx_puppet_twitter_access_token: ''
-matrix_mx_puppet_twitter_access_token_secret: ''
-matrix_mx_puppet_twitter_environment: ''
-```
-
-## 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
+systemctl disable --now matrix-mx-puppet-twitter.service
+
+rm -rf /matrix/mx-puppet-twitter
+
+/matrix/postgres/bin/cli-non-interactive -c 'DROP DATABASE matrix_mx_puppet_twitter;'
 ```
-
-**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.
-
-## Usage
-
-To use the bridge, you need to start a chat with `Twitter Puppet Bridge` with the handle `@_twitterpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-To log in, use `link` and click the link.
-
-Once logged in, send `list` to the bot user to list the available rooms.
-
-Clicking rooms in the list will result in you receiving an invitation to the bridged room.
-
-Send `help` to the bot to see the available commands.

docs/configuring-playbook-bridge-postmoogle.md

@@ -1,6 +1,13 @@
-# Setting up Postmoogle email bridging (optional)
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2023 Luke D Iremadze
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 
-**Note**: email bridging can also happen via the [email2matrix](configuring-playbook-email2matrix.md) bridge supported by the playbook.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Postmoogle email bridging (optional)
 
 The playbook can install and configure [Postmoogle](https://github.com/etkecc/postmoogle) for you.
 
@@ -17,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
 
@@ -37,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:
@@ -55,6 +62,14 @@ matrix_postmoogle_password: PASSWORD_FOR_THE_BOT
 # matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
 ```
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-postmoogle/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:
@@ -72,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
 
@@ -84,12 +99,14 @@ Send `!pm help` to the bot in the room to see the available commands.
 
 You can also refer to the upstream [documentation](https://github.com/etkecc/postmoogle).
 
-### Debug/Logs
+## Troubleshooting
 
-As with all other services, you can find their logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-postmoogle`
+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-postmoogle`.
 
-The default logging level for this bridge is `INFO`, but you can increase it to `DEBUG` with the following additional configuration:
+### 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
-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

@@ -0,0 +1,51 @@
+<!--
+SPDX-FileCopyrightText: 2025 Jason LaGuidice
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up Steam bridging (optional)
+
+The playbook can install and configure [matrix-steam-bridge](https://github.com/jasonlaguidice/matrix-steam-bridge) for you.
+
+See the project's [documentation](https://github.com/jasonlaguidice/matrix-steam-bridge/blob/main/README.md) to learn what it does and why it might be useful to you.
+
+## Adjusting the playbook configuration
+
+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_bridge_steam_enabled: true
+```
+
+## 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` and `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.
+
+The tag for `just` commands for this bridge is `matrix-steam-bridge` - for example: `just install-service matrix-steam-bridge`
+
+## Usage
+
+To use the bridge, you need to start a chat with `Steam bridge bot` with the handle `@steambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+The bridge supports QR code and password-based login as well as SteamGuard codes via app, SMS, or e-mail. See matrix-steam-bridge [documentation](https://github.com/jasonlaguidice/matrix-steam-bridge) for more information about how to configure the bridge.
+
+To login, send `login [flow ID]` where possible flow IDs are `password` or `qr`
+
+Once logged in, send `search [name]` to search through recognized Steam friends. You can send a user name, display name, or all forms of Steam ID. Send `start-chat [identifier]` to request the bridge bot to open a chat room with a user.
+
+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

@@ -1,30 +1,47 @@
+<!--
+SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up WeChat bridging (optional)
 
 The playbook can install and configure [matrix-wechat](https://github.com/duo/matrix-wechat) for you, for bridging to [WeChat](https://www.wechat.com/).
 
 See the project's [documentation](https://github.com/duo/matrix-wechat/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+> [!WARNING]
+> This bridge does not work against newer versions of Synapse anymore. See [this issue](https://github.com/duo/matrix-wechat/issues/33). Don't even bother installing it. Unless bridge maintenance is resumed and fixes this issue, we have no choice but to remove it from the playbook.
+
 ## 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_wechat_enabled: true
+matrix_bridge_wechat_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-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_bridge_wechat_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,ensure-matrix-users-created,start
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,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.
@@ -34,3 +51,16 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 To use the bridge, you need to start a chat with `@wechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `help` to the bot to see the available commands.
+
+## 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-wechat`.
+
+### 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
+matrix_bridge_wechat_log_level: 'debug'
+```

docs/configuring-playbook-cactus-comments.md

@@ -1,3 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 Julian-Samuel Gebühr
+SPDX-FileCopyrightText: 2023 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Cactus Comments (optional)
 
 The playbook can install and configure the [Cactus Comments](https://cactus.chat) system for you.
@@ -8,9 +17,9 @@ See the project's [documentation](https://cactus.chat/docs/getting-started/intro
 
 The playbook contains 2 roles for configuring different pieces of the Cactus Comments system:
 
-- `matrix-cactus-comments` - the backend appservice integrating with the Matrix homeserver
+- `matrix-cactus-comments` — the backend appservice integrating with the Matrix homeserver
 
-- `matrix-cactus-comments-client` - a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
+- `matrix-cactus-comments-client` — a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
 
 You can enable whichever component you need (typically both).
 
@@ -25,23 +34,21 @@ If you wish to adjust it, see the section [below](#adjusting-the-cactus-comments
 To enable Cactus Comments, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-#################
-## Cactus Comments ##
-#################
-
 # This enables the backend (appservice)
 matrix_cactus_comments_enabled: true
 
+# This enables client assets static files serving on `https://matrix.example.com/cactus-comments`.
+# When the backend (appservice) is enabled, this is also enabled automatically, but we explicitly enable it here.
+matrix_cactus_comments_client_enabled: true
+
+# Uncomment and adjust this part if you'd like to use a username different than the default
+# matrix_cactus_comments_user_id: "bot.cactusbot"
+
 # To allow guest comments without users needing to log in, you need to have guest registration enabled.
 # To do this you need to uncomment one of the following lines (depending if you are using Synapse or Dendrite as a homeserver)
 # If you don't know which one you use: The default is Synapse ;)
 # matrix_synapse_allow_guest_access: true
 # matrix_dendrite_allow_guest_access: true
-
-# This enables client assets static files serving on `https://matrix.example.com/cactus-comments`.
-# When the backend (appservice) is enabled, this is also enabled automatically,
-# but we explicitly enable it here.
-matrix_cactus_comments_client_enabled: true
 ```
 
 ### Adjusting the Cactus Comments' client URL (optional)
@@ -61,30 +68,36 @@ If you've changed the default hostname, you may need to create a CNAME record fo
 
 When setting, replace `example.com` with your own.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the components.
+
+For `matrix-cactus-comments`, take a look at:
+
+- `roles/custom/matrix-cactus-comments/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+For `matrix-cactus-comments-client`, take a look at:
+
+- `roles/custom/matrix-cactus-comments-client/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
 ## 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,ensure-matrix-users-created,start
+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`
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+`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.
-
-- 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
 
-Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.
+To use the component, you need to start a chat with `@bot.cactusbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-To get started, send `help` to the `@bot.cactusbot:example.com` bot to confirm it's working.
+Then, register a site by sending `register YOUR_SITE_NAME_HERE` (where `YOUR_SITE_NAME_HERE` is a unique identifier you choose. It does not have to match your domain). You will then be invited into a moderation room.
-
-Then, register a site by sending `register <YourSiteName>` (where `<YourSiteName>` is a unique identifier you choose. It does not have to match your domain). You will then be invited into a moderation room.
 
 Now you are good to go and can embed the comment section on your website!
 
@@ -98,7 +111,7 @@ After including the JavaScript and CSS asset files, insert a `<div>` where you'd
 <div id="comment-section"></div>
 ````
 
-Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `<YourSiteName>` with the one that has been registered above:
+Then, you need to initialize the comment section. Make sure to replace `example.com` with your base domain and `YOUR_SITE_NAME_HERE` with the one that has been registered above:
 
 ```html
 <script>
@@ -106,7 +119,7 @@ initComments({
   node: document.getElementById("comment-section"),
   defaultHomeserverUrl: "https://matrix.example.com:8448",
   serverName: "example.com",
-  siteName: "<YourSiteName>",
+  siteName: "YOUR_SITE_NAME_HERE",
   commentSectionId: "1"
 })
 </script>
@@ -124,3 +137,18 @@ Make sure to replace `example.com` with your base domain before you include the
 ```
 
 **Note**: if the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_path_prefix` variables are tweaked, you would need to adjust the URLs of the assets accordingly.
+
+## 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-cactus-comments` for the backend appservice or `journalctl -fu matrix-cactus-comments-client` for the server serving the client assets, respectively.
+
+### Increase logging verbosity
+
+It is possible to increase logging verbosity for `matrix-cactus-comments-client`. The default logging level for this component is `error`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Controls the SERVER_LOG_LEVEL environment variable.
+# See: https://static-web-server.net/configuration/environment-variables/
+# Valid values: error, warn, info, debug, trace
+matrix_cactus_comments_client_environment_variable_server_log_level: debug
+```

docs/configuring-playbook-client-cinny.md

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Cinny (optional)
 
 The playbook can install and configure the [Cinny](https://github.com/ajbura/cinny) Matrix web client for you.
@@ -19,26 +27,35 @@ When setting, replace `example.com` with your own.
 To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_client_cinny_enabled: true
+cinny_enabled: true
 ```
 
 ### Adjusting the Cinny URL (optional)
 
-By tweaking the `matrix_client_cinny_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+By tweaking the `cinny_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 (`cinny.example.com`)
-matrix_client_cinny_hostname: "app.{{ matrix_domain }}"
+cinny_hostname: "app.{{ matrix_domain }}"
 
 # Expose under the /cinny subpath
-# matrix_client_cinny_path_prefix: /cinny
+# cinny_path_prefix: /cinny
 ```
 
 After changing the domain, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server.
 
-**Note**: while there is a `matrix_client_cinny_path_prefix` variable for changing the path where Cinny is served, overriding it is [not possible](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path. You'd need to serve Cinny at a dedicated subdomain.
+**Note**: while there is a `cinny_path_prefix` variable for changing the path where Cinny is served, overriding it is [not possible](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path. You'd need to serve Cinny 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/cinny/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/galaxy/cinny/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 `cinny_configuration_extension_json` variable
 
 ## Installing
 
@@ -52,3 +69,7 @@ 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-cinny`.