Update docker.io/metio/matrix-alertmanager-receiver Docker tag to v2025.6.25

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

.codespellrc

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

.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

.envrc

@@ -1 +1 @@
-use flake
+use flake

.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

@@ -11,7 +11,7 @@ assignees: ''
 A clear and concise description of what the bug is.
 
 <!--
-NOTE: This Ansible playbook installs tens of separate services. If you're having a problem with a specific service, it is likely that the problem is not with our deployment method, but with the service itself. You may wish to report that problem at the source, upstream, and not to us
+NOTE: This Ansible playbook installs tens of separate services. If you're having a problem with a specific one, it is likely that the problem is with the service itself. You may wish to report that problem at the source, upstream.
 -->
 
 **To Reproduce**
@@ -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

@@ -13,7 +13,9 @@ A clear and concise description of what the problem is. Ex. I'm always frustrate
 <!--
 NOTE: When submitting feature requests, be aware that:
 
-- This Ansible playbook installs tens of separate services. If you're having a problem with a specific service or you'd like some functionality added to it, it is likely that the problem is not with our deployment method, but with the service itself. You may wish to report that problem at the source, upstream, and not to us.
+- This Ansible playbook installs tens of separate services. If you're having a problem with a specific one, it is likely that the problem is with the service itself. You may wish to report that problem at the source, upstream.
+
+- This playbook intends to focus solely on Matrix and Matrix-related services. If your request is not specific to them, you may as well to consider to submit it to the mash-playbook project: https://github.com/mother-of-all-self-hosting/mash-playbook
 
 - This is a community project with no financial backing. The easiest way to get a feature into this project is to just develop it yourself.
 -->

.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,17 @@
 	],
 	"packageRules": [
 		{
-			"matchSourceUrlPrefixes": [
+			"ignoreUnstable": false,
-				"https://github.com/devture/com.devture.ansible.role",
+			"matchSourceUrls": [
-				"https://github.com/mother-of-all-self-hosting"
+				"https://github.com/devture/com.devture.ansible.role{/,}**",
-			],
+				"https://github.com/mother-of-all-self-hosting{/,}**"
-			"ignoreUnstable": false
+			]
 		}
 	],
 	"ignoreDeps": [
 		"ghcr.io/matrixgpt/matrix-chatgpt-bot"
-	]
+	],
+	"pre-commit": {
+		"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
@@ -21,7 +25,7 @@ jobs:
           # Issues/PRs
           ######################################################################
           exempt-assignees: 'spantaleev,aine-etke'
-          operations-per-run: 100
+          operations-per-run: 500
           # Use this to do a dry run from a pull request
           # debug-only: true
           ######################################################################

.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@v5
+        with:
+          add-issue-labels: 'outdated'
+          process-only: 'issues, prs'

.github/workflows/matrix.yml

@@ -1,9 +1,13 @@
+# 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:
 
 jobs:
   yamllint:
@@ -24,3 +28,11 @@ jobs:
         uses: ansible-community/ansible-lint-action@v6.17.0
         with:
           path: roles/custom
+  precommit:
+    name: Run pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1

.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+---
+default_install_hook_types: [pre-push]
+
+exclude: "LICENSES/"
+
+# See: https://pre-commit.com/hooks.html
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # - id: check-executables-have-shebangs
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-toml
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        args: ["--skip=*.po,*.pot,i18n/"]
+  - repo: https://github.com/fsfe/reuse-tool  # https://reuse.software/dev/#pre-commit-hook
+    rev: v5.0.2
+    hooks:
+      - id: reuse

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/AGPL-3.0-or-later.txt

@@ -0,0 +1,235 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+                            Preamble
+
+The GNU Affero General Public License is a free, copyleft license for software and other kinds of works, specifically designed to ensure cooperation with the community in the case of network server software.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works.  By contrast, our General Public Licenses are intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users.
+
+When we speak of free software, we are referring to freedom, not price.  Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+Developers that use our General Public Licenses protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License which gives you legal permission to copy, distribute and/or modify the software.
+
+A secondary benefit of defending all users' freedom is that improvements made in alternate versions of the program, if they receive widespread use, become available for other developers to incorporate.  Many developers of free software are heartened and encouraged by the resulting cooperation.  However, in the case of software used on network servers, this result may fail to come about. The GNU General Public License permits making a modified version and letting the public access it on a server without ever releasing its source code to the public.
+
+The GNU Affero General Public License is designed specifically to ensure that, in such cases, the modified source code becomes available to the community.  It requires the operator of a network server to provide the source code of the modified version running there to the users of that server.  Therefore, public use of a modified version, on a publicly accessible server, gives the public access to the source code of the modified version.
+
+An older license, called the Affero General Public License and published by Affero, was designed to accomplish similar goals.  This is a different license, not a version of the Affero GPL, but Affero has released a new version of the Affero GPL which permits relicensing under this license.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+                       TERMS AND CONDITIONS
+
+0. Definitions.
+
+"This License" refers to version 3 of the GNU Affero General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this License.  Each licensee is addressed as "you".  "Licensees" and "recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy.  The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based on the Program.
+
+To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy.  Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other parties to make or receive copies.  Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License.  If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+The "source code" for a work means the preferred form of the work for making modifications to it.  "Object code" means any non-source form of a work.
+
+A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form.  A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities.  However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work.  For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+2. Basic Permissions.
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met.  This License explicitly affirms your unlimited permission to run the unmodified Program.  The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work.  This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force.  You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright.  Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below.  Sublicensing is not allowed; section 10 makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7.  This requirement modifies the requirement in section 4 to "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy.  This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged.  This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit.  Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+
+6. Conveying Non-Source Forms.
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source.  This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+    d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge.  You need not require recipients to copy the Corresponding Source along with the object code.  If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source.  Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling.  In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage.  For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product.  A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+"Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source.  The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information.  But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed.  Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+
+7. Additional Terms.
+"Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law.  If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it.  (Additional permissions may be written to require their own removal in certain cases when you modify the work.)  You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10.  If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term.  If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+
+8. Termination.
+
+You may not propagate or modify a covered work except as expressly provided under this License.  Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License.  If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run a copy of the Program.  Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance.  However, nothing other than this License grants you permission to propagate or modify any covered work.  These actions infringe copyright if you do not accept this License.  Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License.  You are not responsible for enforcing compliance by third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations.  If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License.  For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+
+11. Patents.
+
+A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based.  The work thus licensed is called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version.  For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement).  To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License.  You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License.  If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+
+13. Remote Network Interaction; Use with the GNU General Public License.
+
+Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software.  This Corresponding Source shall include the Corresponding Source for any work covered by version 3 of the GNU General Public License that is incorporated pursuant to the following paragraph.
+
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU General Public License into a single combined work, and to convey the resulting work.  The terms of this License will continue to apply to the part which is the covered work, but the work with which it is combined will remain governed by version 3 of the GNU General Public License.
+
+14. Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions of the GNU Affero General Public License from time to time.  Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program specifies that a certain numbered version of the GNU Affero General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation.  If the Program does not specify a version number of the GNU Affero General Public License, you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU Affero General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions.  However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program.  It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
+
+     <one line to give the program's name and a brief idea of what it does.>
+     Copyright (C) <year>  <name of author>
+
+     This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+
+     You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If your software can interact with users remotely through a computer network, you should also make sure that it provides a way for users to get its source.  For example, if your program is a web application, its interface could display a "Source" link that leads users to an archive of the code.  There are many ways you could offer source, and different solutions will be better for different programs; see section 13 for the specific requirements.
+
+You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU AGPL, see <http://www.gnu.org/licenses/>.

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

README.md

@@ -1,4 +1,4 @@
-[![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
 
@@ -52,7 +52,9 @@ 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) |
-| [Dendrite](https://github.com/matrix-org/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) |
+| [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. continuwuity is a continuation of conduwuit. | [Link](docs/configuring-playbook-continuwuity.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,6 +66,7 @@ Web clients for Matrix that you can host on your own domains.
 | [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) |
 | [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) |
 
 ### Server Components
 
@@ -72,12 +75,14 @@ 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) |
+| [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 [is possible](docs/configuring-playbook-own-webserver.md) | [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](docs/configuring-playbook-own-webserver.md) is also possible. | [Link](docs/configuring-playbook-traefik.md) |
 | [Let's Encrypt](https://letsencrypt.org/) | ✅ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
 | [Exim](https://www.exim.org/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
 | [ma1sd](https://github.com/ma1uta/ma1sd) | ❌ | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
 | [ddclient](https://github.com/linuxserver/docker-ddclient) | ❌ | Dynamic DNS | [Link](docs/configuring-playbook-dynamic-dns.md) |
+| [LiveKit Server](https://github.com/livekit/livekit) | ❌ | WebRTC server for audio/video calls | [Link](docs/configuring-playbook-livekit-server.md) |
+| [Livekit JWT Service](https://github.com/livekit/livekit-jwt-service) | ❌ | JWT service for integrating [Element Call](./configuring-playbook-element-call.md) with [LiveKit Server](./configuring-playbook-livekit-server.md) | [Link](docs/configuring-playbook-livekit-jwt-service.md) |
 
 ### Authentication
 
@@ -88,10 +93,10 @@ 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-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | ❌ | Proxy that handles Matrix registration requests and forwards them to LDAP | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
-| [matrix-registration](https://github.com/ZerataX/matrix-registration) | ❌ | A simple python application to have a token based Matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
+| [matrix-registration](https://github.com/ZerataX/matrix-registration) | ❌ | Simple python application to have a token based Matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
-| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (UVS) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
+| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
-| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
+| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | Spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
 
 ### File Storage
 
@@ -101,7 +106,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
 
@@ -115,6 +120,7 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [mautrix-gmessages](https://github.com/mautrix/gmessages) | ❌ | Bridge to [Google Messages](https://messages.google.com/) | [Link](docs/configuring-playbook-bridge-mautrix-gmessages.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) |
+| [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) |
@@ -135,7 +141,6 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [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) |
-| [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
@@ -144,13 +149,13 @@ 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) | ❌ | A plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
+| [maubot](https://github.com/maubot/maubot) | ❌ | Plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
-| [Honoroit](https://github.com/etkecc/honoroit) | ❌ | A helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
+| [Honoroit](https://github.com/etkecc/honoroit) | ❌ | Helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
-| [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | A moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
+| [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | Moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
-| [Draupnir](https://github.com/the-draupnir-project/Draupnir) | ❌ | 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))|
+| [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))|
 | [Buscarron](https://github.com/etkecc/buscarron) | ❌ | Web forms (HTTP POST) to Matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
 
 ### Administration
@@ -161,8 +166,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) |
+| [synapse-admin](https://github.com/etkecc/synapse-admin) | ❌ | Web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
-| 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,15 +179,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_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_accept_invite](https://github.com/matrix-org/synapse-auto-accept-invite) | ❌ | 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) |
+| [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) |
 | [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) |
+| [Etherpad](https://etherpad.org) | ❌ | Open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
-| [Jitsi](https://jitsi.org/) | ❌ | An open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
+| [Jitsi](https://jitsi.org/) | ❌ | Open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
-| [Cactus Comments](https://cactus.chat) | ❌ | A federated comment system built on Matrix | [Link](docs/configuring-playbook-cactus-comments.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) | ❌ | An E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.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
 
@@ -198,6 +204,12 @@ When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up w
 
 - GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
 
+## 🌐 Translation
+
+See the [i18n/README.md](i18n/README.md) file for more information about translation.
+
+Translations are still work in progress.
+
 ## 🤝 Related
 
 You may also be interested in [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) - another Ansible playbook for self-hosting non-Matrix services (see its [List of supported services](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md)).

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

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2024 Suguru Hirahara
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+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",
+    "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"
+
+# See https://reuse.software/faq/#aggregate-info
+[[annotations]]
+path = [
+    "i18n/**/*.po",
+    "i18n/**/*.pot"
+]
+precedence = "aggregate"
+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.
@@ -52,7 +59,7 @@ Hopefully, Synapse defaults would also change the same way and we'd see the numb
 
 With this configuration change in place, projects like [MatrixRooms.info](https://matrixrooms.info/) (made by [etke.cc](https://etke.cc/)) and potentially others in the future, can discover, index the metadata (room address, title, topic, number of users, etc.) and make public rooms browsable & searchable across the whole Matrix Federation. It'd be great if users joining Matrix could more easily find interesting communities that match their interests!
 
-On the **media side of things**, besides Jitsi getting better Matrix integration (via the aforementioned Matrix User Verification Service), we've also had some [Coturn security tightening](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues) as well as [performance optimizations](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#coturn-can-now-use-host-networking) for configurations exposing lots of network ports.
+On the **media side of things**, besides Jitsi getting better Matrix integration (via the aforementioned Matrix User Verification Service), we've also had some [coturn security tightening](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues) as well as [performance optimizations](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#coturn-can-now-use-host-networking) for configurations exposing lots of network ports.
 
 [Element Call](https://github.com/element-hq/element-call) seems to have become a nice and polished product lately (as proclaimed in [The Matrix Holiday Update 2023](https://matrix.org/blog/2023/12/25/the-matrix-holiday-update-2023/)), so 2024 is likely the year we'll see support for it in the playbook. Element Call depends on the [LiveKit](https://livekit.io/) streaming server (which is also useful to developers even by itself), so the first step is likely to see LiveKit support in mash-playbook via a reusable Ansible role. Such a LiveKit Ansible role could later easily land in matrix-docker-ansible-deploy and an Element Call static website could be hooked to it.
 
@@ -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/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/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.
@@ -32,7 +37,17 @@ done
 sed --in-place 's/matrix_mautrix_meta_instagram_meta_mode: \(.*\)/matrix_mautrix_meta_instagram_meta_mode: instagram/g' $instagram_role_path/defaults/main.yml
 sed --in-place 's/matrix_mautrix_meta_instagram_identifier: \(.*\)/matrix_mautrix_meta_instagram_identifier: matrix-mautrix-meta-instagram/g' $instagram_role_path/defaults/main.yml
 
-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

conf.py

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2024 Slavi Pantaleev <slavi@devture.com>
+# SPDX-FileCopyrightText: 2024 Suguru Hirahara <acioustick@noreply.codeberg.org>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Configuration file for the Sphinx documentation builder.
+# Also see the `i18n/` directory.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'matrix-docker-ansible-deploy'
+copyright = '2018-%Y, Slavi Pantaleev, Aine Etke, MDAD community members'
+author = 'Slavi Pantaleev, Aine Etke, MDAD community members'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+needs_sphinx = '8.1' # For the copyright year placeholder (%Y). Specified with pyproject.toml as well.
+
+extensions = [
+	'myst_parser',
+	'sphinx_markdown_builder'
+]
+myst_gfm_only = True
+myst_heading_anchors = 4 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors
+
+master_doc = 'README'
+source_suffix = {'.md': 'markdown'}
+
+# Though the default config file advocates exclude_patterns, it is straightforward for us to use include_patterns to select directories explicitly.
+include_patterns = [
+	'docs/*',
+	'i18n/README.md',
+	'*.md',
+]
+
+locale_dirs = ['i18n/locales/']
+gettext_compact = False
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# html_theme = 'alabaster'
+# html_static_path = ['_static']

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,7 +70,7 @@ 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 -->
 
@@ -84,3 +91,5 @@ If your server and services experience issues, feel free to come to [our support
 - [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/).
 
@@ -29,9 +38,12 @@ 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).
 
@@ -42,54 +54,58 @@ To run Ansible in a (Docker) container on the Matrix server itself, you need to
 - you **either** need to install Docker manually first. Follow [the upstream instructions](https://docs.docker.com/engine/install/) for your distribution and consider setting `matrix_playbook_docker_installation_enabled: false` in your `vars.yml` file, to prevent the playbook from installing Docker
 - **or** you need to run the playbook in another way (e.g. [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)) at least the first time around
 
-Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/..`, etc.), as described in [configuring the playbook](configuring-playbook.md).
+Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/…`, etc.), as described in [configuring the playbook](configuring-playbook.md).
 
 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:11.1.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:11.1.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:
 
@@ -97,11 +113,11 @@ To authenticate at your server using a password, you need to add a package. So,
 apk add sshpass
 ```
 
-Then, to be asked for the password whenever running an  `ansible-playbook` command add `--ask-pass` to the arguments of the command.
+Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.
 
 #### 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

docs/configuring-dns.md

@@ -1,9 +1,46 @@
-# 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.
 
+## DNS settings for services enabled by default
+
+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-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 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.
+
+Be mindful as to how long it will take for the DNS records to propagate.
+
+**Note**: if you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail.
+
 ## DNS setting for server delegation (optional)
 
 In the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user ID like `@alice:example.com` instead of `@alice:matrix.example.com`.
@@ -21,58 +58,6 @@ If you choose the recommended method (file-based delegation), you do not need to
 
 On the other hand, if you choose this method (setting up a DNS SRV record), you need to configure the additional DNS record as well as adjust SSL certificate handling. Take a look at this documentation for more information: [Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)
 
-## DNS settings for services enabled by default
-
-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`   |
-| 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).
-
-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.
-
-Be mindful as to how long it will take for the DNS records to propagate.
-
-If you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail.
-
-## DNS settings for optional services/features
-
-For other services which may need subdomain settings, see the table below and configure the DNS (`CNAME`) records accordingly.
-
-| Used by component                                                                                                          | Type  | Host                           | Priority | Weight | Port | Target                             |
-| -------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | -----------------------------------|
-| [Dimension](configuring-playbook-dimension.md) integration server                                                          | CNAME | `dimension`                    | -        | -      | -    | `matrix.example.com`               |
-| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform                                                         | CNAME | `jitsi`                        | -        | -      | -    | `matrix.example.com`               |
-| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system                                         | CNAME | `stats`                        | -        | -      | -    | `matrix.example.com`               |
-| [Go-NEB](configuring-playbook-bot-go-neb.md) bot                                                                           | CNAME | `goneb`                        | -        | -      | -    | `matrix.example.com`               |
-| [Sygnal](configuring-playbook-sygnal.md) push notification gateway                                                         | CNAME | `sygnal`                       | -        | -      | -    | `matrix.example.com`               |
-| [ntfy](configuring-playbook-ntfy.md) push notifications server                                                             | CNAME | `ntfy`                         | -        | -      | -    | `matrix.example.com`               |
-| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor                                                     | CNAME | `etherpad`                     | -        | -      | -    | `matrix.example.com`               |
-| [Hydrogen](configuring-playbook-client-hydrogen.md) web client                                                             | CNAME | `hydrogen`                     | -        | -      | -    | `matrix.example.com`               |
-| [Cinny](configuring-playbook-client-cinny.md) web client                                                                   | CNAME | `cinny`                        | -        | -      | -    | `matrix.example.com`               |
-| [SchildiChat Web](configuring-playbook-client-schildichat-web.md) client                                                   | CNAME | `schildichat`                  | -        | -      | -    | `matrix.example.com`               |
-| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge                                                       | CNAME | `wsproxy`                      | -        | -      | -    | `matrix.example.com`               |
-| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot                                                            | CNAME | `buscarron`                    | -        | -      | -    | `matrix.example.com`               |
-| [rageshake](configuring-playbook-rageshake.md) bug report server                                                           | CNAME | `rageshake`                    | -        | -      | -    | `matrix.example.com`               |
-| [ma1sd](configuring-playbook-ma1sd.md) identity server                                                                     | SRV   | `_matrix-identity._tcp`        | 10       | 0      | 443  | `matrix.example.com`               |
-| [Postmoogle](configuring-playbook-bridge-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX    | `matrix`                       | 10       | 0      | -    | `matrix.example.com`               |
-| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge                                                       | TXT   | `matrix`                       | -        | -      | -    | `v=spf1 ip4:matrix-server-IP -all` |
-| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge                                                       | TXT   | `_dmarc.matrix`                | -        | -      | -    | `v=DMARC1; p=quarantine;`          |
-| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge                                                       | TXT   | `postmoogle._domainkey.matrix` | -        | -      | -    | get it from `!pm dkim`             |
-
-### SRV record for ma1sd
-
-To make ma1sd enable its federation features, you need to set up a `_matrix-identity._tcp` SRV record. Don't confuse this with the `_matrix._tcp` SRV record for server delegation. See the table above and [this section](configuring-playbook-ma1sd.md#adjusting-dns-records) for values which need to be specified.
-
-When setting up a SRV record, if you are asked for a service and protocol instead of a hostname split the host value from the table where the period is. For example use service as `_matrix-identity` and protocol as `_tcp`.
-
-### MX and TXT records for Postmoogle
-
-To make Postmoogle enable its email sending features, you need to configure MX and TXT (SPF, DMARC, and DKIM) records. See the table above for values which need to be specified.
-
 ---------------------------------------------
 
 [▶️](getting-the-playbook.md) When you're done with the DNS configuration and ready to proceed, continue with [Getting the playbook](getting-the-playbook.md).

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,26 +1,67 @@
+<!--
+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.
 
 See the project's [documentation](https://github.com/metio/matrix-alertmanager-receiver/blob/main/README.md) to learn what it does and why it might be useful to you.
 
-At the moment, **setting up this service's bot requires some manual actions** as described below in [Account and room preparation](#account-and-room-preparation).
-
 This service is meant to be used with an external [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) instance. It's **not** meant to be integrated with the [Prometheus & Grafana stack](./configuring-playbook-prometheus-grafana.md) installed by this playbook, because the Alertmanager component is not installed by it.
 
+## Prerequisites
+
+### Register the bot account
+
+This service uses a bot (with a username specified in `matrix_alertmanager_receiver_config_matrix_user_id_localpart`) for delivering messages.
+
+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.alertmanager.receiver password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+```
+
+### 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.
+
+### Join to rooms as the bot manually
+
+ℹ️ **This bot does not accept room invitations automatically**. To deliver messages to rooms, the bot must be joined to all rooms manually.
+
+For each new room you would like the bot to deliver alerts to, invite the bot to the room.
+
+Then, log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account, and log out.
+
+## Adjusting DNS records (optional)
+
+By default, this playbook installs matrix-alertmanager-receiver on the `matrix.` subdomain, at the `/matrix-alertmanager-receiver` path (https://matrix.example.com/matrix-alertmanager-receiver). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
+
+If you wish to adjust it, see the section [below](#adjusting-the-matrix-alertmanager-receiver-url-optional) for details about DNS configuration.
+
 ## Adjusting the playbook configuration
 
-To enable matrix-alertmanager-receiver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
 
 ```yaml
 matrix_alertmanager_receiver_enabled: true
 
-# If you'd like to change the username for this bot, uncomment and adjust. Otherwise, remove.
+# Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_alertmanager_receiver_config_matrix_user_id_localpart: "bot.alertmanager.receiver"
 
-# Specify the bot user's access token here.
+matrix_alertmanager_receiver_config_matrix_access_token: "ACCESS_TOKEN_HERE"
-# See the "Account and room preparation" section below.
-matrix_alertmanager_receiver_config_matrix_access_token: ''
 
 # Optionally, configure some mappings (URL-friendly room name -> actual Matrix room ID).
 #
@@ -33,15 +74,11 @@ 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)
-
-### Adjusting the matrix-alertmanager-receiver URL
-
-By default, this playbook installs matrix-alertmanager-receiver on the `matrix.` subdomain, at the `/matrix-alertmanager-receiver` path (https://matrix.example.com/matrix-alertmanager-receiver). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
 
 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.
 
-Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Change the default hostname and path prefix
@@ -49,46 +86,31 @@ matrix_alertmanager_receiver_hostname: alertmanager.example.com
 matrix_alertmanager_receiver_path_prefix: /
 ```
 
-## Adjusting DNS records
+If you've changed the default hostname, you may need to create a CNAME record for the matrix-alertmanager-receiver domain (`alertmanager.example.com`), which targets `matrix.example.com`.
 
-If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-alertmanager-receiver domain to the Matrix server.
+When setting, replace `example.com` with your own.
 
-See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+### Extending the configuration
 
-If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
+There are some additional things you may wish to configure about the component.
 
-## Account and room preparation
+Take a look at:
 
-The playbook can automatically create users, but it cannot automatically obtain access tokens, nor perform any of the other manual actions below.
+- `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
-`matrix-alertmanager-receiver` uses a bot (with a username specified in `matrix_alertmanager_receiver_config_matrix_user_id_localpart` - see above) for delivering messages. You need to **manually register this bot acccount and obtain an access token for it**.
-
-1. [Register a new user](registering-users.md): `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertmanager.receiver password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user`
-2. [Obtain an access token](obtaining-access-tokens.md) for the bot's user account
-3. Invite the bot to a room where you'd like to alerts to be delivered
-4. Log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account and log out
-5. (Optionally) Adjust `matrix_alertmanager_receiver_config_matrix_room_mapping` to create a mapping between the new room and its ID
-
-Steps 1 and 2 above only need to be done once, while preparing your [configuration](#adjusting-the-playbook-configuration).
-
-Steps 3 and 4 need to be done for each new room you'd like the bot to deliver alerts to. Step 5 is optional and provides cleaner `/alert/` URLs.
 
 ## Installing
 
-Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
+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
 
@@ -111,6 +133,17 @@ route:
     - receiver: matrix
 ```
 
-.. 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`.
+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`.
 
-This bot does **not** accept room invitations automatically (like many other bots do). To deliver messages to rooms, **the bot must be joined to all rooms manually** - see Step 4 of the [Account and room preparation](#account-and-room-preparation) section.
+## 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,10 +1,17 @@
+<!--
+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)
 
-Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
+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.
 
-This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the [appservice method](https://docs.mau.fi/bridges/general/double-puppeting.html#appservice-method-new). The Appservice Double Puppet service is an implementation of this approach.
+This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the appservice method. The service is an implementation of this approach.
 
-Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method.
+Previously, bridges supported performing double-puppeting with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method.
 
 ## Adjusting the playbook configuration
 
@@ -14,23 +21,27 @@ To enable the Appservice Double Puppet service, add the following configuration
 matrix_appservice_double_puppet_enabled: true
 ```
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the service.
+
+Take a look at:
+
+- `roles/custom/matrix-appservice-double-puppet/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_double_puppet_registration_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
 
-When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method.
+Installing the service will automatically enable double puppeting for all bridges that support double puppeting via the appservice method.

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

@@ -1,3 +1,10 @@
+<!--
+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.
@@ -16,90 +23,92 @@ Normal Draupnir does come with the benefit of access to Synapse Admin features.
 
 Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
 
-## Installation
+## Prerequisites
 
-### Create a main management room.
+### Create a main management room
 
-The playbook does not create a management room for your Main Draupnir. This task you have to do on your own.
+The playbook does not create a management room for your Main Draupnir. You **need to create the room manually** before setting up the bot.
 
-The management room has to be given an alias and be public when you are setting up the bot for the first time as the bot does not differentiate between invites and invites to the management room.
+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.
 
 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.
 
-As noted in the Draupnir install instructions the control room is sensitive. The following is said about the control room in the Draupnir install instructions.
+> [!WARNING]
->Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
+> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
 
-### Give your main management room an alias.
+## Adjusting the playbook configuration
 
-Give the room from step 1 an alias. This alias can be anything you want and its recommended for increased security during the setup phase of the bot that you make this alias be a random string. You can give your room a secondary human readable alias when it has been locked down after setup phase.
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE`.
-
-### Adjusting the playbook configuration.
-
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
-
-You must replace `ALIAS_FROM_STEP_2_GOES_HERE` with the alias you created in step 2.
 
 ```yaml
 matrix_appservice_draupnir_for_all_enabled: true
 
-matrix_appservice_draupnir_for_all_master_control_room_alias: "ALIAS_FROM_STEP_2_GOES_HERE"
+matrix_appservice_draupnir_for_all_config_adminRoom: "MANAGEMENT_ROOM_ALIAS_HERE"
 ```
 
-### Installing
+### Extending the configuration
+
+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_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # 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_configuration_yaml`.
+  protectAllJoinedRooms: true
+```
+
+You can refer to the upstream [documentation](https://github.com/the-draupnir-project/Draupnir) for more configuration documentation.
+
+**Notes**:
+
+- The playbook ships a full copy of the example config that does transfer to provisioned Draupnirs in the production-bots.yaml.j2 file in the template directory of the role.
+
+- Config extension does not affect the appservices config as this config is not extensible in current Draupnir anyway. It instead touches the config passed to the Draupnirs that your Appservice creates. So the example above (`protectAllJoinedRooms: true`) makes all provisioned Draupnirs protect all joined rooms.
+
+## 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.
 
 ## 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 allis almost identical to Draupnir bot mode.
+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.
 
 ### 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))
 
-To allow users or whole homeservers you type /plain @draupnir-main:example.com 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 register. 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.
+### How to provision a D4A once you are allowed to
 
-Open a DM with @draupnir-main:example.com and if using an Element client send a message into this DM to finalise creating it. 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.
+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.
 
 Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
-
-### Configuration of D4A
-
-You can refer to the upstream [documentation](https://github.com/the-draupnir-project/Draupnir) for more configuration documentation. Please note that the playbook ships a full copy of the example config that does transfer to provisioned Draupnirs in the production-bots.yaml.j2 file in the template directory of the role.
-
-Please note that Config extension does not affect the appservices config as this config is not extensible in current Draupnir anyways. Config extension instead touches the config passed to the Draupnirs that your Appservice creates. So for example below makes all provisioned Draupnirs protect all joined rooms.
-
-You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
-
-For example to change Draupnir's `protectAllJoinedRooms` option to `true` you would add the following to your `vars.yml` file.
-
-```yaml
-matrix_appservice_draupnir_for_all_extension_yaml: |
-  # Your custom YAML configuration goes here.
-  # This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_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`.
-  protectAllJoinedRooms: true
-```

docs/configuring-playbook-backup-borg.md

@@ -1,87 +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.
 
-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).
+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
-The backup will run based on `backup_borg_schedule` var (systemd timer calendar), default: 4am every day.
+- 📁 `roles/galaxy/backup_borg/docs/configuring-backup-borg.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles)
-
-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. 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.
-
-**Note**: the component is not managed by this repository but its [own repository](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg).
-
-## Prerequisites
-
-1. If you do not disable Postgres-backup support, make sure that the Postgres version of your homeserver's database is compatible with borgmatic.
-
-2. Create a new SSH key:
-
-    ```sh
-    ssh-keygen -t ed25519 -N '' -f matrix-borg-backup -C matrix
-    ```
-
-    This can be done on any machine and you don't need to place the key in the `.ssh` folder. It will be added to the Ansible config later.
-
-3. Add the **public** part of this SSH key (the `matrix-borg-backup.pub` file) to your BorgBackup provider/server:
-
-    If you plan to use a hosted solution, follow their instructions. If you have your own server, copy the key over:
-
-    ```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'
-    ```
-
-## Adjusting the playbook configuration
-
-Minimal working configuration (`inventory/host_vars/matrix.example.com/vars.yml`) to enable BorgBackup:
-
-```yaml
-backup_borg_enabled: true
-backup_borg_location_repositories:
- - ssh://USER@HOST/./REPO
-backup_borg_storage_encryption_passphrase: "PASSPHRASE"
-backup_borg_ssh_key_private: |
-  -----BEGIN OPENSSH PRIVATE KEY-----
-  TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
-  xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
-  bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
-  RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
-  ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
-  -----END OPENSSH PRIVATE KEY-----
-```
-
-where:
-
-* USER - SSH user of a provider/server
-* HOST - SSH host of a provider/server
-* REPO - BorgBackup repository name, it will be initialized on backup start, eg: `matrix`, regarding Syntax see [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls)
-* PASSPHRASE - passphrase used for encrypting backups, you may generate it with `pwgen -s 64 1` or use any password manager
-* PRIVATE KEY - the content of the **private** part of the SSH key you created before. The whole key (all of its belonging lines) under `backup_borg_ssh_key_private` needs to be indented with 2 spaces
-
-To backup without encryption, add `backup_borg_encryption: 'none'` to your vars. This will also enable the `backup_borg_unknown_unencrypted_repo_access_is_ok` variable.
-
-`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 want to exclude certain directories or file patterns from the backup using the `backup_borg_location_exclude_patterns` variable.
-
-Check the [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) file for the full list of available options.
-
-## 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
-
-For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly 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">
@@ -30,7 +37,7 @@ Depending on your current `vars.yml` file and desired configuration, **you may r
 
 ### Base configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_baibot_enabled: true
@@ -38,12 +45,12 @@ 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
 
-# Generate a strong password here. Consider generating it with `pwgen -s 64 1`.
+# 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'
 
 # An optional passphrase to use for backing up and recovering the bot's encryption keys.
-# You can put any string here, but generating a strong one is preferred (e.g. `pwgen -s 64 1`).
+# You can create one with a command like `pwgen -s 64 1`.
 #
 # If set to null, the recovery module will not be used and losing your session/database
 # will mean you lose access to old messages in encrypted room.
@@ -78,7 +85,7 @@ To specify who is considered a bot [👮‍♂️ Administrator](https://github.
 
 If `matrix_admin` is already configured in your `vars.yml` configuration, you can skip this section.
 
-**If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+**If necessary**, add the following configuration to your `vars.yml` file:
 
 ```yaml
 # Uncomment to add one or more admins to this bridge:
@@ -87,7 +94,7 @@ If `matrix_admin` is already configured in your `vars.yml` configuration, you ca
 #   - "@*:example.com"
 #   - "@admin:example.net"
 #
-# .. unless you've made yourself an admin of all bots/bridges like this:
+# … unless you've made yourself an admin of all bots/bridges like this:
 #
 # matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
 ```
@@ -107,7 +114,7 @@ Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is op
 
 **Note**: Once initially configured, the allowed users list **cannot be managed via Ansible anymore**. It can only be managed subsequently via bot commands.
 
-**If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+**If necessary**, add the following configuration to your `vars.yml` file:
 
 ```yaml
 # Uncomment and adjust the bot users if necessary:
@@ -123,7 +130,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).
 
@@ -146,15 +153,13 @@ matrix_bot_baibot_config_agents_static_definitions_anthropic_enabled: true
 
 matrix_bot_baibot_config_agents_static_definitions_anthropic_config_api_key: "YOUR_API_KEY_HERE"
 
-# If you'd like to use another text-generation agent, uncomment and adjust:
+# Uncomment and adjust this part if you'd like to use another text-generation agent
 # matrix_bot_baibot_config_agents_static_definitions_anthropic_config_text_generation_model_id: claude-3-5-sonnet-20240620
 
 # The playbook defines a default prompt for all statically-defined agents.
 # You can adjust it in the `matrix_bot_baibot_config_agents_static_definitions_prompt` variable,
 # or you can adjust it below only for the Anthropic agent.
 # matrix_bot_baibot_config_agents_static_definitions_anthropic_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
-
-# See `defaults/main.yml` in the baibot role for more configuration options.
 ```
 
 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.
@@ -184,8 +189,6 @@ matrix_bot_baibot_config_agents_static_definitions_groq_config_text_generation_m
 #
 # matrix_bot_baibot_config_agents_static_definitions_groq_config_speech_to_text_enabled: true
 # matrix_bot_baibot_config_agents_static_definitions_groq_config_speech_to_text_model_id: whisper-large-v3
-
-# See `defaults/main.yml` in the baibot role for more configuration options.
 ```
 
 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/groq`.
@@ -212,8 +215,6 @@ matrix_bot_baibot_config_agents_static_definitions_mistral_config_api_key: "YOUR
 
 # Uncomment and adjust this part if you're not happy with these defaults:
 # matrix_bot_baibot_config_agents_static_definitions_mistral_config_text_generation_model_id: mistral-large-latest
-
-# See `defaults/main.yml` in the baibot role for more configuration options.
 ```
 
 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/mistral`.
@@ -241,9 +242,7 @@ 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
-
-# See `defaults/main.yml` in the baibot role for more configuration options.
 ```
 
 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`.
@@ -258,7 +257,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).
 
@@ -313,7 +312,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).
 
@@ -362,6 +361,15 @@ matrix_bot_baibot_config_initial_global_config_handler_image_generation: null
 
 **Note**: these are initial defaults for the bot's global configuration. As such, changing any of these values subsequently has no effect on the bot's behavior. **Once initially configured the global configuration cannot be managed Ansible**, but only via bot commands.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-baibot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bot-baibot/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_baibot_configuration_extension_yaml` variable
+
 ## Installing
 
 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@@ -383,7 +391,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-To use the bot, invite the `@baibot:example.com` bot user into a room.
+To use the bot, invite it to any existing Matrix room (`/invite @baibot:example.com` where `example.com` is your base domain, not the `matrix.` domain).
 
 If you're an allowed bot [👥 user](https://github.com/etkecc/baibot/blob/main/docs/access.md#user) (see [👥 Initial users configuration](#-initial-users-configuration)), the bot will accept your invitation and join the room.
 
@@ -391,15 +399,17 @@ After joining, the bot will introduce itself and show information about the [✨
 
 If you've [🤖 configured one or more agents via Ansible](#-configuring-agents-via-ansible) and have [🤝 configured initial default handlers](#configuring-initial-default-handlers), the bot will immediately be able to make use of these agents for this new room. Otherwise, you will need to configure agents and/or handlers via chat commands.
 
-Send `!bai help` to the room at any time to see the bot's help menu for additional commands.
+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,12 +1,28 @@
+<!--
+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`.
+
+When setting, replace `example.com` with your own.
+
 ## Adjusting the playbook configuration
 
-To enable Buscarron, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_buscarron_enabled: true
@@ -14,7 +30,7 @@ matrix_bot_buscarron_enabled: true
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_buscarron_login: bot.buscarron
 
-# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
+# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
 matrix_bot_buscarron_password: PASSWORD_FOR_THE_BOT
 
 # Adjust accepted forms
@@ -29,13 +45,11 @@ matrix_bot_buscarron_forms:
 matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
 ```
 
-### Adjusting the Buscarron URL
+### Adjusting the Buscarron URL (optional)
-
-By default, this playbook installs Buscarron on the `buscarron.` subdomain (`buscarron.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
 
 By tweaking the `matrix_bot_buscarron_hostname` and `matrix_bot_buscarron_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Switch to the domain used for Matrix services (`matrix.example.com`),
@@ -46,14 +60,18 @@ matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_bot_buscarron_path_prefix: /buscarron
 ```
 
-## Adjusting DNS records
+After changing the domain, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
-
-By default, you will need to create a CNAME record for `buscarron`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 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:
@@ -75,7 +93,11 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-To use the bot, invite the `@bot.buscarron:example.com` to the room you specified in a config, after that any point your form to the form url, example for the `contact` form:
+To use the bot, invite it to the room you specified on your `vars.yml` file (`/invite @bot.buscarron:example.com` where `example.com` is your base domain, not the `matrix.` domain).
+
+After the bot joins the room, anyone can call the web form via HTTP POST method.
+
+Here is an example for the `contact` form:
 
 ```html
 <form method="POST" action="https://buscarron.example.com/contact">
@@ -85,10 +107,20 @@ To use the bot, invite the `@bot.buscarron:example.com` to the room you specifie
 
 **Note**: to fight against spam, Buscarron is **very aggressive when it comes to banning** and will ban you if:
 
-- if you hit the homepage (HTTP `GET` request to `/`)
+- you hit the homepage (HTTP `GET` request to `/`)
-- if you submit a form to the wrong URL (`POST` request to `/non-existing-form`)
+- you submit a form to the wrong URL (`POST` request to `/non-existing-form`)
-- if `hasemail` is enabled for the form (like in the example above) and you don't submit an `email` field
+- `hasemail` is enabled for the form (like in the example above) and you don't submit an `email` field
 
 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,18 +1,32 @@
+<!--
+SPDX-FileCopyrightText: 2023 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2023 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up matrix-bot-chatgpt (optional, unmaintained)
 
-**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.
+**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.
 
 The playbook can install and configure [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) for you.
 
 Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client!
 
-## Register the bot account
+See the project's [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot/blob/main/README.md) to learn what it does and why it might be useful to you.
 
-The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
+## Prerequisites
 
-You **need to register the bot user manually** before setting up the bot.
+### Obtain an OpenAI API key
 
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
+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).
+
+### 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):
 
@@ -20,36 +34,41 @@ You can use the playbook to [register a new user](registering-users.md):
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-## Get an access token and create encryption keys
+### Obtain an access token and create encryption keys
 
-Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+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
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+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
 
-# Obtain a new API key from https://platform.openai.com/account/api-keys
+matrix_bot_chatgpt_openai_api_key: 'API_KEY_HERE'
-matrix_bot_chatgpt_openai_api_key: ''
 
-# This is the default username
+# 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 access token (from bot user above)
+matrix_bot_chatgpt_matrix_access_token: 'ACCESS_TOKEN_HERE'
-# see: https://webapps.stackexchange.com/questions/131056/how-to-get-an-access-token-for-element-riot-matrix
-matrix_bot_chatgpt_matrix_access_token: ''
 
-# Configuring the system promt used, needed if the bot is used for special tasks.
+# Configuring the system prompt 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.'
-
 ```
 
-You will need to get tokens for ChatGPT.
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-chatgpt/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 
 ## Installing
 
@@ -70,6 +89,10 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-To use the bot, invite the `@bot.chatgpt:example.com` to the room you specified in a config, after that start speaking to it, use the prefix if you configured one or mention the bot.
+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).
 
-You can also refer to the upstream [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot).
+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.
+
+## 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-chatgpt`.

docs/configuring-playbook-bot-draupnir.md

@@ -1,110 +1,198 @@
+<!--
+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.
 
-See the project's [documentation](https://github.com/the-draupnir-project/Draupnir/blob/main/README.md) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) to learn what it does and why it might be useful to you.
 
 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 step 5b.
+If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
 
-## Register the bot account
+## Prerequisites
 
-The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
+### Create a management room
 
-You **need to register the bot user manually** before setting up the bot.
+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.
 
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
+> [!WARNING]
+> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
 
-You can use the playbook to [register a new user](registering-users.md):
+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)).
 
-```sh
+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`.
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+
+## 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.
+
+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.
+
+### 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 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. Make sure to replace `CLEAN_ACCESS_TOKEN_HERE` with the access token you obtained just now.
+
+```yaml
+# Enables the native E2EE support
+matrix_bot_draupnir_config_experimentalRustCrypto: true
+
+# Access token which the bot will use for logging in.
+# Comment out `matrix_bot_draupnir_login_native` when using this option.
+matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
 ```
 
-If you would like Draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports ([see below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
-
-## Get an access token
-
-Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
-
-## Make sure the account is free from rate limiting
-
-You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Draupnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
-
-If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](configuring-playbook-synapse-admin.md) or running `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
-
-The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit` Replace `@bot.draupnir:example.com` with the MXID of your Draupnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Draupnir itself. If you made Draupnir Admin you can just use the Draupnir token.
-
-## 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.
-
-If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
-
-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`.
-
-Finally invite the `@bot.draupnir:example.com` account you created earlier into the room.
-
 ## Adjusting the playbook configuration
 
-Decide whether you want Draupnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Draupnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created earlier.
-
-### a. Configuration with E2EE support
-
-When using Pantalaimon, Draupnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
-
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
-# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
-matrix_pantalaimon_enabled: true
-
 # Enable Draupnir
 matrix_bot_draupnir_enabled: true
 
-# Tell Draupnir to use Pantalaimon
+# Uncomment and adjust this part if you'd like to use a username different than the default
-matrix_bot_draupnir_pantalaimon_use: true
+# matrix_bot_draupnir_login: bot.draupnir
 
-# User name and password for the bot. Required when using Pantalaimon.
+# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
-matrix_bot_draupnir_pantalaimon_username: "DRAUPNIR_USERNAME_FROM_STEP_1"
+# 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_pantalaimon_password: ### you should create a secure password for the bot account
+matrix_bot_draupnir_password: PASSWORD_FOR_THE_BOT
 
-matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+# 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_config_managementRoom: "MANAGEMENT_ROOM_ID_HERE"
 ```
 
-The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Draupnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
+### Create and invite the bot to the management room
+
+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
+```
+
+**Note**: the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
+
+### 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.
+
+**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
+
+The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
+
+#### Add the configuration
+
+To expose the APIs publicly, add the following configuration to your `vars.yml` file:
 
 ```yaml
-# Endpoint URL that Draupnir uses to interact with the Matrix homeserver (client-server API).
+matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
-# Set this to the pantalaimon URL if you're using that.
-matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_draupnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
-
-# Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
-# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
-matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
 ```
 
-### b. Configuration without E2EE support
+#### Obtain an access token for admin account
 
-When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account.
+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).
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+> [!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.
 
-You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with your own values.
+#### 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 ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit
+```
+
+**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.
+
+### Abuse Reports
+
+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_enabled: true
+matrix_bot_draupnir_config_web_abuseReporting: true
-
-matrix_bot_draupnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
-
-matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
 ```
 
-### c. Migrating from Mjolnir (Only required if migrating.)
+### Enabling synapse-http-antispam support
+
+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 and consulting the [enabling protections](#enabling-built-in-protections) guide can be helpful or consulting upstream documentation.
+
+<!--
+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.
+-->
+
+### Extending the configuration
+
+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:
+
+```yaml
+matrix_bot_draupnir_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_bot_draupnir_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_bot_draupnir_configuration_yaml`.
+  acceptInvitesFromSpace: "!qporfwt:example.com"
+```
+
+### Migrating from Mjolnir (Only required if migrating)
 
 Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable Mjolnir if you're doing migration.
 
+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.
 
 ## Installing
@@ -124,7 +212,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 Pantalaimon's password (`matrix_bot_draupnir_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_draupnir_pantalaimon_password` to let Pantalaimon know its new password.
+- If you change the bot password (`matrix_bot_draupnir_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_draupnir_password` to let the bot know its new password.
 
 ## Usage
 
@@ -154,7 +242,7 @@ 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. A popular policy list is maintained in the public `#community-moderation-effort-bl:neko.dev` room.
 
 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`
 
@@ -186,45 +274,10 @@ You can also **turn on various built-in [protections](https://the-draupnir-proje
 
 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 config get PROTECTION_NAME` (e.g. `!draupnir config get JoinWaveShortCircuit`).
+To **see the configuration options for a given protection**, send a `!draupnir protections show PROTECTION_NAME` (e.g. `!draupnir protections show JoinWaveShortCircuit`).
 
 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 **enable a given protection**, send a command like this: `!draupnir enable PROTECTION_NAME` (e.g. `!draupnir enable JoinWaveShortCircuit`).
 
 To **disable a given protection**, send a command like this: `!draupnir disable PROTECTION_NAME` (e.g. `!draupnir disable JoinWaveShortCircuit`).
-
-## Extending the configuration
-
-You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
-
-For example to change Draupnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
-
-```yaml
-matrix_bot_draupnir_configuration_extension_yaml: |
-  # Your custom YAML configuration goes here.
-  # This configuration extends the default starting configuration (`matrix_bot_draupnir_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_bot_draupnir_configuration_yaml`.
-  recordIgnoredInvites: true
-```
-
-## Abuse Reports
-
-Draupnir supports two methods to receive reports in the management room.
-
-The first method intercepts 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
-```
-
-The other method polls an synapse admin API endpoint and is hence only available when using synapse and when the Draupnir user is an admin user (see step 1). To enable it, set `pollReports: true` in Draupnir's config:
-
-```yaml
-matrix_bot_draupnir_configuration_extension_yaml: |
-  pollReports: true
-```

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

@@ -1,6 +1,16 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Yannick Goossens
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2025 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Go-NEB (optional, unmaintained)
 
-**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.
+**Note**: [Go-NEB](https://github.com/matrix-org/go-neb) is now an archived (**unmaintained**) project. We recommend not bothering with installing it. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) as a replacement, which can also be [installed using this playbook](configuring-playbook-bridge-hookshot.md). Consider using that bot instead of this one.
 
 The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
 
@@ -8,13 +18,13 @@ Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the ori
 
 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.
 
-## Registering the bot account
+## Prerequisites
 
-The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
+### Register the bot account
 
-You **need to register the bot user manually** before setting up the bot.
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
+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):
 
@@ -22,11 +32,22 @@ You can use the playbook to [register a new user](registering-users.md):
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
+### 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 Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+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
@@ -35,7 +56,7 @@ matrix_bot_go_neb_enabled: true
 # Use the access token you obtained in the step above.
 matrix_bot_go_neb_clients:
   - UserID: "@goneb:{{ matrix_domain }}"
-    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+    AccessToken: "ACCESS_TOKEN_FOR_GONEB_HERE"
     DeviceID: "DEVICE1"
     HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: true
@@ -44,7 +65,7 @@ matrix_bot_go_neb_clients:
     AcceptVerificationFromUsers: [":{{ matrix_domain }}"]
 
   - UserID: "@another_goneb:{{ matrix_domain }}"
-    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+    AccessToken: "ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE"
     DeviceID: "DEVICE2"
     HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: false
@@ -105,7 +126,7 @@ matrix_bot_go_neb_services:
       api_key: "AIzaSyA4FD39m9"
       cx: "AIASDFWSRRtrtr"
 
-# Get a key via https://api.imgur.com/oauth2/addclient
+# Obtain a key via https://api.imgur.com/oauth2/addclient
 # Select "oauth2 without callback url"
   - ID: "imgur_service"
     Type: "imgur"
@@ -190,47 +211,46 @@ matrix_bot_go_neb_services:
           msg_type: "m.text"  # Must be either `m.text` or `m.notice`
 ```
 
-### Adjusting the Go-NEB URL
+### Adjusting the Go-NEB URL (optional)
-
-By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
 
 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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+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 /buscarron subpath
+# Expose under the /go-neb subpath
 matrix_bot_go_neb_path_prefix: /go-neb
 ```
 
-## Adjusting DNS records
+After changing the domain, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
-
-By default, you will need to create a CNAME record for `goneb`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-go-neb/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bot-go-neb/templates/config.yaml.j2` for the bot's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_go_neb_configuration_extension_yaml` variable
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
 <!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
 ```sh
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,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
 
@@ -238,6 +258,10 @@ To use the bot, invite it to any existing Matrix room (`/invite @bot.go-neb:exam
 
 Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
 
-If you enabled the github_cmd service you can get the supported commands via `!github help`
+If you enabled the github_cmd service, send `!github help` to the bot in the room to see the available commands.
 
 You can also refer to the upstream [Documentation](https://github.com/matrix-org/go-neb).
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bot-go-neb`.

docs/configuring-playbook-bot-honoroit.md

@@ -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.
@@ -6,9 +14,15 @@ It's a bot you can use to setup **your own helpdesk on matrix**
 
 See the project's [documentation](https://github.com/etkecc/honoroit/blob/main/README.md) to learn what it does and why it might be useful to you.
 
+## Adjusting DNS records (optional)
+
+By default, this playbook installs Honoroit on the `matrix.` subdomain, at the `/honoroit` path (https://matrix.example.com/honoroit). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
+
+If you wish to adjust it, see the section [below](#adjusting-the-honoroit-url-optional) for details about DNS configuration.
+
 ## Adjusting the playbook configuration
 
-To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_honoroit_enabled: true
@@ -16,20 +30,18 @@ matrix_bot_honoroit_enabled: true
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_honoroit_login: honoroit
 
-# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
+# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
 matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT
 
 # Adjust this to your room ID
 matrix_bot_honoroit_roomid: "!qporfwt:{{ matrix_domain }}"
 ```
 
-### Adjusting the Honoroit URL
+### Adjusting the Honoroit URL (optional)
-
-By default, this playbook installs Honoroit on the `matrix.` subdomain, at the `/honoroit` path (https://matrix.example.com/honoroit). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
 
 By tweaking the `matrix_bot_honoroit_hostname` and `matrix_bot_honoroit_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Change the default hostname and path prefix
@@ -37,13 +49,17 @@ matrix_bot_honoroit_hostname: honoroit.example.com
 matrix_bot_honoroit_path_prefix: /
 ```
 
-## Adjusting DNS records
+If you've changed the default hostname, you may need to create a CNAME record for the Honoroit domain (`honoroit.example.com`), which targets `matrix.example.com`.
 
-If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server.
+When setting, replace `example.com` with your own.
 
-See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+### Extending the configuration
 
-If you've decided to use the default hostname, you won't need to do any extra DNS 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
 
@@ -66,8 +82,22 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-To use the bot, invite the `@honoroit:example.com` to the room you specified in config, after that any Matrix user can send a message to the `@honoroit:example.com` to start a new thread in that room.
+To use the bot, invite it to the room you specified on your `vars.yml` file (`/invite @honoroit:example.com` where `example.com` is your base domain, not the `matrix.` domain).
 
-Send `!ho help` to the room to see the bot's help menu for additional commands.
+After the bot joins the room, any Matrix user can send a message to it to start a new thread in that room.
+
+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,3 +1,15 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2023 Julian-Samuel Gebühr
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Erick Wibben
+SPDX-FileCopyrightText: 2022 Kolja Lampe
+SPDX-FileCopyrightText: 2023 - 2024 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up matrix-registration-bot (optional)
 
 The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
@@ -6,7 +18,7 @@ The bot allows you to easily **create and manage registration tokens** aka. invi
 
 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.
 
-## Configuration
+## Adjusting the playbook configuration
 
 To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
@@ -17,7 +29,7 @@ matrix_bot_matrix_registration_bot_enabled: true
 # 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 here. Consider generating it with `pwgen -s 64 1`
+# 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
@@ -29,6 +41,15 @@ matrix_synapse_registration_requires_token: true
 
 The bot account will be created automatically.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bot-matrix-registration-bot/templates/config.yaml.j2` for the bridge's default configuration
+
 ## Installing
 
 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@@ -52,14 +73,27 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 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).
 
-In this room send `help` and the bot will reply with all options.
+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).
+If you have any questions, or if you need help setting it up, read the [troubleshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md) or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
 
 To clean the cache (session & encryption data) after you changed the bot's username, changed the login method from access_token to password etc… you can use:
 
 ```sh
 just run-tags bot-matrix-registration-bot-clean-cache
 ```
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bot-matrix-registration-bot`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: ERROR, INFO, DEBUG
+matrix_bot_matrix_registration_bot_logging_level: DEBUG
+```

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.
@@ -8,7 +16,7 @@ See the project's [documentation](https://github.com/anoadragon453/matrix-remind
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_matrix_reminder_bot_enabled: true
@@ -16,13 +24,22 @@ matrix_bot_matrix_reminder_bot_enabled: true
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_matrix_reminder_bot_matrix_user_id_localpart: bot.matrix-reminder-bot
 
-# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
+# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
 matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
 
 # Adjust this to your timezone
 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:
@@ -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.
@@ -6,9 +17,15 @@ After setting up maubot, you can use the web management interface to make it do
 
 See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) to learn what it does and why it might be useful to you.
 
+## Adjusting DNS records (optional)
+
+By default, this playbook installs maubot on the `matrix.` subdomain, at the `/_matrix/maubot/` path (https://matrix.example.com/_matrix/maubot/). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**.
+
+If you wish to adjust it, see the section [below](#adjusting-the-maubot-url-optional) for details about DNS configuration.
+
 ## Adjusting the playbook configuration
 
-To enable maubot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_maubot_enabled: true
@@ -16,7 +33,7 @@ matrix_bot_maubot_enabled: true
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_maubot_login: bot.maubot
 
-# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
+# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
 matrix_bot_maubot_initial_password: PASSWORD_FOR_THE_BOT
 
 matrix_bot_maubot_admins:
@@ -25,13 +42,11 @@ matrix_bot_maubot_admins:
 
 You can add multiple admins. The admin accounts are only used to access the maubot administration interface.
 
-### Adjusting the maubot URL
+### Adjusting the maubot URL (optional)
-
-By default, this playbook installs maubot on the `matrix.` subdomain, at the `/_matrix/maubot/` path (https://matrix.example.com/_matrix/maubot/). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
 
 By tweaking the `matrix_bot_maubot_hostname` and `matrix_bot_maubot_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Change the default hostname and path prefix
@@ -39,13 +54,37 @@ matrix_bot_maubot_hostname: maubot.example.com
 matrix_bot_maubot_path_prefix: /
 ```
 
-## Adjusting DNS records
+If you've changed the default hostname, you may need to create a CNAME record for the maubot domain (`maubot.example.com`), which targets `matrix.example.com`.
 
-If you've changed the default hostname, **you may need to adjust your DNS** records to point the maubot domain to the Matrix server.
+When setting, replace `example.com` with your own.
 
-See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+### Extending the configuration
 
-If you've decided to use the default hostname, you won't need to do any extra DNS 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.
+
+You can customize the default maubot container image and install your own dependencies.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+matrix_bot_maubot_container_image_customizations_enabled: true
+
+# Adjust the Dockerfile and install ffmpeg.
+#
+matrix_bot_maubot_container_image_customizations_dockerfile_body_custom: |
+  RUN apk add --no-cache ffmpeg
+```
+
+Consult the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/) for more information about the syntax.
 
 ## Installing
 
@@ -75,8 +114,24 @@ You should start in the following order
 2. **Upload some Plugins**: Plugins can be obtained from [here](https://github.com/maubot/maubot#plugins) or any other source.
 3. **Create an instance**: An instance is the actual bot. You have to specify a client which the bot instance will use and the plugin (how the bot will behave)
 
-## Obtaining an access token
+## Obtain an access token
 
 This can be done via `mbc login` then `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). To run these commands, you'll first need to `exec` into the maubot container with `docker exec -it matrix-bot-maubot sh`.
 
-Alternatively, you can follow our generic [obtain an access token](obtaining-access-tokens.md) documentation. 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 give your bot issues in encrypted rooms. Read [more](https://docs.mau.fi/maubot/usage/basic.html#creating-clients).
+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.
+
+## 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,16 +1,27 @@
+<!--
+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.
 
 See the project's [documentation](https://github.com/matrix-org/mjolnir/blob/main/README.md) to learn what it does and why it might be useful to you.
 
-## Register the bot account
+## Prerequisites
 
-The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
+### Register the bot account
 
-You **need to register the bot user manually** before setting up the bot.
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
+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):
 
@@ -20,53 +31,100 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir
 
 If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
 
-## Get an access token
+### Obtain an access token
 
-Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+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).
 
-## Make sure the account is free from rate limiting
+> [!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.
 
-You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
+### Make sure the account is free from rate limiting
 
-If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](configuring-playbook-synapse-admin.md) or running `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
+If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a required step. If you do not configure it, Mjolnir will crash.**
 
-The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit` Replace `@bot.mjolnir:example.com` with the MXID of your Mjolnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Mjolnir itself. If you made Mjolnir Admin you can just use the Mjolnir token.
+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.
 
-## Create a management room
+**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).
 
-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.
+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).
 
-If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
+#### Add the configuration
 
-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`.
+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
+```
+
+#### Obtain an access token for admin account
+
+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.
+
+> [!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 ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit
+```
+
+**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.
+
+> [!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 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
 
-Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+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.
 
-### a. Configuration with E2EE support
+```yaml
+# Enable Mjolnir
+matrix_bot_mjolnir_enabled: true
+
+matrix_bot_mjolnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
+```
+
+### End-to-End Encryption support
+
+Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms.
+
+To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+
+#### Configuration with E2EE support
 
 When using Pantalaimon, Mjolnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+Add the following configuration to your `vars.yml` file (adapt to your needs):
 
 ```yaml
 # Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
 matrix_pantalaimon_enabled: true
 
-# Enable Mjolnir
-matrix_bot_mjolnir_enabled: true
-
 # Tell Mjolnir to use Pantalaimon
 matrix_bot_mjolnir_pantalaimon_use: true
 
-# User name and password for the bot. Required when using Pantalaimon.
+# User name and password for the bot you have created above. Required when using Pantalaimon.
-matrix_bot_mjolnir_pantalaimon_username: "MJOLNIR_USERNAME_FROM_STEP_1"
+matrix_bot_mjolnir_pantalaimon_username: "bot.mjolnir"
-matrix_bot_mjolnir_pantalaimon_password: ### you should create a secure password for the bot account
+matrix_bot_mjolnir_pantalaimon_password: "PASSWORD_FOR_THE_BOT"
-
-matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
 ```
 
 The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Mjolnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
@@ -81,25 +139,19 @@ matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matri
 matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
 ```
 
-### b. Configuration without E2EE support
+#### Configuration without E2EE support
 
 When NOT using Pantalaimon, Mjolnir does not log in by itself and you must give it an access token for its bot account.
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+Add the following configuration to your `vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
-
-You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with your own values.
 
 ```yaml
-matrix_bot_mjolnir_enabled: true
+matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_HERE"
-
-matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
-
-matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
 ```
 
-## Adding Mjolnir synapse antispam module (optional)
+### Adding Mjolnir synapse antispam module (optional)
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+To enable Mjolnir synapse antispam module, add the following configuration to your `vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
@@ -109,32 +161,15 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
 ```
 
-## Installing
+### Extending the configuration
 
-After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+There are some additional things you may wish to configure about the bot.
 
-<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+Take a look at:
-```sh
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
-```
 
-**Notes**:
+- `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
 
-- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+For example, to change Mjolnir's `recordIgnoredInvites` option to `true`, add the following configuration to your `vars.yml` file:
-
-- 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.
-
-## 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.
-
-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.
-
-For example to change Mjolnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
 
 ```yaml
 matrix_bot_mjolnir_configuration_extension_yaml: |
@@ -147,3 +182,38 @@ matrix_bot_mjolnir_configuration_extension_yaml: |
   # completely redefining `matrix_bot_mjolnir_configuration_yaml`.
   recordIgnoredInvites: 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
+```
+
+**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.
+
+- 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.
+
+## 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,3 +1,12 @@
+<!--
+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.
@@ -28,26 +37,32 @@ 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_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+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
@@ -63,7 +78,7 @@ Then, follow the instructions in the help output message.
 
 If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
 
-On the Discord side, you can say `!matrix help` to get a list of available commands to manage the bridge and Matrix users.
+On the Discord side, send `!matrix help` to the bot to see the available commands for managing the bridge and Matrix users.
 
 **Note**: Encrypted Matrix rooms are not supported as of writing.
 
@@ -73,7 +88,7 @@ Through portal bridging, Matrix rooms will automatically be created by the bot a
 
 All Matrix rooms created this way are **listed publicly** by default, and you will not have admin permissions to change this. To get more control, [make yourself a room Administrator](#getting-administrator-access-in-a-portal-bridged-room). You can then unlist the room from the directory and change the join rules.
 
-To disable portal bridging, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To disable portal bridging, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_appservice_discord_bridge_disablePortalBridging: true
@@ -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_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.
@@ -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_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_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,16 +1,30 @@
+<!--
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 MDAD project contributors
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Appservice Kakaotalk bridging (optional)
 
-The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you. `matrix-appservice-kakaotalk` is a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
+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.
-
-⚠️ **Warning**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
 
 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.
 
+> [!WARNING]
+> There have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
+
 ## Prerequisite (optional)
 
+### Enable Shared Secret Auth
+
 If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -20,9 +34,7 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_appservice_kakaotalk_enabled: true
 ```
 
-You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
+### Extending the configuration
-
-### Additional configuration
 
 There are some additional things you may wish to configure about the bridge.
 
@@ -37,41 +49,27 @@ 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 `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-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.
+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.
 
-### 💡 Set up Double Puppeting
+## Troubleshooting
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-appservice-kakaotalk`.
 
-To set it up, you have 2 ways of going about it.
+### Increase logging verbosity
 
-#### Method 1: automatically, by enabling Shared Secret Auth
+The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
-The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+```yaml
-
+matrix_appservice_kakaotalk_logging_level: DEBUG
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+```
-
-#### Method 2: manually, by asking each user to provide a working access token
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,3 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2019 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2020 Udo Rader
+SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Joel Bennett
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+SPDX-FileCopyrightText: 2024 Fabio Bonelli
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Appservice Slack bridging (optional)
 
 **Notes**:
@@ -61,7 +72,21 @@ matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
 # matrix_appservice_slack_team_sync_enabled: true
 ```
 
-Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
+### 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-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bridge-appservice-slack/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_slack_configuration_extension_yaml` variable
+
+For example, to change the bot's username from `slackbot`, add the following configuration to your `vars.yml` file. Replace `examplebot` with your own.
+
+```yaml
+matrix_appservice_slack_configuration_extension_yaml: |
+  bot_username: "examplebot"
+```
 
 ## Installing
 
@@ -69,16 +94,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
 
@@ -86,7 +107,7 @@ To use the bridge, you need to send `/invite @slackbot:example.com` to invite th
 
 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`.
+- 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:
@@ -121,7 +142,7 @@ Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave
 
 ## Troubleshooting
 
-As always, check the logs: `journalctl -fu matrix-appservice-slack`
+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-slack`.
 
 ### Linking: "Room is now pending-name"
 
@@ -129,8 +150,8 @@ This typically means that you haven't used the correct Slack channel ID. Unlink
 
 ### Messages work from Matrix to Slack, but not the other way around
 
-Check you logs, if they say something like
+Check the logs, and if you find the message like below, unlink your room, reinvite the bot and re-link it again.
 
 `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.
+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,6 +1,17 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2023 MDAD project contributors
+SPDX-FileCopyrightText: 2020 Björn Marten
+SPDX-FileCopyrightText: 2020 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 iLyas Bakouch
+SPDX-FileCopyrightText: 2022 Kim Brose
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Appservice Webhooks bridging (optional, deprecated)
 
-**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.
+**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.
 
 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.
 
@@ -14,9 +25,6 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 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.
 #
@@ -24,22 +32,27 @@ matrix_appservice_webhooks_api_secret: '<your_secret>'
 #   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-webhooks/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bridge-appservice-webhooks/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_webhooks_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
 
@@ -48,7 +61,7 @@ To use the bridge, you need to invite the bridge bot user to your room in either
 - 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 in order to receive a private message including the webhook link:
+You then need to send a message to the bridge bot to receive a private message including the webhook link:
 
 ```
 !webhook
@@ -85,3 +98,16 @@ If you're using the [Dimension integration manager](configuring-playbook-dimensi
 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.
+
+## 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-webhooks`.
+
+### 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: info, verbose
+matrix_appservice_webhooks_log_level: 'verbose'
+```

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

@@ -1,9 +1,29 @@
+<!--
+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 other mautrix bridges
+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.
 
 See the project's [documentation](https://github.com/beeper/linkedin/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+## Prerequisite
+
+### Enable Appservice Double Puppet or Shared Secret Auth (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.
+
+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:
@@ -12,25 +32,13 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_beeper_linkedin_enabled: true
 ```
 
-There are some additional things you may wish to configure about the bridge before you continue.
+### Extending the configuration
 
-Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+There are some additional things you may wish to configure about the bridge.
 
-```yaml
+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.
-matrix_beeper_linkedin_bridge_encryption_allow: true
-matrix_beeper_linkedin_bridge_encryption_default: true
-```
 
-If you would like to be able to administrate the bridge from your account it can be configured like this:
+**Note**: when following the guide to configure the bridge, make sure to replace `_mautrix_SERVICENAME_` in the variable names with `_beeper_linkedin_`.
-
-```yaml
-matrix_beeper_linkedin_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@alice:{{ matrix_domain }}': admin
-```
-
-You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
 
 ## Installing
 
@@ -38,37 +46,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 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.
-
-## Set up Double Puppeting by enabling Appservice Double Puppet or Shared Secret Auth
-
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
-
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
 
 ## Usage
 
 To use the bridge, you need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
+You then need to send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
-
-If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
-
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting-by-enabling-appservice-double-puppet-or-shared-secret-auth), if you haven't already done so.
 
 ## 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_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,36 +1,68 @@
+<!--
+SPDX-FileCopyrightText: 2022 Vladimir Panteleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Go Skype Bridge bridging (optional)
 
-The playbook can install and configure [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.
+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.
 
 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.
 
+## Prerequisite (optional)
+
+### Enable Shared Secret Auth
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
+
 ## Adjusting the playbook configuration
 
-To enable the [Skype](https://www.skype.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+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
+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 `Skype bridge bot` with the handle `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+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).
 
-Send `help` to the bot to see the commands available.
+## 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-go-skype-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
+matrix_go_skype_bridge_log_level: 'info'
+```

docs/configuring-playbook-bridge-heisenbridge.md

@@ -1,12 +1,26 @@
+<!--
+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).
 
-## Configuration
+## Adjusting DNS records (optional)
+
+By default, this playbook installs Heisenbridge on the `matrix.` subdomain, at the `/heisenbridge` path (https://matrix.example.com/heisenbridge). It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
+
+If you wish to adjust it, see the section [below](#adjusting-the-heisenbridge-url-optional) for details about DNS configuration.
+
+## Adjusting the playbook configuration
 
 To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
@@ -21,17 +35,11 @@ matrix_heisenbridge_owner: "@alice:{{ matrix_domain }}"
 # matrix_heisenbridge_identd_enabled: true
 ```
 
-For a more complete list of variables that you could override, see the [`defaults/main.yml` file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml) of the Heisenbridge Ansible role.
+### Adjusting the Heisenbridge URL (optional)
-
-### Adjusting the Heisenbridge URL
-
-By default, this playbook installs Heisenbridge on the `matrix.` subdomain, at the `/heisenbridge` path (https://matrix.example.com/heisenbridge). It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)).
-
-This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
 
 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.
 
-Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Change the default hostname and path prefix
@@ -39,13 +47,17 @@ matrix_heisenbridge_hostname: heisenbridge.example.com
 matrix_heisenbridge_path_prefix: /
 ```
 
-## Adjusting DNS records
+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`.
 
-If you've changed the default hostname, **you may need to adjust your DNS** records to point the Heisenbridge domain to the Matrix server.
+When setting, replace `example.com` with your own.
 
-See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+### Extending the configuration
 
-If you've decided to use the default hostname, you won't need to do any extra DNS 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
 
@@ -53,16 +65,12 @@ After configuring the playbook and potentially [adjusting your DNS records](#adj
 
 <!-- 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
 
@@ -73,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,32 +1,74 @@
+<!--
+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.
 
-Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from software project management services such as GitHub, GitLab, JIRA, and Figma, as well as generic webhooks.
+Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from software project management services such as GitHub, GitLab, Jira, and Figma, as well as generic webhooks.
 
 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.
 
-## Setup Instructions
+## Prerequisites
 
-Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
+### Download GitHub app private key (optional)
 
-1. Enable the bridge by adding `matrix_hookshot_enabled: true` to your `vars.yml` file
+If you're setting up the GitHub bridge, you need to create your GitHub app, and generate a private key file of it.
-2. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
-3. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
-4. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-aux-role) explained below.
-5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
 
-Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
+You need to download the private key file, if you will install the file manually or with the `aux` role. For details, see [the section below](#manage-github-private-key-with-aux-role).
 
-Finally, run the playbook (see [installing](installing.md)).
+## Adjusting the playbook configuration
 
-### End-to-bridge encryption
+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).
 
-You can enable [encryption](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) for Hookshot by adding `matrix_hookshot_encryption_enabled: true` to your configuration (`vars.yml`) and [executing the playbook](installing.md) again.
+```yaml
+matrix_hookshot_enabled: true
 
-Should the crypto store be corrupted, you can reset it by executing this Ansible playbook with the tag `reset-hookshot-encryption` added, for example `ansible-playbook -i inventory/hosts setup.yml --tags=reset-hookshot-encryption`.
+# 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
+
+# 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"
+```
+
+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.
+
+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).
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-hookshot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bridge-hookshot/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables
+
+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.
+
+## 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-service hookshot` or `just setup-all`
+
+`just install-service hookshot` is useful for maintaining your setup quickly 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 `just setup-all` runs the `ensure-matrix-users-created` tag too.
 
 ## Usage
 
@@ -34,11 +76,19 @@ To use the bridge, you need to create a room and invite the Hookshot bot (`@hook
 
 Make sure the bot is able to send state events (usually the Moderator power level in clients).
 
-Send a `!hookshot help` message to see a list of help commands.
+Send `!hookshot help` to the bot to see the available commands.
 
 Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) for more details about using the bridge's various features.
 
-**Important**: Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](#urls-for-bridges-setup) below.
+💡 **Note**: the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation. See [URLs for bridges setup](#urls-for-bridges-setup) below.
+
+### Reset crypto store
+
+Should the crypto store be corrupted, you can reset it by executing this Ansible playbook with the tag `reset-hookshot-encryption` added:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=reset-hookshot-encryption
+```
 
 ## More setup documentation
 
@@ -46,59 +96,90 @@ Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot
 
 Unless indicated otherwise, the following endpoints are reachable on your `matrix.` subdomain (if the feature is enabled).
 
-| listener | default path | variable | used as |
+| Listener | Default path | Variable | Used as |
 |---|---|---|---|
 | - | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
 | generic | `/hookshot/webhooks/webhook` | `matrix_hookshot_generic_endpoint` | Generic webhooks |
 | github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
-| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | JIRA OAuth |
+| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | Jira OAuth |
 | figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
-| provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
 | appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
 | 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_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_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.
 
 ### 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_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.
 - 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 additional configuration:
+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:
 
 ```yaml
 aux_file_definitions:
   - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_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
-
-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`.
-
-### 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 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:
-
-- either enabling metrics exposure for Hookshot via `matrix_hookshot_metrics_proxying_enabled: true`
-- 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.
-
 ### Collision with matrix-appservice-webhooks
 
 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_'`).
+
+### Enable metrics
+
+The playbook can enable and configure the metrics of the service for you.
+
+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 enable the metrics, add the following configuration to your `vars.yml` file:
+
+```yaml
+# Expose metrics (locally, on the container network).
+matrix_hookshot_metrics_enabled: true
+```
+
+**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.example.com/metrics/hookshot` by adding the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_hookshot_metrics_proxying_enabled: true
+```
+
+By default metrics are exposed publicly **without** password-protection. To password-protect the metrics with dedicated credentials, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
+matrix_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
+```
+
+To `matrix_hookshot_container_labels_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
+
+**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_hookshot_logging_level: debug
+```

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

@@ -1,10 +1,20 @@
+<!--
+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.
 
 See the project's [documentation](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-**The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.**
+## Prerequisite
+
+The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.
 
 ## Adjusting the playbook configuration
 
@@ -28,26 +38,33 @@ matrix_sms_bridge_provider_android_password: supeSecretPassword
 # (optional) if your android-sms-gateway-server uses a self signed vertificate, the bridge needs a "truststore". This can be the certificate itself.
 matrix_sms_bridge_provider_android_truststore_local_path: android-sms-gateway-server.p12
 matrix_sms_bridge_provider_android_truststore_password: 123
-
 ```
 
+### 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_sms_bridge_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_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_mautrix_bluesky_logging_level: 'debug'
+```

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

@@ -0,0 +1,218 @@
+<!--
+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.
+
+The author of the bridges maintains [the official docs](https://docs.mau.fi/bridges/index.html), whose source code is available at [mautrix/docs](https://github.com/mautrix/docs) repository on GitHub. You may as well to refer it while configuring them.
+
+You can see each bridge's features on the `ROADMAP.md` file in its corresponding mautrix repository.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Replace SERVICENAME with one of: twitter, discord, signal, googlechat, etc.
+matrix_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).
+
+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.
+
+### Configure bridge permissions (optional)
+
+By default any user on your homeserver will be able to use the mautrix bridges. To limit who can use them you would need to configure their permissions settings.
+
+Different levels of permission can be granted to users. For example, to **configure a user as an administrator for all bridges**, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_admin: "@alice:{{ matrix_domain }}"
+```
+
+If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
+
+**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: |
+  bridge:
+    permissions:
+      '@alice:{{ matrix_domain }}': admin
+```
+
+This will add the admin permission to the specific user, while keeping the default permissions.
+
+You could also redefine the default permissions settings completely, rather than adding extra permissions. You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` to find information on the permission settings and other options you would like to configure.
+
+### Enable encryption (optional)
+
+[Encryption (End-to-Bridge Encryption, E2BE) support](https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html) is off by default. If you would like to enable encryption, add the following configuration to your `vars.yml` file:
+
+**for all bridges with encryption support**:
+
+```yaml
+matrix_bridges_encryption_enabled: true
+matrix_bridges_encryption_default: true
+```
+
+**Alternatively**, for a specific bridge:
+
+```yaml
+matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
+matrix_mautrix_SERVICENAME_bridge_encryption_default: true
+```
+
+### Enable relay mode (optional)
+
+[Relay mode](https://docs.mau.fi/bridges/general/relay-mode.html) is off by default. Check [the table on the official documentation](https://docs.mau.fi/bridges/general/relay-mode.html#support-table) for bridges which support relay mode.
+
+If you would like to enable it, add the following configuration to your `vars.yml` file:
+
+**for all bridges with relay mode support**:
+
+```yaml
+matrix_bridges_relay_enabled: true
+```
+
+**Alternatively**, for a specific bridge:
+
+```yaml
+matrix_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:
+
+```yaml
+matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
+  bridge:
+    relay:
+      enabled: true
+    permissions:
+      '@alice:{{ matrix_domain }}': admin
+    encryption:
+      allow: true
+      default: true
+```
+
+If you want to activate the relaybot in a room, send `!prefix set-relay` in the rooms where you want to use the bot (replace `!prefix` with the appropriate command prefix for the bridge, like `!signal` or `!wa`). To deactivate, send `!prefix unset-relay`.
+
+Use `!prefix set-pl 100` to be able for the bot to modify room settings and invite others.
+
+#### Allow anyone on the homeserver to become a relay user (optional)
+
+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
+```
+
+### Set the bot's username (optional)
+
+To set the bot's username, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
+```
+
+### Configure the logging level (optional)
+
+To specify the logging level, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_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.
+
+### Extending the configuration
+
+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
+
+## 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, you need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+For details about the next steps, refer to each bridge's individual documentation page.
+
+Send `help` to the bot to see the available commands.
+
+If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
+
+### Set up Double Puppeting (optional)
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet (recommended)
+
+To set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html), you could enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
+
+To enable the Appservice Double Puppet service, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_appservice_double_puppet_enabled: true
+```
+
+When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+**Notes**:
+
+- 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.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
+
+## Troubleshooting
+
+For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
+
+If the bridge's bot doesn't accept the invite to a chat, refer [the official troubleshooting page](https://docs.mau.fi/bridges/general/troubleshooting.html) as well.
+
+If you found bugs in mautrix bridges, they should be reported to the upstream project, in the corresponding mautrix repository, not to us.

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

@@ -1,5 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 Hugues Morisset
+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 - 2025 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.
 - 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.
@@ -18,7 +32,9 @@ If this is a dealbreaker for you, consider using one of the other Discord bridge
 
 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.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -28,16 +44,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_discord_enabled: true
 ```
 
-You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
+### Extending the configuration
-
-### Additional configuration
 
 There are some additional things you may wish to configure about the bridge.
 
-Take a look at:
+<!-- 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.
-- `roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-mautrix-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_mautrix_discord_configuration_extension_yaml` variable
 
 ## Installing
 
@@ -45,64 +57,38 @@ 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
 
-### Logging in
+To use the bridge, you need to start a chat with `@discordbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-#### Method 1: Login using QR code (recommended)
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/discord/authentication.html).
 
-For using this bridge, you would need to authenticate by **scanning a QR code** with the Discord app on your phone.
+After logging in, the bridge will create portal rooms for some recent direct messages.
 
-You can delete the Discord app after the authentication process.
+### Bridge guilds
 
-#### Method 2: Login using Discord token (not recommended)
+If you'd like to bridge guilds, send `guilds status` to see the list of guilds, then send `guilds bridge GUILD_ID_HERE` for each guild that you'd like bridged. Make sure to replace `GUILD_ID_HERE` with the guild's ID.
 
-To acquire the token, open Discord in a private browser window. Then open the developer settings (keyboard shortcut might be "ctrl+shift+i" or by pressing "F12"). Navigate to the "Network" tab then reload the page. In the URL filter or search bar type "/api" and find the response with the file name of "library". Under the request headers you should find a variable called "Authorization", this is the token to your Discord account. After copying the token, you can close the browser window.
+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.
 
-### Bridging
+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.
 
-1. Start a chat with `@discordbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+## Troubleshooting
-2. If you would like to login to Discord using a token, send `login-token` command, otherwise, send `login-qr` command.
-3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
-4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as …"
-5. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to
-6. Some Direct Messages from Discord should start syncing automatically
-7. If you'd like to bridge guilds:
-    - send `guilds status` to see the list of guilds
-    - for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire`
-8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function.
 
-### 💡 Set up Double Puppeting
+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`.
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+### Increase logging verbosity
 
-To set it up, you have 2 ways of going about it.
+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:
 
-#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+```yaml
-
+# Valid values: fatal, error, warn, info, debug, trace
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+matrix_mautrix_discord_logging_level: 'debug'
-
+```
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
-#### Method 2: manually, by asking each user to provide a working access token
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,16 +1,34 @@
+<!--
+SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 Hugues Morisset
+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: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Facebook bridging (optional, deprecated)
 
-**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.
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
+**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.
 
 The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you.
 
-See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.
+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.
 
 ## Prerequisite (optional)
 
+### Enable Shared Secret Auth
+
 If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -20,40 +38,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_facebook_enabled: true
 ```
 
-There are some additional things you may wish to configure about the bridge before you continue.
+### Extending the configuration
 
-Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+There are some additional things you may wish to configure about the bridge.
 
-```yaml
+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.
-matrix_mautrix_facebook_configuration_extension_yaml: |
-  bridge:
-    encryption:
-      allow: true
-      default: true
-```
-
-If you would like to be able to administrate the bridge from your account it can be configured like this:
-
-```yaml
-matrix_mautrix_facebook_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@alice:{{ matrix_domain }}': admin
-```
-
-Using both would look like
-
-```yaml
-matrix_mautrix_facebook_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@alice:{{ matrix_domain }}': admin
-    encryption:
-      allow: true
-      default: true
-```
-
-You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure.
 
 ## Installing
 
@@ -61,49 +50,33 @@ 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 `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html).
+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.
 
-### 💡 Set up Double Puppeting
-
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
-
-To set it up, you have 2 ways of going about it.
-
-#### Method 1: automatically, by enabling Shared Secret Auth
-
-The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
-
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-#### Method 2: manually, by asking each user to provide a working access token
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature
-
 ## 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-facebook`.
+
+### 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_mautrix_facebook_logging_level: DEBUG
+```
+
 ### 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.

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

@@ -1,14 +1,26 @@
+<!--
+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>
+
 The playbook can install and configure [mautrix-gmessages](https://github.com/mautrix/gmessages) for you, for bridging to [Google Messages](https://messages.google.com/).
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/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.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -18,45 +30,43 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_gmessages_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,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 `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-### 💡 Set up Double Puppeting
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/gmessages/authentication.html).
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+After logging in, the bridge will create portal rooms for recent chats.
 
-To set it up, you have 2 ways of going about it.
+## Troubleshooting
 
-#### Method 1: automatically, by enabling Appservice Double Puppet
+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`.
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+### Increase logging verbosity
 
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+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:
 
-#### Method 2: manually, by asking each user to provide a working access token
+```yaml
-
+# Valid values: fatal, error, warn, info, debug, trace
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+matrix_mautrix_gmessages_logging_level: 'debug'
-
+```
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-gmessages` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,14 +1,29 @@
+<!--
+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>
+
 The playbook can install and configure [mautrix-googlechat](https://github.com/mautrix/googlechat) for you.
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/googlechat/index.html) to learn what it does and why it might be useful to you.
 
 ## Prerequisite (optional)
 
+### Enable Appservice Double Puppet or Shared Secret Auth
+
 If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -18,55 +33,42 @@ To enable the [Google Chat](https://chat.google.com/) bridge, add the following
 matrix_mautrix_googlechat_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,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 `googlechat bridge bot` with handle `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-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.
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
 
-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.
+After logging in, the bridge will create portal rooms for recent chats. Portal rooms for other chats will be created as you receive messages.
 
-Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages.
+## Troubleshooting
 
-You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
+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`.
 
-### 💡 Set up Double Puppeting
+### Increase logging verbosity
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+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:
 
-To set it up, you have 2 ways of going about it.
+```yaml
-
+matrix_mautrix_googlechat_logging_level: DEBUG
-#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+```
-
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
-
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
-#### Method 2: manually, by asking each user to provide a working access token
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,72 +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
 
-💡 **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.
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 
-The playbook can install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts) for you.
+# Setting up Mautrix Hangouts bridging (optional, removed)
 
-See the project's [documentation](https://docs.mau.fi/bridges/python/hangouts/index.html) to learn what it does and why it might be useful to 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.
 
-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.
+## Uninstalling the bridge manually
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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:
 
-## 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
-```
-
-## 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 '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 `Hangouts bridge bot` with handle `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-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.
-
-You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/hangouts/authentication.html).
-
-### 💡 Set up Double Puppeting
-
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
-
-To set it up, you have 2 ways of going about it.
-
-#### Method 1: automatically, by enabling Shared Secret Auth
-
-The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
-
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-#### Method 2: manually, by asking each user to provide a working access token
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,10 +1,21 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2021 Marcus Proest
+SPDX-FileCopyrightText: 2022 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Mautrix Instagram bridging (optional, deprecated)
 
-**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.
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
+**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.
 
 The playbook can install and configure [mautrix-instagram](https://github.com/mautrix/instagram) for you.
 
-See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/index.html) to learn what it does and why it might be useful to you.
+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.
 
 ## Adjusting the playbook configuration
 
@@ -14,33 +25,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_instagram_enabled: true
 ```
 
-There are some additional things you may wish to configure about the bridge before you continue.
+### Extending the configuration
 
-Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+There are some additional things you may wish to configure about the bridge.
 
-```yaml
+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.
-matrix_mautrix_instagram_configuration_extension_yaml: |
-  bridge:
-    encryption:
-      allow: true
-      default: true
-```
-
-If you would like to be able to administrate the bridge from your account it can be configured like this:
-
-```yaml
-# The easy way. The specified Matrix user ID will be made an admin of all bridges
-matrix_admin: "@alice:{{ matrix_domain }}"
-
-# OR:
-# The more verbose way. Applies to this bridge only. You may define multiple Matrix users as admins.
-matrix_mautrix_instagram_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@alice:{{ matrix_domain }}': admin
-```
-
-You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
 
 ## Installing
 
@@ -48,21 +37,27 @@ 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 `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account.
+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.
 
-You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/instagram/authentication.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-instagram`.
+
+### 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_mautrix_instagram_logging_level: DEBUG
+```

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

@@ -1,7 +1,18 @@
+<!--
+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>
+
 The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
 
+See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you.
+
 Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
 
 This documentation page only deals with the bridge's ability to bridge to Instagram. For bridging to Facebook/Messenger, see [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md).
@@ -23,7 +34,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre
 
 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.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -35,37 +46,11 @@ matrix_mautrix_meta_instagram_enabled: true
 
 Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
 
-### Bridge permissions
+### Extending the configuration
 
-By default, any user on your homeserver will be able to use the bridge.
+There are some additional things you may wish to configure about the bridge.
 
-Different levels of permission can be granted to users:
+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.
-
-- `relay` - Allowed to be relayed through the bridge, no access to commands
-- `user` - Use the bridge with puppeting
-- `admin` - Use and administer the bridge
-
-The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
-
-The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this:
-
-```yaml
-matrix_mautrix_meta_instagram_bridge_permissions_default:
-  '*': relay
-  example.com: user
-  '{{ matrix_admin }}': admin
-```
-
-If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
-
-You may redefine `matrix_mautrix_meta_instagram_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_instagram_bridge_permissions_custom` like this:
-
-```yaml
-matrix_mautrix_meta_instagram_bridge_permissions_custom:
-  '@alice:{{ matrix_domain }}': admin
-```
-
-You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
 
 ## Installing
 
@@ -73,39 +58,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 `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-### 💡 Set up Double Puppeting
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+After logging in, the bridge will sync recent chats.
 
-To set it up, you have 2 ways of going about it.
+## Troubleshooting
 
-#### Method 1: automatically, by enabling Appservice Double Puppet
+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`.
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+### Increase logging verbosity
 
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+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:
 
-#### Method 2: manually, by asking each user to provide a working access token
+```yaml
-
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+matrix_mautrix_meta_instagram_logging_min_level: debug
-
+```
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature

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

@@ -1,7 +1,19 @@
+<!--
+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>
+
 The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
 
+See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you.
+
 Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
 
 This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md).
@@ -22,7 +34,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre
 
 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.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -41,44 +53,18 @@ 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).
 
 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.).
 
-### Bridge permissions
+### Extending the configuration
 
-By default, any user on your homeserver will be able to use the bridge.
+There are some additional things you may wish to configure about the bridge.
 
-Different levels of permission can be granted to users:
+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.
-
-- `relay` - Allowed to be relayed through the bridge, no access to commands
-- `user` - Use the bridge with puppeting
-- `admin` - Use and administer the bridge
-
-The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
-
-The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this:
-
-```yaml
-matrix_mautrix_meta_messenger_bridge_permissions_default:
-  '*': relay
-  example.com: user
-  '{{ matrix_admin }}': admin
-```
-
-If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
-
-You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this:
-
-```yaml
-matrix_mautrix_meta_messenger_bridge_permissions_custom:
-  '@alice:{{ matrix_domain }}': admin
-```
-
-You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
 
 ## Installing
 
@@ -86,43 +72,32 @@ 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 `@messengerbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Note that the user ID of the bridge's bot is not `@facebookbot:example.com`.
 
-You then need to send a `login` command and follow the bridge bot's instructions.
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
 
-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 as per [the bridge's authentication instructions](https://docs.mau.fi/bridges/go/meta/authentication.html).
+After logging in, the bridge will sync recent chats.
 
-### 💡 Set up Double Puppeting
+**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.
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+## Troubleshooting
 
-To set it up, you have 2 ways of going about it.
+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`.
 
-#### Method 1: automatically, by enabling Appservice Double Puppet
+### Increase logging verbosity
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+```yaml
-
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
-#### Method 2: manually, by asking each user to provide a working access token
+matrix_mautrix_meta_messenger_logging_min_level: debug
-
+```
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature

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

@@ -1,10 +1,26 @@
+<!--
+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>
+
 The playbook can install and configure [mautrix-signal](https://github.com/mautrix/signal) for you.
 
-See the project's [documentation](https://docs.mau.fi/bridges/python/signal/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/signal/index.html) to learn what it does and why it might be useful to you.
-
-**Note**: This revamped version of the [mautrix-signal (legacy)](configuring-playbook-bridge-mautrix-signal.md) may increase the CPU usage of your homeserver.
 
 ## Prerequisites (optional)
 
@@ -18,7 +34,7 @@ However, if you're [using an external Postgres server](configuring-playbook-exte
 
 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.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -28,46 +44,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_signal_enabled: true
 ```
 
-There are some additional things you may wish to configure about the bridge before you continue.
+### Extending the configuration
 
-By default, any user on your homeserver will be able to use the bridge.
+There are some additional things you may wish to configure about the bridge.
 
-Different levels of permission can be granted to users:
+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.
-
-* relay - Allowed to be relayed through the bridge, no access to commands;
-* user - Use the bridge with puppeting;
-* admin - Use and administer the bridge.
-
-The permissions are following the sequence: nothing < relay < user < admin.
-
-The default permissions are set as follows:
-
-```yaml
-permissions:
-  '*': relay
-  example.com: user
-```
-
-If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file:
-
-```yaml
-matrix_mautrix_signal_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@alice:{{ matrix_domain }}': admin
-```
-
-This will add the admin permission to the specific user, while keeping the default permissions.
-
-In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
-
-```yaml
-matrix_mautrix_signal_bridge_permissions:
-  '@alice:{{ matrix_domain }}': admin
-  '@bob:{{ matrix_domain }}' : user
-```
-
-You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
 
 ## Installing
 
@@ -75,39 +56,32 @@ 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 `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-### 💡 Set up Double Puppeting
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/signal/authentication.html).
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+After logging in, the bridge will bridge chats as you receive messages.
 
-To set it up, you have 2 ways of going about it.
+**Note**: Signal does not support any kind of message history (even on official apps), so the bridge won't backfill any messages.
 
-#### Method 1: automatically, by enabling Appservice Double Puppet
+## Troubleshooting
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+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`.
 
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+### Increase logging verbosity
 
-#### Method 2: manually, by asking each user to provide a working access token
+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:
 
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+```yaml
-
+# Valid values: fatal, error, warn, info, debug, trace
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+matrix_mautrix_signal_logging_level: 'debug'
-
+```
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,5 +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.
@@ -20,7 +31,7 @@ Note that neither of these methods are officially supported by Slack. [matrix-ap
 
 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.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -30,16 +41,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_slack_enabled: true
 ```
 
-You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
+### Extending the configuration
 
-### Additional configuration
+There are some additional things you may wish to configure about the bridge.
 
-There are some additional options you may wish to configure with 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.
-Take a look at:
-
-- `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-mautrix-slack/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_slack_configuration_extension_yaml` variable
 
 ## Installing
 
@@ -47,43 +54,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
 
-1. Start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-2. If you would like to login to Slack using a token, send the `login-token` command, otherwise, send the `login-password` command. Read [here](https://docs.mau.fi/bridges/go/slack/authentication.html) on how to retrieve your token and cookie token.
-3. The bot should respond with "Successfully logged into <email> for team <workspace>"
-4. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to.
-5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication.
 
-### 💡 Set up Double Puppeting
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/slack/authentication.html).
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+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.
 
-To set it up, you have 2 ways of going about it.
+## Troubleshooting
 
-#### Method 1: automatically, by enabling Appservice Double Puppet
+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`.
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+### Increase logging verbosity
 
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+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:
 
-#### Method 2: manually, by asking each user to provide a working access token
+```yaml
-
+# Valid values: fatal, error, warn, info, debug, trace
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+matrix_mautrix_slack_logging_level: 'debug'
-
+```
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,18 +1,45 @@
+<!--
+SPDX-FileCopyrightText: 2018 - 2024 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.
 
-## Prerequisite (optional)
+## Prerequisites
+
+### Obtain a Telegram API key
+
+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)
 
 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.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
-You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+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
@@ -20,28 +47,11 @@ matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
 matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
 ```
 
-## Installing
+### Relaying
 
-After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+### Enable relay-bot (optional)
 
-<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+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:
-```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 `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-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 `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
@@ -51,45 +61,56 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
       '*': relaybot
 ```
 
-You might also want to give permissions to administrate the bot:
+### Configure a user as an administrator of the bridge (optional)
 
-```yaml
+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.
-matrix_mautrix_telegram_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@alice:{{ matrix_domain }}': admin
-```
 
 More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
 
-If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration:
+### 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
 ```
 
-### 💡 Set up Double Puppeting
+### Extending the configuration
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+There are some additional things you may wish to configure about the bridge.
 
-To set it up, you have 2 ways of going about it.
+<!-- 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.
 
-#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+## Installing
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+<!-- 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
+```
 
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-#### Method 2: manually, by asking each user to provide a working access token
+`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.
 
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging.
+## Usage
 
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+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).
 
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/telegram/authentication.html).
 
-- send `login-matrix` to the bot and follow instructions about how to send the access token to it
+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.
 
-- make sure you don't log out the `Mautrix-Telegram` device some time in the future, as that would break the Double Puppeting feature
+## 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 `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_mautrix_telegram_logging_level: DEBUG
+```

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

@@ -1,5 +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.
@@ -8,9 +19,11 @@ See the project's [documentation](https://github.com/mautrix/twitter/blob/master
 
 ## Prerequisite (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.
+### Enable Appservice Double Puppet
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -20,44 +33,43 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_twitter_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,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
 
-1. You then need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-2. Send login-cookie to start the login. The bot should respond with instructions on how to proceed.
 
-You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/twitter/authentication.html).
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/twitter/authentication.html).
 
-### 💡 Set up Double Puppeting
+After logging in, the bridge will create portal rooms for recent chats. Portal rooms for other chats will be created as you receive messages.
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+## Troubleshooting
 
-To set it up, you have 2 ways of going about it.
+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`.
 
-#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+### Increase logging verbosity
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+```yaml
-
+# Valid values: fatal, error, warn, info, debug, trace
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+matrix_mautrix_twitter_logging_level: 'debug'
-
+```
-#### Method 2: manually, by asking each user to provide a working access token
-
-This method is currently not available for the Mautrix-Twitter bridge, but is on the [roadmap](https://github.com/mautrix/twitter/blob/master/ROADMAP.md) under Misc/Manual login with `login-matrix`

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

@@ -1,14 +1,33 @@
+<!--
+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>
+
 The playbook can install and configure [mautrix-whatsapp](https://github.com/mautrix/whatsapp) for you.
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/whatsapp/index.html) to learn what it does and why it might be useful to you.
 
 ## Prerequisite (optional)
 
+### Enable Appservice Double Puppet or Shared Secret Auth
+
 If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+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
 
@@ -18,21 +37,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_whatsapp_enabled: true
 ```
 
-Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
+### Extending the configuration
 
-The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file:
+There are some additional things you may wish to configure about the bridge.
 
-```yaml
+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.
-matrix_mautrix_whatsapp_bridge_relay_enabled: true
-```
-
-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 this to your `vars.yml` file:
-
-```yaml
-matrix_mautrix_whatsapp_bridge_relay_admin_only: false
-```
-
-If you want to activate the relay bot in a room, send `!wa set-relay`. To deactivate, send `!wa unset-relay`.
 
 ## Installing
 
@@ -40,41 +49,32 @@ 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 `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-### 💡 Set up Double Puppeting
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/whatsapp/authentication.html).
 
-After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+Approximately in a minute after logging in, the bridge will create portal rooms for recent chats.
 
-To set it up, you have 2 ways of going about it.
+**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.
 
-#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+## Troubleshooting
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+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`.
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+### Increase logging verbosity
 
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+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:
 
-#### Method 2: manually, by asking each user to provide a working access token
+```yaml
-
+# Valid values: fatal, error, warn, info, debug, trace
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+matrix_mautrix_whatsapp_logging_level: 'debug'
-
+```
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Whatsapp` device some time in the future, as that would break the Double Puppeting feature

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

@@ -1,9 +1,25 @@
+<!--
+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>
+
 The playbook can install and configure [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for you.
 
 See the project's [documentation](https://github.com/mautrix/wsproxy/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+## Adjusting DNS records
+
+By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to create a CNAME record for `wsproxy`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -20,24 +36,24 @@ matrix_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
+### Adjusting the wsproxy URL (optional)
-
-By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
 
 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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Change the default hostname
 matrix_mautrix_wsproxy_hostname: ws.example.com
 ```
 
-## Adjusting DNS records
+After changing the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.
 
-Once you've decided on the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.
+### Extending the configuration
 
-By default, you will need to create a CNAME record for `wsproxy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+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
 
@@ -45,17 +61,17 @@ After configuring the playbook and potentially [adjusting your DNS records](#adj
 
 <!-- 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 [matrix-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-mx-puppet-discord.md

@@ -1,7 +1,16 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2022 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Hugues Morisset
+SPDX-FileCopyrightText: 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up MX Puppet Discord bridging (optional)
 
-**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.   
+**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.
-- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.  
+- 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.
@@ -22,16 +31,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
 
@@ -43,4 +48,4 @@ 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.
 
-Also send `help` to the bot to see the commands available.
+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.
@@ -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
 
@@ -45,4 +50,4 @@ Once logged in, send `listrooms` 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.
 
-Also send `help` to the bot to see the commands available.
+Send `help` to the bot to see the available commands.

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

@@ -1,3 +1,10 @@
+<!--
+SPDX-FileCopyrightText: 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up MX Puppet Instagram bridging (optional)
 
 The playbook can install and configure [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) for you.
@@ -18,16 +25,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
 
@@ -45,4 +48,4 @@ For double-puppeting, you probably want to issue these commands:
 
 If you are linking only one Instagram account, your `$puppetId` is probably 1, but use the `list` command find out.
 
-The `help` command shows which commands are available, though at the time of writing, not every command is fully implemented.
+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.

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

@@ -1,3 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2023 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Rodrigo Belem
+SPDX-FileCopyrightText: 2021 Marcel Ackermann
+SPDX-FileCopyrightText: 2022 Jim Myhrberg
+SPDX-FileCopyrightText: 2022 Nikita Chernyi
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up MX Puppet Slack bridging (optional)
 
 **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.
@@ -27,16 +38,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
 
@@ -48,4 +55,4 @@ 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.
 
-Also send `help` to the bot to see the commands available.
+Send `help` to the bot to see the available commands.

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

@@ -1,3 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2021 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Hugues Morisset
+SPDX-FileCopyrightText: 2020 Panagiotis Vasilopoulos
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up MX Puppet Steam bridging (optional)
 
 The playbook can install and configure [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) for you.
@@ -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
 
@@ -39,4 +44,4 @@ 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.
 
-Also send `help` to the bot to see the commands available.
+Send `help` to the bot to see the available commands.

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

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2020 Tulir Asokan
+SPDX-FileCopyrightText: 2021 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up MX Puppet Twitter bridging (optional)
 
 **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.
@@ -29,16 +37,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
 
@@ -50,4 +54,4 @@ 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.
 
-Also send `help` to the bot to see the commands available.
+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.
 
@@ -19,6 +26,19 @@ If you don't open these ports, you will still be able to send emails, but not re
 
 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.
 
+## Adjusting DNS records
+
+To make Postmoogle enable its email sending features, you need to configure MX and TXT (SPF, DMARC, and DKIM) records. See the table below for values which need to be specified.
+
+| Type | Host                           | Priority | Weight | Port | Target                             |
+|------|--------------------------------|----------|--------|------|------------------------------------|
+| MX   | `matrix`                       | 10       | 0      | -    | `matrix.example.com`               |
+| TXT  | `matrix`                       | -        | -      | -    | `v=spf1 ip4:matrix-server-IP -all` |
+| TXT  | `_dmarc.matrix`                | -        | -      | -    | `v=DMARC1; p=quarantine;`          |
+| TXT  | `postmoogle._domainkey.matrix` | -        | -      | -    | get it from `!pm dkim`             |
+
+**Note**: the DKIM record can be retrieved after configuring and installing the bridge's bot.
+
 ## Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -29,7 +49,7 @@ matrix_postmoogle_enabled: true
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_postmoogle_login: postmoogle
 
-# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
+# 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
 
 # Uncomment to add one or more admins to this bridge:
@@ -37,14 +57,18 @@ matrix_postmoogle_password: PASSWORD_FOR_THE_BOT
 # matrix_postmoogle_admins:
 #  - '@yourAdminAccount:{{ matrix_domain }}'
 #
-# .. unless you've made yourself an admin of all bots/bridges like this:
+# … unless you've made yourself an admin of all bots/bridges like this:
 #
 # matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
 ```
 
-## Adjusting DNS records
+### Extending the configuration
 
-You will also need to add several DNS records so that Postmoogle can send emails. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+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
 
@@ -71,15 +95,17 @@ To use the bridge, invite the `@postmoogle:example.com` bot user into a room you
 
 Then send `!pm mailbox NAME` to expose this Matrix room as an inbox with the email address `NAME@matrix.example.com`. Emails sent to that email address will be forwarded to the room.
 
-Send `!pm help` to the room to see the bridge's help menu for additional commands.
+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'

docs/configuring-playbook-bridge-wechat.md

@@ -1,9 +1,19 @@
+<!--
+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 the [matrix-wechat](https://github.com/duo/matrix-wechat) bridge for you (for bridging to the [WeChat](https://www.wechat.com/) network).
+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:
@@ -12,25 +22,45 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_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_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.
 
 ## Usage
 
-Once the bridge is installed, start a chat with `@wechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+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_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,43 +17,45 @@ 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).
 
-## Configuration
+## Adjusting DNS records (optional)
+
+By default, this playbook installs Cactus Comments' client on the `matrix.` subdomain, at the `/cactus-comments` path (https://matrix.example.com/cactus-comments). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
+
+If you wish to adjust it, see the section [below](#adjusting-the-cactus-comments-client-url-optional) for details about DNS configuration.
+
+## Adjusting the playbook configuration
 
 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
+### Adjusting the Cactus Comments' client URL (optional)
-
-By default, this playbook installs Cactus Comments' client on the `matrix.` subdomain, at the `/cactus-comments` path (https://matrix.example.com/cactus-comments). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
 
 By tweaking the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Change the default hostname and path prefix to host the client assets at a different location
@@ -53,13 +64,21 @@ matrix_cactus_comments_client_hostname: cactus.example.com
 matrix_cactus_comments_client_path_prefix: /
 ```
 
-## Adjusting DNS records
+If you've changed the default hostname, you may need to create a CNAME record for the Cactus Comments' client domain (`cactus.example.com`), which targets `matrix.example.com`.
 
-If you've changed the default hostname, **you may need to adjust your DNS** records to point the Cactus Comments' client domain to the Matrix server.
+When setting, replace `example.com` with your own.
 
-See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+### Extending the configuration
 
-If you've decided to use the default hostname, you won't need to do any extra DNS 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
 
@@ -67,24 +86,18 @@ After configuring the playbook and potentially [adjusting your DNS records](#adj
 
 <!-- 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 a `help` message 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,6 +1,14 @@
+<!--
+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)
 
-This playbook can install the [Cinny](https://github.com/ajbura/cinny) Matrix web client for you.
+The playbook can install and configure the [Cinny](https://github.com/ajbura/cinny) Matrix web client for you.
 
 Cinny is a web client focusing primarily on simple, elegant and secure interface. It can be installed alongside or instead of [Element Web](./configuring-playbook-client-element-web.md).
 
@@ -8,6 +16,12 @@ Cinny is a web client focusing primarily on simple, elegant and secure interface
 
 - [app.cinny.in](https://app.cinny.in), hosted by the [Cinny](https://cinny.in/) developers
 
+## Adjusting DNS records
+
+By default, this playbook installs Cinny on the `cinny.` subdomain (`cinny.example.com`) and requires you to create a CNAME record for `cinny`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
 ## Adjusting the playbook configuration
 
 To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -16,28 +30,32 @@ To enable Cinny, add the following configuration to your `inventory/host_vars/ma
 matrix_client_cinny_enabled: true
 ```
 
-### Adjusting the Cinny URL
+### Adjusting the Cinny URL (optional)
-
-By default, this playbook installs Cinny on the `cinny.` subdomain (`cinny.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
 
 By tweaking the `matrix_client_cinny_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
 
-While a `matrix_client_cinny_path_prefix` variable exists for tweaking the path-prefix, it's [not supported anymore](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.
+Example additional configuration for your `vars.yml` file:
-
-Example additional configuration for your `inventory/host_vars/matrix.example.com/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 }}"
+
+# Expose under the /cinny subpath
+# matrix_client_cinny_path_prefix: /cinny
 ```
 
-## Adjusting DNS records
+After changing the domain, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server.
 
-Once you've decided on 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.
 
-By default, you will need to create a CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+### Extending the configuration
 
-If you've adjusted `matrix_client_cinny_hostname`, you will need to adjust your DNS configuration accordingly.
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-cinny/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-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 `matrix_client_cinny_configuration_extension_json` variable
 
 ## Installing
 
@@ -51,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`.

docs/configuring-playbook-client-element-web.md

@@ -1,53 +1,83 @@
+<!--
+SPDX-FileCopyrightText: 2020 - 2022 MDAD project contributors
+SPDX-FileCopyrightText: 2020 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2020 Aaron Raimist
+SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Configuring Element Web (optional)
 
 By default, this playbook installs the [Element Web](https://github.com/element-hq/element-web) Matrix client for you. If that's okay, you can skip this document.
 
+If you'd like to stop the playbook installing the client, see the section [below](#disabling-element-web) to check the configuration for disabling it.
+
 💡 **Note**: the latest version of Element Web is also available on the web, hosted by 3rd parties. If you trust giving your credentials to the following 3rd party Single Page Applications, you can consider using it from there and avoiding the (small) overhead of self-hosting (by [disabling Element Web](#disabling-element-web)):
 
 - [app.element.io](https://app.element.io/), hosted by [Element](https://element.io/)
 - [app.etke.cc](https://app.etke.cc/), hosted by [etke.cc](https://etke.cc/)
 
-## Disabling Element Web
+## Adjusting DNS records
 
-If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+By default, this playbook installs Element Web on the `element.` subdomain (`element.example.com`) and requires you to create a CNAME record for `element`, which targets `matrix.example.com`.
 
-```yaml
+When setting, replace `example.com` with your own.
-matrix_client_element_enabled: false
-```
 
 ## Adjusting the playbook configuration
 
-The playbook provides some customization variables you could use to change Element Web's settings.
+### Set the country code for phone number inputs
 
-Their defaults are defined in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-element/templates/config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2) template.
+You can change the country code (default: `GB`) to use when showing phone number inputs. To change it to `FR` for example, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
+```yaml
-
+matrix_client_element_default_country_code: "FR"
-Alternatively, **if there is no pre-defined variable** for an Element Web setting you wish to change:
+```
-
-- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Element Web's various settings that rarely get used.
-
-- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
-
-- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
 
 ### Themes
 
-To change the look of Element Web, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
+#### Change the default theme
 
-Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_element_themes_enabled: true`).
+You can change the default theme from `light` to `dark`. To do so, add the following configuration to your `vars.yml` file:
 
-If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
+```yaml
+# Controls the default theme
+matrix_client_element_default_theme: 'dark'
+```
+
+#### Use themes by `element-themes`
+
+You can change the look of Element Web by pulling themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project or defining your own themes manually.
+
+To pull the themes and use them for your Element Web instance, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_client_element_themes_enabled: true
+```
+
+If the variable is set to `true`, all themes found in the repository specified with `matrix_client_element_themes_repository_url` will be installed and enabled automatically.
 
 Note that for a custom theme to work well, all Element Web instances that you use must have the same theme installed.
 
-### Adjusting the Element Web URL
+#### Define themes manually
 
-By default, this playbook installs Element Web on the `element.` subdomain (`element.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+You can also define your own themes manually by adding and adjusting the following configuration to your `vars.yml` file:
+
+```yaml
+# Controls the `setting_defaults.custom_themes` setting of the Element Web configuration.
+matrix_client_element_setting_defaults_custom_themes: []
+```
+
+If you define your own themes with it and set `matrix_client_element_themes_enabled` to `true` for the themes by `element-themes`, your themes will be preserved as well.
+
+If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
+
+### Adjusting the Element Web URL (optional)
 
 By tweaking the `matrix_client_element_hostname` and `matrix_client_element_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Switch to the domain used for Matrix services (`matrix.example.com`),
@@ -58,14 +88,45 @@ matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_client_element_path_prefix: /element
 ```
 
-## Adjusting DNS records
+After changing the domain, **you may need to adjust your DNS** records to point the Element domain to the Matrix server.
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Element Web domain to the Matrix server.
-
-By default, you will need to create a CNAME record for `element`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 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 component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-element/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-element/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 `matrix_client_element_configuration_extension_json` variable
+
+For example, to override some Element Web settings, add the following configuration to your `vars.yml` file:
+
+```yaml
+ # Your custom JSON configuration for Element Web should go to `matrix_client_element_configuration_extension_json`.
+ # This configuration extends the default starting configuration (`matrix_client_element_configuration_default`).
+ #
+ # 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_client_element_configuration_default`.
+ #
+matrix_client_element_configuration_extension_json: |
+ {
+ "disable_3pid_login": true,
+ "disable_login_language_selector": true
+ }
+```
+
+## Disabling Element Web
+
+If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_client_element_enabled: false
+```
+
 ## 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:
@@ -78,3 +139,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-element`.

docs/configuring-playbook-client-fluffychat-web.md

@@ -0,0 +1,66 @@
+<!--
+SPDX-FileCopyrightText: 2025 Nikita Chernyi
+SPDX-FileCopyrightText: 2025 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up FluffyChat Web (optional)
+
+The playbook can install and configure the [FluffyChat Web](https://github.com/krille-chan/fluffychat) Matrix client for you.
+
+FluffyChat Web is a cute cross-platform (web, iOS, Android) messenger for Matrix written in [Flutter](https://flutter.dev/).
+
+💡 **Note**: the latest version of FluffyChat Web is also available on the web, hosted by 3rd parties. If you trust giving your credentials to the following 3rd party Single Page Application, you can consider using it from there:
+
+- [fluffychat.im](https://fluffychat.im/web), hosted by the [FluffyChat](https://fluffychat.im/) developers
+
+## Adjusting DNS records
+
+By default, this playbook installs FluffyChat Web on the `fluffychat.` subdomain (`fluffychat.example.com`) and requires you to create a CNAME record for `fluffychat`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+## Adjusting the playbook configuration
+
+To enable FluffyChat Web, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_client_fluffychat_enabled: true
+```
+
+### Adjusting the FluffyChat Web URL (optional)
+
+By tweaking the `matrix_client_fluffychat_hostname` and `matrix_client_fluffychat_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 FluffyChat Web.
+matrix_client_fluffychat_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /fluffychat subpath
+matrix_client_fluffychat_path_prefix: /fluffychat
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the FluffyChat Web 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,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-fluffychat`.

docs/configuring-playbook-client-hydrogen.md

@@ -1,9 +1,24 @@
+<!--
+SPDX-FileCopyrightText: 2021 Aaron Raimist
+SPDX-FileCopyrightText: 2021 MDAD project contributors
+SPDX-FileCopyrightText: 2023 Pierre 'McFly' Marty
+SPDX-FileCopyrightText: 2024 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Hydrogen (optional)
 
-This playbook can install the [Hydrogen](https://github.com/element-hq/hydrogen-web) Matrix web client for you.
+The playbook can install and configure the [Hydrogen](https://github.com/element-hq/hydrogen-web) Matrix web client for you.
 
 Hydrogen is a lightweight web client that supports mobile and legacy web browsers. It can be installed alongside or instead of Element Web.
 
+## Adjusting DNS records
+
+By default, this playbook installs Hydrogen on the `hydrogen.` subdomain (`hydrogen.example.com`) and requires you to create a CNAME record for `hydrogen`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
 ## Adjusting the playbook configuration
 
 To enable Hydrogen, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -12,13 +27,11 @@ To enable Hydrogen, add the following configuration to your `inventory/host_vars
 matrix_client_hydrogen_enabled: true
 ```
 
-### Adjusting the Hydrogen URL
+### Adjusting the Hydrogen URL (optional)
-
-By default, this playbook installs Hydrogen on the `hydrogen.` subdomain (`hydrogen.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
 
 By tweaking the `matrix_client_hydrogen_hostname` and `matrix_client_hydrogen_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Switch to the domain used for Matrix services (`matrix.example.com`),
@@ -29,14 +42,19 @@ matrix_client_hydrogen_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_client_hydrogen_path_prefix: /hydrogen
 ```
 
-## Adjusting DNS records
+After changing the domain, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server.
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server.
-
-By default, you will need to create a CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 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 client.
+
+Take a look at:
+
+- `roles/custom/matrix-client-hydrogen/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-hydrogen/templates/config.json.j2` for the client's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_hydrogen_configuration_extension_json` variable
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
@@ -49,3 +67,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-hydrogen`.

docs/configuring-playbook-client-schildichat-web.md

@@ -1,6 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2023 Nikita Chernyi
+SPDX-FileCopyrightText: 2023 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up SchildiChat Web (optional)
 
-This playbook can install the [SchildiChat Web](https://github.com/SchildiChat/schildichat-desktop) Matrix client for you.
+The playbook can install and configure the [SchildiChat Web](https://github.com/SchildiChat/schildichat-desktop) Matrix client for you.
 
 SchildiChat Web is a feature-rich messenger for Matrix based on Element Web with some extras and tweaks. It can be installed alongside or instead of Element Web.
 
@@ -8,6 +16,12 @@ SchildiChat Web is a feature-rich messenger for Matrix based on Element Web with
 
 - [app.schildi.chat](https://app.schildi.chat/), hosted by the [SchildiChat](https://schildi.chat/) developers
 
+## Adjusting DNS records
+
+By default, this playbook installs SchildiChat Web on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to create a CNAME record for `schildichat`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
 ## Adjusting the playbook configuration
 
 To enable SchildiChat Web, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -16,37 +30,57 @@ To enable SchildiChat Web, add the following configuration to your `inventory/ho
 matrix_client_schildichat_enabled: true
 ```
 
-The playbook provides some customization variables you could use to change SchildiChat Web's settings.
+### Set the country code for phone number inputs
 
-Their defaults are defined in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml) and they ultimately end up in the generated `/matrix/schildichat/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-schildichat/templates/config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2) template.
+You can change the country code (default: `GB`) to use when showing phone number inputs. To change it to `FR` for example, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
+```yaml
-
+matrix_client_schildichat_default_country_code: "FR"
-Alternatively, **if there is no pre-defined variable** for a SchildiChat Web setting you wish to change:
+```
-
-- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of SchildiChat Web's various settings that rarely get used.
-
-- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2)) by making use of the `matrix_client_schildichat_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
-
-- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_schildichat_configuration_default` (or `matrix_client_schildichat_configuration`). You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
 
 ### Themes
 
-To change the look of SchildiChat Web, you can define your own themes manually by using the `matrix_client_schildichat_setting_defaults_custom_themes` setting.
+#### Change the default theme
 
-Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_schildichat_themes_enabled: true`).
+You can change the default theme from `light` to `dark`. To do so, add the following configuration to your `vars.yml` file:
 
-If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
+```yaml
+# Controls the default theme
+matrix_client_schildichat_default_theme: 'dark'
+```
+
+#### Use themes by `element-themes`
+
+You can change the look of SchildiChat Web by pulling themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project or defining your own themes manually.
+
+To pull the themes and use them for your SchildiChat Web instance, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_client_schildichat_themes_enabled: true
+```
+
+If the variable is set to `true`, all themes found in the repository specified with `matrix_client_schildichat_themes_repository_url` will be installed and enabled automatically.
 
 Note that for a custom theme to work well, all SchildiChat Web instances that you use must have the same theme installed.
 
-### Adjusting the SchildiChat Web URL
+#### Define themes manually
 
-By default, this playbook installs SchildiChat Web on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+You can also define your own themes manually by adding and adjusting the following configuration to your `vars.yml` file:
+
+```yaml
+# Controls the `setting_defaults.custom_themes` setting of the SchildiChat Web configuration.
+matrix_client_schildichat_setting_defaults_custom_themes: []
+```
+
+If you define your own themes with it and set `matrix_client_schildichat_themes_enabled` to `true` for the themes by `element-themes`, your themes will be preserved as well.
+
+If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
+
+### Adjusting the SchildiChat Web URL (optional)
 
 By tweaking the `matrix_client_schildichat_hostname` and `matrix_client_schildichat_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Switch to the domain used for Matrix services (`matrix.example.com`),
@@ -57,14 +91,37 @@ matrix_client_schildichat_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_client_schildichat_path_prefix: /schildichat
 ```
 
-## Adjusting DNS records
+After changing the domain, **you may need to adjust your DNS** records to point the SchildiChat Web domain to the Matrix server.
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the SchildiChat Web domain to the Matrix server.
-
-By default, you will need to create a CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 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 component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-schildichat/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-schildichat/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 `matrix_client_schildichat_configuration_extension_json` variable
+
+For example, to override some SchildiChat Web settings, add the following configuration to your `vars.yml` file:
+
+```yaml
+ # Your custom JSON configuration for SchildiChat Web should go to `matrix_client_schildichat_configuration_extension_json`.
+ # This configuration extends the default starting configuration (`matrix_client_schildichat_configuration_default`).
+ #
+ # 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_client_schildichat_configuration_default`.
+ #
+matrix_client_schildichat_configuration_extension_json: |
+ {
+ "disable_3pid_login": true,
+ "disable_login_language_selector": true
+ }
+```
+
 ## 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:
@@ -77,3 +134,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-schildichat`.

docs/configuring-playbook-conduit.md

@@ -1,27 +1,53 @@
+<!--
+SPDX-FileCopyrightText: 2022 - 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Configuring Conduit (optional)
 
-By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).
+The playbook can install and configure the [Conduit](https://conduit.rs) Matrix server for you.
 
-**Notes**:
+See the project's [documentation](https://docs.conduit.rs/) to learn what it does and why it might be useful to you.
 
-- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Conduit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
+By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
 
-- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
+💡 **Note**: The playbook also supports installing a (currently) faster-moving Conduit fork called [conduwuit](./configuring-playbook-conduwuit.md).
+
+> [!WARNING]
+> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Conduit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
+> - **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
 
 ## Adjusting the playbook configuration
 
-To use Conduit, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To use Conduit, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
 
 ```yaml
 matrix_homeserver_implementation: conduit
 ```
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the server.
+
+Take a look at:
+
+- `roles/custom/matrix-conduit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-conduit/templates/conduit.toml.j2` for the server's default configuration
+
+If you'd like to have your own different configuration, feel free to copy and paste the original files into your inventory (e.g. in `inventory/host_vars/matrix.example.com/`) and then change the specific host's `vars.yml` file like this:
+
+```yaml
+matrix_conduit_template_conduit_config: "{{ playbook_dir }}/inventory/host_vars/matrix.example.com/conduit.toml.j2"
+```
+
 ## Creating the first user account
 
 Since it is difficult to create the first user account on Conduit (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) and it does not support [registering users](registering-users.md) (via the command line or via the playbook) like Synapse and Dendrite do, we recommend the following procedure:
 
 1. Add `matrix_conduit_allow_registration: true` to your `vars.yml` the first time around, temporarily
-2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` - see [Installing](installing.md))
+2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` — see [Installing](installing.md))
 3. Create your first user via Element Web or any other client which supports creating users
 4. Get rid of `matrix_conduit_allow_registration: true` from your `vars.yml`
 5. Run the playbook again (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-conduit,start` would be enough this time)
@@ -29,9 +55,9 @@ Since it is difficult to create the first user account on Conduit (see [famedly/
 
 ## Configuring bridges / appservices
 
-Automatic appservice setup is currently unsupported when using Conduit. After setting up the service as usual you may notice that it is unable to start.
+For other homeserver implementations (like Synapse and Dendrite), the playbook automatically registers appservices (for bridges, bots, etc.) with the homeserver.
 
-You will have to manually register appservices using the the [register-appservice](https://gitlab.com/famedly/conduit/-/blob/next/APPSERVICES.md) command.
+For Conduit, you will have to manually register appservices using the the [register-appservice](https://gitlab.com/famedly/conduit/-/blob/next/APPSERVICES.md) command.
 
 Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to Conduit:
 
@@ -39,6 +65,7 @@ Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/ma
     ```
     as_token: <token>
     de.sorunome.msc2409.push_ephemeral: true
+    receive_ephemeral: true
     hs_token: <token>
     id: signal
     namespaces:
@@ -54,3 +81,7 @@ Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/ma
     sender_localpart: _bot_signalbot
     url: http://matrix-mautrix-signal:29328
     ```
+
+## 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-conduit`.

docs/configuring-playbook-conduwuit.md

@@ -0,0 +1,106 @@
+<!--
+SPDX-FileCopyrightText: 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Configuring conduwuit (optional)
+
+The playbook can install and configure the [conduwuit](https://conduwuit.puppyirl.gay/) Matrix server for you.
+
+See the project's [documentation](https://conduwuit.puppyirl.gay/) to learn what it does and why it might be useful to you.
+
+By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
+
+💡 **Note**: conduwuit is a fork of [Conduit](./configuring-playbook-conduit.md), which the playbook also supports. See [Differences from upstream Conduit](https://conduwuit.puppyirl.gay/differences.html).
+
+> [!WARNING]
+> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> conduwuit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
+> - **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
+> - **the Conduwuit project appears to have been abandoned**. You may wish to install [Conduit](./configuring-playbook-conduit.md), or one of the Conduwuit successors (like [Continuwuity](configuring-playbook-continuwuity.md))
+
+## Adjusting the playbook configuration
+
+To use conduwuit, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
+
+```yaml
+matrix_homeserver_implementation: conduwuit
+
+# Registering users can only happen via the API,
+# so it makes sense to enable it, at least initially.
+matrix_conduwuit_config_allow_registration: true
+
+# Generate a strong registration token to protect the registration endpoint from abuse.
+# You can create one with a command like `pwgen -s 64 1`.
+matrix_conduwuit_config_registration_token: ''
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the server.
+
+Take a look at:
+
+- `roles/custom/matrix-conduwuit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-conduwuit/templates/conduwuit.toml.j2` for the server's default configuration
+
+There are various Ansible variables that control settings in the `conduwuit.toml` file.
+
+If a specific setting you'd like to change does not have a dedicated Ansible variable, you can either submit a PR to us to add it, or you can [override the setting using an environment variable](https://conduwuit.puppyirl.gay/configuration.html#environment-variables) using `matrix_conduwuit_environment_variables_extension`. For example:
+
+```yaml
+matrix_conduwuit_environment_variables_extension: |
+  CONDUWUIT_MAX_REQUEST_SIZE=50000000
+  CONDUWUIT_REQUEST_TIMEOUT=60
+```
+
+## Creating the first user account
+
+Unlike other homeserver implementations (like Synapse and Dendrite), conduwuit does not support creating users via the command line or via the playbook.
+
+If you followed the instructions above (see [Adjusting the playbook configuration](#adjusting-the-playbook-configuration)), you should have registration enabled and protected by a registration token.
+
+This should allow you to create the first user account via any client (like [Element Web](./configuring-playbook-client-element-web.md)) which supports creating users.
+
+The **first user account that you create will be marked as an admin** and **will be automatically invited to an admin room**.
+
+
+## Configuring bridges / appservices
+
+For other homeserver implementations (like Synapse and Dendrite), the playbook automatically registers appservices (for bridges, bots, etc.) with the homeserver.
+
+For conduwuit, you will have to manually register appservices using the [`!admin appservices register` command](https://conduwuit.puppyirl.gay/appservices.html#set-up-the-appservice---general-instructions) sent to the server bot account.
+
+The server's bot account has a Matrix ID of `@conduit:example.com` (not `@conduwuit:example.com`!) due to conduwuit's historical legacy.
+Your first user account would already have been invited to an admin room with this bot.
+
+Find the appservice file you'd like to register. This can be any `registration.yaml` file found in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`.
+
+Then, send its content to the existing admin room:
+
+    !admin appservices register
+
+    ```
+    as_token: <token>
+    de.sorunome.msc2409.push_ephemeral: true
+    receive_ephemeral: true
+    hs_token: <token>
+    id: signal
+    namespaces:
+      aliases:
+      - exclusive: true
+        regex: ^#signal_.+:example\.org$
+      users:
+      - exclusive: true
+        regex: ^@signal_.+:example\.org$
+      - exclusive: true
+        regex: ^@signalbot:example\.org$
+    rate_limited: false
+    sender_localpart: _bot_signalbot
+    url: http://matrix-mautrix-signal:29328
+    ```
+
+## 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-conduwuit`.

docs/configuring-playbook-continuwuity.md

@@ -0,0 +1,117 @@
+<!--
+SPDX-FileCopyrightText: 2025 Slavi Pantaleev
+SPDX-FileCopyrightText: 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Configuring Continuwuity (optional)
+
+The playbook can install and configure the [Continuwuity](https://continuwuity.org) Matrix server for you.
+
+See the project's [documentation](https://continuwuity.org) to learn what it does and why it might be useful to you.
+
+By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
+
+💡 **Note**: continuwuity is a fork of [conduwuit](./configuring-playbook-conduwuit.md), which the playbook also supports.
+
+> [!WARNING]
+> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Continuwuity). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
+> - **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
+
+## Adjusting the playbook configuration
+
+To use Continuwuity, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
+
+```yaml
+matrix_homeserver_implementation: continuwuity
+
+# Registering users can only happen via the API,
+# so it makes sense to enable it, at least initially.
+matrix_continuwuity_config_allow_registration: true
+
+# Generate a strong registration token to protect the registration endpoint from abuse.
+# You can create one with a command like `pwgen -s 64 1`.
+matrix_continuwuity_config_registration_token: ''
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the server.
+
+Take a look at:
+
+- `roles/custom/matrix-continuwuity/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-continuwuity/templates/continuwuity.toml.j2` for the server's default configuration
+
+There are various Ansible variables that control settings in the `continuwuity.toml` file.
+
+If a specific setting you'd like to change does not have a dedicated Ansible variable, you can either submit a PR to us to add it, or you can [override the setting using an environment variable](https://continuwuity.org/configuration#environment-variables) using `matrix_continuwuity_environment_variables_extension`. For example:
+
+```yaml
+matrix_continuwuity_environment_variables_extension: |
+  continuwuity_MAX_REQUEST_SIZE=50000000
+  continuwuity_REQUEST_TIMEOUT=60
+```
+
+## Creating the first user account
+
+Unlike other homeserver implementations (like Synapse and Dendrite), continuwuity does not support creating users via the command line or via the playbook.
+
+If you followed the instructions above (see [Adjusting the playbook configuration](#adjusting-the-playbook-configuration)), you should have registration enabled and protected by a registration token.
+
+This should allow you to create the first user account via any client (like [Element Web](./configuring-playbook-client-element-web.md)) which supports creating users.
+
+The **first user account that you create will be marked as an admin** and **will be automatically invited to an admin room**.
+
+
+## Configuring bridges / appservices
+
+For other homeserver implementations (like Synapse and Dendrite), the playbook automatically registers appservices (for bridges, bots, etc.) with the homeserver.
+
+For continuwuity, you will have to manually register appservices using the [`!admin appservices register` command](https://continuwuity.org/appservices.html#set-up-the-appservice---general-instructions) sent to the server bot account.
+
+The server's bot account has a Matrix ID of `@conduit:example.com` (not `@continuwuity:example.com`!) due to continuwuity's historical legacy.
+Your first user account would already have been invited to an admin room with this bot.
+
+Find the appservice file you'd like to register. This can be any `registration.yaml` file found in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`.
+
+Then, send its content to the existing admin room:
+
+    !admin appservices register
+
+    ```
+    as_token: <token>
+    de.sorunome.msc2409.push_ephemeral: true
+    receive_ephemeral: true
+    hs_token: <token>
+    id: signal
+    namespaces:
+      aliases:
+      - exclusive: true
+        regex: ^#signal_.+:example\.org$
+      users:
+      - exclusive: true
+        regex: ^@signal_.+:example\.org$
+      - exclusive: true
+        regex: ^@signalbot:example\.org$
+    rate_limited: false
+    sender_localpart: _bot_signalbot
+    url: http://matrix-mautrix-signal:29328
+    ```
+
+## Migrating from conduwuit
+
+Since Continuwuity is a drop-in replacement for [conduwuit](configuring-playbook-conduwuit.md), migration is possible.
+
+1. Make sure that Continuwuity is properly set up on your `vars.yml` as described above
+
+2. Make sure that Conduwuit references are removed from your `vars.yml` file
+
+3. Run the installation in a way that installs new services and uninstalls old ones (e.g. `just setup-all`)
+
+4. Run the playbook with the `continuwuity-migrate-from-conduwuit` tag (e.g. `just run-tags continuwuity-migrate-from-conduwuit`). This migrates data from `/matrix/conduwuit` to `/matrix/continuwuity`
+
+## 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-continuwuity`.

docs/configuring-playbook-dendrite.md

@@ -1,34 +1,60 @@
+<!--
+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
+-->
+
 # Configuring Dendrite (optional)
 
-By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Dendrite](https://github.com/matrix-org/dendrite).
+The playbook can install and configure the [Dendrite](https://github.com/element-hq/dendrite) Matrix server for you.
 
-**Notes**:
+See the project's [documentation](https://element-hq.github.io/dendrite/) to learn what it does and why it might be useful to you.
 
-- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Dendrite). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
+By default, the playbook installs [Synapse](https://github.com/element-hq/synapse) as it's the only full-featured Matrix server at the moment. If that's okay, you can skip this document.
 
-- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
+> [!WARNING]
+> - **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Dendrite). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
+> - **Homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
 
 ## Adjusting the playbook configuration
 
-To use Dendrite, you **generally** need to add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To use Dendrite, you **generally** need to adjust the `matrix_homeserver_implementation: synapse` configuration on your `inventory/host_vars/matrix.example.com/vars.yml` file as below:
 
 ```yaml
 matrix_homeserver_implementation: dendrite
 ```
 
-The playbook provides lots of customization variables you could use to change Dendrite's settings.
+### Extending the configuration
 
-Their defaults are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2) template.
+There are some additional things you may wish to configure about the server.
 
-**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
+Take a look at:
 
-Alternatively, **if there is no pre-defined variable** for a Dendrite setting you wish to change:
+- `roles/custom/matrix-dendrite/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-dendrite/templates/dendrite.yaml.j2` for the server's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_dendrite_configuration_extension_yaml` variable
 
-- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Dendrite's various settings that rarely get used.
+For example, to override some Dendrite settings, add the following configuration to your `vars.yml` file:
 
-- or, you can **extend and override the default configuration** ([`dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2)) by making use of the `matrix_dendrite_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
+```yaml
-
+matrix_dendrite_configuration_extension_yaml: |
-- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
+  # Your custom YAML configuration for Dendrite goes here.
+  # This configuration extends the default starting configuration (`matrix_dendrite_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_dendrite_configuration_yaml`.
+  #
+  # Example configuration extension follows:
+  #
+  server_notices:
+    system_mxid_localpart: notices
+    system_mxid_display_name: "Server Notices"
+    system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ"
+    room_name: "Server Notices"
+```
 
 ## Installing
 
@@ -42,3 +68,18 @@ 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-dendrite`.
+
+### 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_dendrite_configuration_extension_yaml: |
+  logging:
+  - type: std
+    level: debug
+```

docs/configuring-playbook-dimension.md

@@ -1,22 +1,76 @@
+<!--
+SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2019 - 2025 MDAD project contributors
+SPDX-FileCopyrightText: 2019 Edgars Voroboks
+SPDX-FileCopyrightText: 2020 Chris van Dijk
+SPDX-FileCopyrightText: 2020 jens quade
+SPDX-FileCopyrightText: 2022 Dennis Ciba
+SPDX-FileCopyrightText: 2022 Kim Brose
+SPDX-FileCopyrightText: 2022 Travis Ralston
+SPDX-FileCopyrightText: 2022 Yan Minagawa
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Dimension integration manager (optional, unmaintained)
 
-**[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.** If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later.
+**Notes**:
+- Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
+- This playbook now supports running Dimension in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`.
 
-**Note**: Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
+The playbook can install and configure the [Dimension](https://dimension.t2bot.io) integration manager for you.
 
-**Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
+See the project's [documentation](https://github.com/turt2live/matrix-dimension/blob/master/README.md) to learn what it does and why it might be useful to you.
+
+## Prerequisites
+
+### Open Matrix Federation port
+
+Enabling the Dimension service will automatically reconfigure your Synapse homeserver to expose the `openid` API endpoints on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. If you enable the component, make sure that the port is accessible.
+
+### Install Matrix services
+
+Dimension can only be installed after Matrix services are installed and running. If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) and come back here later.
+
+### Register a dedicated Matrix user (optional, recommended)
+
+We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username).
+
+Generate a strong password for the user. 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=dimension password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user
+```
+
+### Obtain an access token
+
+Dimension 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 Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to create a CNAME record for `dimension`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
 
 ## Adjusting the playbook configuration
 
-To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
+To enable Dimension, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
 
 ```yaml
 matrix_dimension_enabled: true
+
+matrix_dimension_access_token: "ACCESS_TOKEN_HERE"
 ```
 
 ### Define admin users
 
-These users can modify the integrations this Dimension supports. Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
+To define admin users who can modify the integrations this Dimension supports, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_dimension_admins:
@@ -26,29 +80,11 @@ matrix_dimension_admins:
 
 The admin interface is accessible within Element Web by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element Web by the "Add widgets, bridges, & bots" link in the room information.
 
-### Access token
+### Adjusting the Dimension URL (optional)
-
-We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username). Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
-
-You are required to specify an access token (belonging to this new user) for Dimension to work. To get an access token for the Dimension user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
-
-**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
-
-Add access token to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
-
-```yaml
-matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"
-```
-
-For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens).
-
-### Adjusting the Dimension URL
-
-By default, this playbook installs Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
 
 By tweaking the `matrix_dimension_hostname` and `matrix_dimension_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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
 # Switch to the domain used for Matrix services (`matrix.example.com`),
@@ -59,13 +95,22 @@ matrix_dimension_hostname: "{{ matrix_server_fqn_matrix }}"
 # matrix_dimension_path_prefix: /dimension
 ```
 
-**Note**: While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain.
+After changing the domain, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
 
-## Adjusting DNS records
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
+**Note**: while there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You'd need to serve Dimension at a dedicated subdomain.
 
-By default, you will need to create a CNAME record for `dimension`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-dimension/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-dimension/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_dimension_configuration_extension_yaml` variable
+
+You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).
 
 ## Installing
 
@@ -82,16 +127,18 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
   `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
-- After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the Room info button (`i`) button in the top right corner of the screen, and then clicking Add widgets, bridges & bots.
+## Usage
 
-## Jitsi domain
+After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the room info button (`i`) on the top right corner, and then clicking the "Add widgets, bridges, & bots" link.
 
-By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `conferenceDomain` of [Jitsi](https://jitsi.org/) audio/video conference widgets. For users running [a self-hosted Jitsi instance](./configuring-playbook-jitsi.md), you will likely want the widget to use your own Jitsi instance. Currently there is no way to configure this via the playbook, see [this issue](https://github.com/turt2live/matrix-dimension/issues/345) for details.
+### Set up a Jitsi widget
 
-In the interim until the above limitation is resolved, an admin user needs to configure the domain via the admin ui once dimension is running. In Element Web, go to *Manage Integrations* &rightarrow; *Settings* &rightarrow; *Widgets* &rightarrow; *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
+By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `conferenceDomain` of [Jitsi](https://jitsi.org/) audio/video conference widgets. For users running [a self-hosted Jitsi instance](configuring-playbook-jitsi.md), you will likely want the widget to use your own Jitsi instance.
 
-## Additional features
+To set up the widget, an admin user needs to configure the domain via the admin UI once Dimension is running. In Element Web, go to *Manage Integrations* → *Settings* → *Widgets* → *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
 
-To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.
+There is unfortunately no way to configure the widget via the playbook. See [this issue](https://github.com/turt2live/matrix-dimension/issues/345) for details.
 
-You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).
+## 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-dimension`.

docs/configuring-playbook-dynamic-dns.md

@@ -1,3 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2020 Scott Crossen
+SPDX-FileCopyrightText: 2020 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
 # Setting up Dynamic DNS (optional)
 
 The playbook can configure Dynamic DNS with [ddclient⁠](https://github.com/ddclient/ddclient) for you. It is a Perl client used to update dynamic DNS entries for accounts on Dynamic DNS Network Service Provider.
@@ -6,7 +14,7 @@ Most cloud providers / ISPs will charge you extra for a static IP address. If yo
 
 ## Prerequisite
 
-You'll need to get a username and password from your DNS provider. Please consult with the provider about how to retrieve them.
+You'll need to authenticate with your DNS provider somehow, in most cases this is simply a username and password but can differ from provider to provider. Please consult with your providers documentation and the upstream [ddclient documentation](https://github.com/ddclient/ddclient/blob/main/ddclient.conf.in) to determine what you'll need to provide to authenticate.
 
 ## Adjusting the playbook configuration
 
@@ -23,6 +31,16 @@ matrix_dynamic_dns_domain_configurations:
     domain: "{{ matrix_domain }}"
 ```
 
+Keep in mind that certain providers may require a different configuration of the `matrix_dynamic_dns_domain_configurations` variable, for provider specific examples see the [upstream documentation](https://github.com/ddclient/ddclient/blob/main/ddclient.conf.in).
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-dynamic-dns/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:
@@ -41,3 +59,8 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 Additional resources:
 
 - https://matrix.org/docs/guides/free-small-matrix-server
+- https://github.com/linuxserver/docker-ddclient
+
+## 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-dynamic-dns`. However, due to an [upstream issue](https://github.com/linuxserver/docker-ddclient/issues/54#issuecomment-1153143132) the logging output is not always complete. For advanced debugging purposes running the `ddclient` tool outside of the container is useful via the following: `ddclient -file ./ddclient.conf -daemon=0 -debug -verbose -noquiet`.