meta: move inventory structure to be more usable

Update ajbura/cinny Docker tag to v4.3.0

.config/ansible-lint.yml

@@ -0,0 +1,17 @@
+---
+
+use_default_rules: true
+
+skip_list:
+  - unnamed-task
+  - no-handler
+  - no-jinja-nesting
+  - schema
+  - command-instead-of-shell
+  - role-name
+  - var-naming[no-role-prefix]
+  # We frequently load configuration from a template (into a variable), then merge that with another variable (configuration extension)
+  # before finally dumping it to a file.
+  - template-instead-of-copy
+
+offline: true

.editorconfig

@@ -19,6 +19,14 @@ trim_trailing_whitespace = true
 indent_style = space
 indent_size = 2
 
+[group_vars/matrix_servers]
+indent_style = space
+indent_size = 2
+
+[justfile]
+indent_style = space
+indent_size = 4
+
 # Markdown Files
 #
 # Two spaces at the end of a line in Markdown mean "new line",

.envrc

@@ -0,0 +1 @@
+use flake

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/ISSUE_TEMPLATE/bug_report.md

@@ -2,7 +2,7 @@
 name: Bug report
 about: Create a report to help us improve
 title: ''
-labels: ''
+labels: bug
 assignees: ''
 
 ---
@@ -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/config.yml

@@ -0,0 +1,6 @@
+---
+blank_issues_enabled: false
+contact_links:
+    - name: Support room on Matrix
+      url: https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com
+      about: Get timely support from more people by joining our Matrix room.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,18 +2,20 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ''
-labels: ''
+labels: suggestion
 assignees: ''
 
 ---
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. Ex. I'm always frustrated when […]
 
 <!--
 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/i-need-help.md

@@ -2,13 +2,15 @@
 name: I need help
 about: Get support from our community
 title: ''
-labels: ''
+labels: question
 assignees: ''
 
 ---
 
 <!--
-NOTE: you can usually get more timely support and from more people by joining our Matrix room (also bridged to IRC). See the [Support section of our README](https://github.com/spantaleev/matrix-docker-ansible-deploy#support)
+NOTE: our FAQ page is available at https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/faq.md. It contains a list of questions and answers about configuration, installation, troubleshooting, etc. Before creating a new issue, you are encouraged to have a look at it.
+
+Also you can usually get more timely support and from more people by joining our Matrix room (also bridged to IRC). See the support section of our README.
 -->
 
 **Playbook Configuration**:
@@ -26,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/renovate.json

@@ -0,0 +1,27 @@
+{
+	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
+	"extends": [
+		"config:base"
+	],
+	"labels": ["dependencies"],
+	"regexManagers": [
+		{
+			"fileMatch": ["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"
+			]
+		}
+	],
+	"packageRules": [
+		{
+			"matchSourceUrlPrefixes": [
+				"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"
+	]
+}

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

@@ -0,0 +1,50 @@
+---
+name: 'Close stale issues and PRs'
+on:  # yamllint disable-line rule:truthy
+  # Use this to do a dry run from a pull request
+  # pull_request:
+  schedule:
+    - cron: '30 1 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          ######################################################################
+          # Issues/PRs
+          ######################################################################
+          exempt-assignees: 'spantaleev,aine-etke'
+          operations-per-run: 500
+          # Use this to do a dry run from a pull request
+          # debug-only: true
+          ######################################################################
+          # Issues
+          ######################################################################
+          stale-issue-message: 'This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days. To exempt the issue from being marked as stale again due to inactivity, add "confirmed" label.'
+          close-issue-message: 'This issue was closed because it has been stalled for 7 days with no activity. If this issue is still reproduced, feel free to provide the issue with up-to-date information.'
+          stale-issue-label: 'stale'
+          # Add this label to exempt the issue from being marked as stale due to inactivity
+          exempt-issue-labels: 'confirmed'
+          # An allow-list of label(s) to only process the issues which contain one of these label(s).
+          any-of-issue-labels: 'needs-info,question'
+          ######################################################################
+          # PRs
+          ######################################################################
+          days-before-pr-stale: '365'
+          days-before-pr-close: '30'
+          stale-pr-message: 'This PR is stale because it has not been provided with required information or its conflicts have not been fixed over a year. Remove stale label or this will be closed in 30 days. To exempt the PR from being marked as stale again due to inactivity, add "confirmed" label.'
+          close-pr-message: 'This PR was closed because it has been stalled for 30 days with no activity.'
+          stale-pr-label: 'stale'
+          # Add this label to exempt the PR from being marked as stale due to inactivity
+          exempt-pr-labels: 'confirmed'
+          # An allow-list of label(s) to only process the PRs which contain one of these label(s).
+          any-of-pr-labels: 'needs-info,needs-rebase'
+          # Use this to ignore updates such as comments (only to keep the PR alive by bumping)
+          ignore-pr-updates: true

.github/workflows/matrix.yml

@@ -7,10 +7,20 @@ on:  # yamllint disable-line rule:truthy
 
 jobs:
   yamllint:
-    name: 🧹 yamllint
+    name: yamllint
     runs-on: ubuntu-latest
     steps:
-      - name: ⤵️ Check out configuration from GitHub
-        uses: actions/checkout@v3
-      - name: 🚀 Run yamllint
-        uses: frenck/action-yamllint@v1.1.2
+      - name: Check out
+        uses: actions/checkout@v4
+      - name: Run yamllint
+        uses: frenck/action-yamllint@v1.5.0
+  ansible-lint:
+    name: ansible-lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+      - name: Run ansible-lint
+        uses: ansible-community/ansible-lint-action@v6.17.0
+        with:
+          path: roles/custom

.gitignore

@@ -1,3 +1,10 @@
-/roles/*/files/scratchpad
+/inventory
+/roles/**/files/scratchpad
 .DS_Store
 .python-version
+.idea/
+.direnv/
+
+# ignore roles pulled by ansible-galaxy
+/roles/galaxy/*
+!/roles/galaxy/.gitkeep

.yamllint

@@ -1,8 +1,5 @@
 ---
 extends: default
 
-ignore: |
-  roles/matrix-synapse/vars/workers.yml
-
 rules:
   line-length: disable

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/>.

Makefile

@@ -0,0 +1,11 @@
+.PHONY: roles lint
+
+help: ## Show this help.
+	@grep -F -h "##" $(MAKEFILE_LIST) | grep -v grep | sed -e 's/\\$$//' | sed -e 's/##//'
+
+roles: ## Pull roles
+	rm -rf roles/galaxy
+	ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force
+
+lint: ## Runs ansible-lint against all roles in the playbook
+	ansible-lint roles/custom

README.md

@@ -2,149 +2,195 @@
 
 # Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker
 
-## Purpose
+## 🎯 Purpose
 
 This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#supported-services) related to that.
 
-That is, it lets you join the Matrix network using your own `@<username>:<your-domain>` identifier, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
+That is, it lets you join the Matrix network using your own user ID like `@alice:example.com`, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
 
-We run all services in [Docker](https://www.docker.com/) containers (see [the container images we use](docs/container-images.md)), which lets us have a predictable and up-to-date setup, across multiple supported distros (see [prerequisites](docs/prerequisites.md)) and [architectures](docs/alternative-architectures.md) (x86/amd64 being recommended).
+We run all [supported services](#-supported-services) in [Docker](https://www.docker.com/) containers (see [the container images we use](docs/container-images.md)), which lets us have a predictable and up-to-date setup, across multiple supported distros (see [prerequisites](docs/prerequisites.md)) and [architectures](docs/alternative-architectures.md) (x86/amd64 being recommended).
 
-[Installation](docs/README.md) (upgrades) and some maintenance tasks are automated using [Ansible](https://www.ansible.com/) (see [our Ansible guide](docs/ansible.md)).
+Installation (upgrades) and some maintenance tasks are automated using [Ansible](https://www.ansible.com/) (see [our Ansible guide](docs/ansible.md)).
 
+## ☁ Self-hosting or Managed / SaaS
 
-## Supported services
+This Ansible playbook tries to make self-hosting and maintaining a Matrix server fairly easy (see [Getting started](#-getting-started)). Still, running any service smoothly requires knowledge, time and effort.
 
-Using this playbook, you can get the following services configured on your server:
+If you like the [FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) spirit of this Ansible playbook, but prefer to put the responsibility on someone else, you can also [get a managed Matrix server from etke.cc](https://etke.cc?utm_source=github&utm_medium=readme&utm_campaign=mdad) (both hosting and on-premises) - a service built on top of this Ansible playbook but with [additional components](https://etke.cc/help/extras/?utm_source=github&utm_medium=readme&utm_campaign=mdad) and [services](https://etke.cc/services/?utm_source=github&utm_medium=readme&utm_campaign=mdad) which all help you run a Matrix server with ease. Be advised that etke.cc operates on a subscription-based approach and there is no "just set up my server once and be done with it" option.
 
-- (optional, default) a [Synapse](https://github.com/matrix-org/synapse) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network
+## 🚀 Getting started
 
-- (optional) a [Dendrite](https://github.com/matrix-org/dendrite) homeserver - 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.
+We have detailed documentation in the [docs/](./docs) directory - see the Table of Contents in the [documentation README](./docs/README.md).
 
-- (optional) [Amazon S3](https://aws.amazon.com/s3/) storage for Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys)
+While the [list of supported services](#-supported-services) and documentation is very extensive, you don't need to read through everything. We recommend:
 
-- (optional, default) [PostgreSQL](https://www.postgresql.org/) database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible.
+- Starting with the basics. You can always add/remove or tweak services later on.
 
-- (optional, default) a [coturn](https://github.com/coturn/coturn) STUN/TURN server for WebRTC audio/video calls
+- Following our installation guide. There are two guides available for beginners and advanced users:
 
-- (optional, default) free [Let's Encrypt](https://letsencrypt.org/) SSL certificate, which secures the connection to the Synapse server and the Element web UI
+    - ⚡ **[Quick start](./docs/quick-start.md) (for beginners)**: this is recommended for those who do not have an existing Matrix server and want to start quickly with "opinionated defaults".
 
-- (optional, default) an [Element](https://app.element.io/) ([formerly Riot](https://element.io/previously-riot)) web UI, which is configured to connect to your own Synapse server by default
+    - **Full installation guide (for advanced users)**: if you need to import an existing Matrix server's data into the new server or want to learn more while setting up the server, follow this guide by starting with the **[Prerequisites](./docs/prerequisites.md)** documentation page.
 
-- (optional) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
+If you experience an issue on configuring the playbook, setting up your server, maintaining services on it, etc., please take a look at our [FAQ](./docs/faq.md). If you cannot find an answer to your question, feel free to ask for [help and support](#-support).
 
-- (optional, default) an [Exim](https://www.exim.org/) mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server)
+## ✔ Supported services
 
-- (optional, default) an [nginx](http://nginx.org/) web server, listening on ports 80 and 443 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md)
+Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
 
-- (optional, advanced) the [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) REST authentication password provider module
+**Notes**:
 
-- (optional, advanced) the [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) password provider module
+- The list below is exhaustive. It includes optional or even some advanced components that you will most likely not need. Sticking with the defaults (which install a subset of the above components) is the best choice, especially for a new installation. You can always re-run the playbook later to add or remove components.
 
-- (optional, advanced) the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider module
+- Deprecated or unmaintained services are not listed. You can find documentations for them [here](docs/configuring-playbook.md#deprecated--unmaintained--removed-services).
 
-- (optional, advanced) the [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) spam checker module
+### Homeserver
 
-- (optional, advanced) the [Matrix Corporal](https://github.com/devture/matrix-corporal) reconciliator and gateway for a managed Matrix server
+The homeserver is the backbone of your Matrix system. Choose one from the following list.
 
-- (optional) the [mautrix-telegram](https://github.com/mautrix/telegram) bridge for bridging your Matrix server to [Telegram](https://telegram.org/)
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [Synapse](https://github.com/element-hq/synapse) | ✅ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network | [Link](docs/configuring-playbook-synapse.md) |
+| [Conduit](https://conduit.rs) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements | [Link](docs/configuring-playbook-conduit.md) |
+| [conduwuit](https://conduwuit.puppyirl.gay/) | ❌ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. conduwuit is a fork of Conduit. | [Link](docs/configuring-playbook-conduwuit.md) |
+| [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) |
 
-- (optional) the [mautrix-whatsapp](https://github.com/mautrix/whatsapp) bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/)
+### Clients
 
-- (optional) the [mautrix-facebook](https://github.com/mautrix/facebook) bridge for bridging your Matrix server to [Facebook](https://facebook.com/)
+Web clients for Matrix that you can host on your own domains.
 
-- (optional) the [mautrix-twitter](https://github.com/mautrix/twitter) bridge for bridging your Matrix server to [Twitter](https://twitter.com/)
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [Element Web](https://github.com/element-hq/element-web) | ✅ | Default Matrix web client, configured to connect to your own Synapse server | [Link](docs/configuring-playbook-client-element-web.md) |
+| [Hydrogen](https://github.com/element-hq/hydrogen-web) | ❌ | Lightweight Matrix client with legacy and mobile browser support | [Link](docs/configuring-playbook-client-hydrogen.md) |
+| [Cinny](https://github.com/ajbura/cinny) |  ❌ | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
+| [SchildiChat Web](https://schildi.chat/) | ❌ | Based on Element Web, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat-web.md) |
 
-- (optional) the [mautrix-hangouts](https://github.com/mautrix/hangouts) bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts)
+### Server Components
 
-- (optional) the [mautrix-googlechat](https://github.com/mautrix/googlechat) bridge for bridging your Matrix server to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat)
+Services that run on the server to make the various parts of your installation work.
 
-- (optional) the [mautrix-instagram](https://github.com/mautrix/instagram) bridge for bridging your Matrix server to [Instagram](https://instagram.com/)
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [PostgreSQL](https://www.postgresql.org/)| ✅ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
+| [coturn](https://github.com/coturn/coturn) | ✅ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
+| [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. [Using your own webserver](docs/configuring-playbook-own-webserver.md) is also possible. | [Link](docs/configuring-playbook-traefik.md) |
+| [Let's Encrypt](https://letsencrypt.org/) | ✅ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
+| [Exim](https://www.exim.org/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
+| [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) |
 
-- (optional) the [mautrix-signal](https://github.com/mautrix/signal) bridge for bridging your Matrix server to [Signal](https://www.signal.org/)
+### Authentication
 
-- (optional) the [beeper-linkedin](https://gitlab.com/beeper/linkedin) bridge for bridging your Matrix server to [LinkedIn](https://www.linkedin.com/)
+Extend and modify how users are authenticated on your homeserver.
 
-- (optional) the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat)
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) (advanced) | ❌ | REST authentication password provider module | [Link](docs/configuring-playbook-rest-auth.md) |
+|[matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) (advanced) | ❌ | Password provider module | [Link](docs/configuring-playbook-shared-secret-auth.md) |
+| [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) (advanced) | ❌ | LDAP Auth password provider module | [Link](docs/configuring-playbook-ldap-auth.md) |
+| [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | ❌ | Proxy that handles Matrix registration requests and forwards them to LDAP | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
+| [matrix-registration](https://github.com/ZerataX/matrix-registration) | ❌ | Simple python application to have a token based Matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
+| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (UVS) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
+| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | Spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
 
-- (optional) the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge for bridging your Matrix server to [Discord](https://discordapp.com/)
+### File Storage
 
-- (optional) the [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) bridge for bridging your Matrix server to [Slack](https://slack.com/)
+Use alternative file storage to the default `media_store` folder.
 
-- (optional) the [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.)
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [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) | ❌ | 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) |
 
-- (optional) the [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) bridge for bridging Matrix to generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular
+### Bridges
 
-- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
+Bridges can be used to connect your Matrix installation with third-party communication networks.
 
-- (optional) the [Heisenbridge](https://github.com/hifi/heisenbridge) for bridging your Matrix server to IRC bouncer-style - see [docs/configuring-playbook-bridge-heisenbridge.md](docs/configuring-playbook-bridge-heisenbridge.md) for setup documentation
-
-- (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
-
-- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
-
-- (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
-
-- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
-
-- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
-
-- (optional) the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
-
-- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
-
-- (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
-
-- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
-
-- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
-
-- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
-
-- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation
-
-- (optional) [honoroit](https://gitlab.com/etke.cc/honoroit) helpdesk bot - see [docs/configuring-playbook-bot-honoroit.md](docs/configuring-playbook-bot-honoroit.md) for setup documentation
-
-- (optional) [Go-NEB](https://github.com/matrix-org/go-neb) multi functional bot written in Go - see [docs/configuring-playbook-bot-go-neb.md](docs/configuring-playbook-bot-go-neb.md) for setup documentation
-
-- (optional) [Mjolnir](https://github.com/matrix-org/mjolnir), a moderation tool for Matrix - see [docs/configuring-playbook-bot-mjolnir.md](docs/configuring-playbook-bot-mjolnir.md) for setup documentation
-
-- (optional) [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), a web UI tool for administrating users and rooms on your Matrix server - see [docs/configuring-playbook-synapse-admin.md](docs/configuring-playbook-synapse-admin.md) for setup documentation
-
-- (optional) [matrix-registration](https://github.com/ZerataX/matrix-registration), a simple python application to have a token based matrix registration - see [docs/configuring-playbook-matrix-registration.md](docs/configuring-playbook-matrix-registration.md) for setup documentation
-
-- (optional) 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 - see [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) for setup documentation
-
-- (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation
-
-- (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation
-
-- (optional) the [Cinny](https://github.com/ajbura/cinny) web client - see [docs/configuring-playbook-client-cinny.md](docs/configuring-playbook-client-cinny.md) for setup documentation
-
-- (optional) the [Borg](https://borgbackup.org) backup - see [docs/configuring-playbook-backup-borg.md](docs/configuring-playbook-backup-borg.md) for setup documentation
-
-- (optional) the [Buscarron](https://gitlab.com/etke.cc/buscarron) bot - see [docs/configuring-playbook-bot-buscarron.md](docs/configuring-playbook-bot-buscarron.md) for setup documentation
-
-Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
-
-**Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.
-Sticking with the defaults (which install a subset of the above components) is the best choice, especially for a new installation.
-You can always re-run the playbook later to add or remove components.
-
-
-## Installation
-
-To configure and install Matrix on your own server, follow the [README in the docs/ directory](docs/README.md).
-
-
-## Changes
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [mautrix-discord](https://github.com/mautrix/discord) | ❌ | Bridge to [Discord](https://discord.com/) | [Link](docs/configuring-playbook-bridge-mautrix-discord.md) |
+| [mautrix-slack](https://github.com/mautrix/slack) | ❌ | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-mautrix-slack.md) |
+| [mautrix-telegram](https://github.com/mautrix/telegram) | ❌ | Bridge to [Telegram](https://telegram.org/) | [Link](docs/configuring-playbook-bridge-mautrix-telegram.md) |
+| [mautrix-gmessages](https://github.com/mautrix/gmessages) | ❌ | Bridge to [Google Messages](https://messages.google.com/) | [Link](docs/configuring-playbook-bridge-mautrix-gmessages.md) |
+| [mautrix-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-twitter](https://github.com/mautrix/twitter) | ❌ | Bridge to [Twitter](https://twitter.com/) | [Link](docs/configuring-playbook-bridge-mautrix-twitter.md) |
+| [mautrix-googlechat](https://github.com/mautrix/googlechat) | ❌ | Bridge to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) | [Link](docs/configuring-playbook-bridge-mautrix-googlechat.md) |
+| [mautrix-meta](https://github.com/mautrix/instagram) | ❌ | Bridge to [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) | Link for [Messenger](docs/configuring-playbook-bridge-mautrix-meta-messenger.md) / [Instagram](docs/configuring-playbook-bridge-mautrix-meta-instagram.md) |
+| [mautrix-signal](https://github.com/mautrix/signal) | ❌ | Bridge to [Signal](https://www.signal.org/) | [Link](docs/configuring-playbook-bridge-mautrix-signal.md) |
+| [beeper-linkedin](https://github.com/beeper/linkedin) | ❌ | Bridge to [LinkedIn](https://www.linkedin.com/) | [Link](docs/configuring-playbook-bridge-beeper-linkedin.md) |
+| [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) | ❌ | Bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-appservice-irc.md) |
+| [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) | ❌ | Bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) | [Link](docs/configuring-playbook-bridge-appservice-kakaotalk.md) |
+| [matrix-appservice-discord](https://github.com/matrix-org/matrix-appservice-discord) | ❌ | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-appservice-discord.md) |
+| [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) | ❌ | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-appservice-slack.md) |
+| [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) | ❌ | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | [Link](docs/configuring-playbook-bridge-hookshot.md) |
+| [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | ❌ | Bridge to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) |
+| [matrix-wechat](https://github.com/duo/matrix-wechat) | ❌ | Bridge to [WeChat](https://www.wechat.com/) | [Link](docs/configuring-playbook-bridge-wechat.md) |
+| [Heisenbridge](https://github.com/hifi/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-heisenbridge.md) |
+| [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) | ❌ | Bridge to [Skype](https://www.skype.com) | [Link](docs/configuring-playbook-bridge-go-skype-bridge.md) |
+| [mx-puppet-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) | ❌ | Bridge to [Slack](https://slack.com) | [Link](docs/configuring-playbook-bridge-mx-puppet-slack.md) |
+| [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) | ❌ | Bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-instagram.md) |
+| [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) | ❌ | Bridge for Twitter-DMs ([Twitter](https://twitter.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-twitter.md) |
+| [mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) | ❌ | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-discord.md) |
+| [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | ❌ | Bridge to [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) |
+| [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) |
+| [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) |
+
+### Bots
+
+Bots provide various additional functionality to your installation.
+
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [baibot](https://github.com/etkecc/baibot) | ❌ | Bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you | [Link](docs/configuring-playbook-bot-baibot.md) |
+| [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) | ❌ | Bot for scheduling one-off & recurring reminders and alarms | [Link](docs/configuring-playbook-bot-matrix-reminder-bot.md) |
+| [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) | ❌ | Bot for invitations by creating and managing registration tokens | [Link](docs/configuring-playbook-bot-matrix-registration-bot.md) |
+| [maubot](https://github.com/maubot/maubot) | ❌ | Plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
+| [Honoroit](https://github.com/etkecc/honoroit) | ❌ | Helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
+| [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | Moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
+| [Draupnir](https://github.com/the-draupnir-project/Draupnir) | ❌ | Moderation tool for Matrix (Fork of Mjolnir) | [Link](docs/configuring-playbook-bot-draupnir.md) (for [appservice mode](docs/configuring-playbook-appservice-draupnir-for-all.md))|
+| [Buscarron](https://github.com/etkecc/buscarron) | ❌ | Web forms (HTTP POST) to Matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
+
+### Administration
+
+Services that help you in administrating and monitoring your Matrix installation.
+
+| Name | Default? | Description | Documentation |
+| ---- | -------- | ----------- | ------------- |
+| [matrix-alertmanager-receiver](https://github.com/metio/matrix-alertmanager-receiver) | ❌ | Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) client | [Link](docs/configuring-playbook-alertmanager-receiver.md) |
+| [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) | ❌ | OAuth 2.0 and OpenID Provider server | [Link](docs/configuring-playbook-matrix-authentication-service.md) |
+| [synapse-admin](https://github.com/etkecc/synapse-admin) | ❌ | Web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
+| 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) |
+
+### Misc
+
+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) | ❌ | 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) | ❌ | 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) | ❌ | Open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
+| [Jitsi](https://jitsi.org/) | ❌ | Open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
+| [Cactus Comments](https://cactus.chat) | ❌ | Federated comment system built on Matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
+| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | ❌ | E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
+| [Sygnal](https://github.com/matrix-org/sygnal) | ❌ | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
+| [ntfy](https://ntfy.sh) | ❌ | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
+
+## 🆕 Changes
 
 This playbook evolves over time, sometimes with backward-incompatible changes.
 
 When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
 
-
-## Support
+## 🆘 Support
 
 - Matrix room: [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)
 
@@ -152,7 +198,14 @@ 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
 
-## Services by the community
+See the [i18n/README.md](i18n/README.md) file for more information about translation.
 
-- [etke.cc](https://etke.cc) - matrix-docker-ansible-deploy and system stuff "as a service". That service will create your matrix homeserver on your domain and server (doesn't matter if it's cloud provider or on an old laptop in the corner of your room), (optional) maintains it (server's system updates, cleanup, security adjustments, tuning, etc.; matrix homeserver updates & maintenance) and (optional) provide full-featured email service for your domain
+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)).
+
+mash-playbook also makes use of [Traefik](./docs/configuring-playbook-traefik.md) as its reverse-proxy, so with minor [interoperability adjustments](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/interoperability.md), you can make matrix-docker-ansible-deploy and mash-playbook co-exist and host Matrix and non-Matrix services on the same server.

YEAR-IN-REVIEW.md

@@ -0,0 +1,106 @@
+# 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:
+
+*   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.
+
+`matrix-nginx-proxy` is no longer in the way of us being interoperable, but its ugly internal details are still there. It is one more proxy in the long chain of reverse-proxies we have and we'd like to cut it out. This would both make things simpler and also boost performance.
+
+The delay in eliminating `matrix-nginx-proxy` has probably been welcome by many existing users who decided to postpone the Traefik migration a bit longer. In 2024, work on eliminating `matrix-nginx-proxy` will continue with rapid pace. People who are still using `matrix-nginx-proxy` as their front-most reverse-proxy will need to rework their setup. About a year of putting it off has been long enough.
+
+This large Traefik reverse-proxy change was also accompanied by another internal change which began in 2022, but continued in 2023 - **moving non-Matrix-related roles from being internal to the playbook to living their own life outside of it**. Various roles were made more decoupled and moved outside of the playbook, so that other projects (like the [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) Ansible playbook or other Ansible playbooks) could benefit from them. This led to the **death of a few sibling playbooks** ([gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy), [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy), [peertube-docker-ansible-deploy](https://github.com/spantaleev/peertube-docker-ansible-deploy), [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy)), but brought life to something better, which supports all these services and more.
+
+[mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) is a new Ansible playbook that a few of us (matrix-docker-ansible-deploy contributors) have launched in 2023. It has quickly grown to supports [60+ services](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md) and aims to do the same for [FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) service hosting, as matrix-docker-ansible-deploy has done for Matrix - providing a clean and secure way to run a bunch of services in containers on a regular server (that is to say, without Kubernetes, etc.). Thanks to Traefik and Ansible role reuse, it's easy to host both mash-playbook services and matrix-docker-ansible-deploy services on the same server - see mash-playbook's [interoperability](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/interoperability.md) documentation page. If you've been looking for a holiday project or your New Year's Resolutions list contains "self-hosting more services", then you're welcome to give this new playbook a try and join its Matrix room ([#mash-playbook:devture.com](https://matrix.to/#/#mash-playbook:devture.com)).
+
+Because many of the roles are now external to this playbook (defined in the [requirements.yml](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/da27655ef34999fa924bc0a5e641dbd9ba06f133/requirements.yml) file), running `make roles` (or better yet `just roles` via the [just tool](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#support-for-running-commands-via-just)) becomes a necessity each time one pulls playbook updates (`git pull`). Pulling external roles happens via the [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) command-line tool, but if available, the playbook would also use the much faster [agru](https://github.com/etkecc/agru) tool (developed by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) this year).
+
+With the internal (but important) details out of the way, we can now talk more about **new features that landed in matrix-docker-ansible-deploy in 2023**.
+
+The following **new** **bridges** were added to the playbook in 2023:
+
+*   (2023-01-11) [mautrix-slack](https://mau.dev/mautrix/slack), thanks to a PR by [Cody Neiman](https://github.com/xangelix) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#mautrix-slack-support))
+*   (2023-07-21) [mautrix-gmessages](https://github.com/mautrix/gmessages), thanks to a PR by [Shreyas Ajjarapu](https://github.com/shreyasajj) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#mautrix-gmessages-support))
+*   (2023-08-23) [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for Apple iMessage bridging (when combined with the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android phone), thanks to a PR by [Johan Swetzén](https://github.com/jswetzen)
+
+This brings the total number of **[bridges that the playbook supports](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/docs/configuring-playbook.md#bridging-other-networks) up to 30**. There are alternative bridge implementations for various networks and protocols, so the number of "unique bridged networks" is surely much smaller.
+
+A few other **major components and changes** landed in 2023:
+
+*   (2023-02-10) The [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool (successor to [Mjolnir](https://github.com/matrix-org/mjolnir)), thanks to a PR by [FSG-Cat](https://github.com/FSG-Cat) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#draupnir-moderation-tool-bot-support))
+*   (2023-02-10) [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) to add Matrix Authentication Support to our Jitsi setup, thanks to a PR by [Jakob S.](https://github.com/jakicoll) from [zakk gGmbH](https://github.com/zakk-it) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#matrix-authentication-support-for-jitsi))
+*   (2023-02-25) The [rageshake](https://github.com/matrix-org/rageshake) bug report server, thanks to a PR by [Benjamin Kampmann](https://github.com/gnunicorn) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#rageshake-support))
+*   (2023-03-07) [Sliding Sync proxy](https://github.com/matrix-org/sliding-sync) (currently a necessary component for [Element X](https://element.io/labs/element-x) to work), thanks to: [Benjamin Kampmann](https://github.com/gnunicorn) and [FSG-Cat](https://github.com/FSG-Cat) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#sliding-sync-proxy-element-x-support))
+*   (2023-03-12) synapse-auto-compressor to periodically and automatically run [rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state), thanks to a PR by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#synapse-auto-compressor-support))
+*   (2023-07-17) [matrix-media-repo](https://github.com/turt2live/matrix-media-repo),  thanks to a PR by [Michael Hollister](https://github.com/Michael-Hollister) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#matrix-media-repo-support))
+*   (2023-08-31) [SchildiChat Web](https://github.com/SchildiChat/schildichat-desktop) client app (fork of [Element Web)](https://github.com/element-hq/element-web), thanks to a PR by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#schildichat-support))
+*   (2023-10-18) Postgres parameters auto-tuning, thanks to a PR by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/) (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#postgres-parameters-are-automatically-tuned-now))
+*   (2023-10-23) Enabling federation of the room directory for Synapse (see the [changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#enabling-allow_public_rooms_over_federation-by-default-for-synapse))
+
+The most recent change in the list above (Enabling federation of the room directory for Synapse) has been somewhat **controversial** as it goes against upstream defaults for Synapse. Nevertheless, we believe it **promotes the well-being of the Matrix Federation by improving room discovery**.
+
+**Matrix Federation Stats** (containing the percentage of servers publishing their room directory publicly) are posted to [TWIM](https://matrix.org/category/this-week-in-matrix/) each week by [Aine](https://gitlab.com/etke.cc) from [etke.cc](https://etke.cc/). The number of servers which [currently published their room directory publicly](https://matrix.org/blog/2023/12/2/this-week-in-matrix-2023-12-22/#matrix-federation-stats) stands at `26.6%`, which is:
+
+- **2.4% more** than when it was when [first published to TWIM](https://matrix.org/blog/2023/11/03/this-week-in-matrix-2023-11-03/#matrix-federation-stats) (1 month earlier, in November)
+- likely about **15+% more** than from before we flipped the switch (in October)
+
+Hopefully, Synapse defaults would also change the same way and we'd see the number of servers publicly listing their room directory grow faster.
+
+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.
+
+[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.
+
+Besides these highlights, there were many other relatively large changes announced in our [CHANGELOG](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md) and hundreds of other more minor (but still important) playbook changes that didn't get a mention.
+
+We have **hundreds of contributors to thank for their hard work** on making Matrix self-hosting better for all of us! It should be noted that **support comes in many shapes**, not only in raw code commits and financial help (via [donations](https://liberapay.com/s.pantaleev) or using the [etke.cc managed Matrix hosting service](https://etke.cc/) which is based on matrix-docker-ansible-deploy). It also comes in the shape of code reviews, helping others with [issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues), reporting new issues, participating in our support room on Matrix ([#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)), etc. To everyone who has been there to make matrix-docker-ansible-deploy better in 2023, thank you! 🙇‍♂️
+
+
+# 2022
+
+For [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy/), 2022 started with **breaking the** [**Synapse**](https://github.com/element-hq/synapse) **monopoly** by [adding support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#dendrite-support) for the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver in early January. This required various internal changes so that the [Ansible](https://www.ansible.com/) playbook would not be Synapse-centric anymore. This groundwork paved the way for continuing in this direction and we [added support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#conduit-support) for [Conduit](https://conduit.rs/) in August.
+
+When it comes to the `matrix-docker-ansible-deploy` Ansible playbook, 2022 was the year of the non-Synapse homeserver implementation. In practice, none of these homeserver implementations seem ready for prime-time yet and there is no migration path when coming from Synapse. Having done our job of adding support for these alternative homeserver implementations, we can say that we're not getting in the way of future progress. It's time for the Dendrite developers to push harder (development-wise) and for the Synapse developers to take a well-deserved long (infinite) break, and we may get to see more people migrating away from Synapse in the next year(s).
+
+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
+*   [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)
+
+Support for the following new **bots** was added:
+
+*   [buscarron bot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#buscarron-bot-support)
+*   [Honoroit bot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#honoroit-bot-support)
+*   [matrix-registration-bot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-registration-bot-support)
+*   [matrix-hookshot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-hookshot-bridging-support)
+*   [maubot](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#maubot-support)
+
+Support for the following new **components and services** was added:
+
+*   [BorgBackup](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#borg-backup-support)
+*   [Cactus Comments](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#cactus-comments-support)
+*   [Cinny](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#cinny-support) client support
+*   [ntfy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#ntfy-push-notifications-support) notifications
+*   [matrix-ldap-registration-proxy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix-ldap-registration-proxy-support)
+*   [matrix\_encryption\_disabler support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#matrix_encryption_disabler-support)
+*   [synapse-s3-storage-provider](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#synapse-s3-storage-provider-support) to stop the Synapse media store from being a scalability problem. This brought along [another feature](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#synapse-container-image-customization-support) - an easier way to customize the Synapse container image without having to fork and self-build all of it from scratch
+
+Besides these major user-visible changes, a lot of work also happened **under the hood**:
+
+*   we made [major improvements to Synapse workers](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#potential-backward-compatibility-break-major-improvements-to-synapse-workers) - adding support for stream writers and for running multiple workers of various kinds (federation senders, pushers, background task processing workers, etc.)
+*   we [improved the compatibility of (Synapse + workers) with the rest of the playbook](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#backward-compatibility-break-changing-how-reverse-proxying-to-synapse-works---now-via-a-matrix-synapse-reverse-proxy-companion-service) by introducing a new `matrix-synapse-reverse-proxy-companion-service` service
+*   we started [splitting various Ansible roles out of the Matrix playbook and into independent roles](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#the-playbook-now-uses-external-roles-for-some-things) (e.g. `matrix-postgres` -> [ansible-role-postgres](https://github.com/mother-of-all-self-hosting/ansible-role-postgres)), which could be included in other Ansible playbooks. In fact, these roles already power a few **interesting other sibling playbooks**:
+    *   [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy), for deploying a [Gitea](https://gitea.io/) (self-hosted [Git](https://git-scm.com/) service) server
+    *   [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy), for deploying a [Nextcloud](https://nextcloud.com/) groupware server
+    *   [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy), for deploying a [Vaultwarden](https://github.com/dani-garcia/vaultwarden) password manager server (unofficial [Bitwarden](https://bitwarden.com/) compatible server)
+
+These sibling playbooks co-exist nicely with one another due to using [Traefik](https://traefik.io/) for reverse-proxying, instead of trying to overtake the whole server by running their own [nginx](https://nginx.org/) reverse-proxy. Hopefully soon, the Matrix playbook will follow suit and be powered by Traefik by default.
+
+Last, but not least, to optimize our [etke.cc managed Matrix hosting service](https://etke.cc/)'s performance (but also individual Ansible playbook runs for people self-hosting by themselves using the playbook), we've [improved playbook runtime 2-5x](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) by employing various Ansible tricks.

bin/ansible-all-hosts.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# 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
+# to this script as arguments, e.g.
+#
+#     ./bin/ansible-all-hosts.sh self-check
+#
+
+# set playbook root path
+root=$(dirname "$(readlink -f "$0")")/..
+
+# set default tags or get from first argument if any
+tags="${1:-setup-all,start}"
+
+# init password array
+declare -A pws
+
+# capture passwords for all hosts
+for host in "$root"/inventory/*.yml; do
+    read -rp "sudo password for $(basename "$host"): " -s pw
+    pws[$host]="$pw"
+    echo
+done
+
+# run ansible on all captured passwords/hosts
+for host in "${!pws[@]}"; do
+    ansible-playbook "$root"/setup.yml \
+        --inventory-file "$host" \
+        --extra-vars "ansible_become_pass=${pws[$host]}" \
+        --tags="$tags"
+done

bin/rebuild-mautrix-meta-instagram.sh

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

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,39 +1,84 @@
 # Table of Contents
 
-- [FAQ](faq.md) - lots of questions and answers. Jump to [Prerequisites](prerequisites.md) to avoid reading too much and to just start a guided installation.
+## ⬇️ Installaton guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->
 
-- [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook
+There are two installation guides available for beginners and advanced users.
 
-- [Configuring your DNS server](configuring-dns.md)
+- ⚡ **[Quick start](quick-start.md) (for beginners)**: this is recommended for those who do not have an existing Matrix server and want to start quickly with "opinionated defaults".
 
-- [Getting this playbook's source code](getting-the-playbook.md)
+- **Full installation guide (for advanced users)**: if you need to import an existing Matrix server's data into the new server or want to learn more while setting up the server, follow this guide.
 
-- [Configuring the playbook](configuring-playbook.md)
+    - [Prerequisites](prerequisites.md)
 
-- [Installing](installing.md)
+    - [Configuring your DNS settings](configuring-dns.md)
 
-- **Importing data from another server installation**
+    - [Getting the playbook](getting-the-playbook.md)
 
-  - [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)
+    - [Configuring the playbook](configuring-playbook.md)
 
-  - [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)
+    - [Installing](installing.md)
 
-  - [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
+## 🛠️ Configuration options
 
-- [Registering users](registering-users.md)
+<!--
+NOTE:
+- Avoid putting the same anchor links as configuring-playbook.md lists under the "configuration options" section. Note that most of them are linked to "configure-playbook-*.md" and their titles start with "Setting up" (e.g. "Setting up Hydrogen").
+-->
 
-- [Updating users passwords](updating-users-passwords.md)
+You can check useful documentation for configuring components here: [Configuring the playbook](configuring-playbook.md)
 
-- [Configuring service discovery via .well-known](configuring-well-known.md)
+- [Administration](configuring-playbook.md#administration) — services that help you in administrating and monitoring your Matrix installation
 
-- [Maintenance / checking if services work](maintenance-checking-services.md)
+- [Authentication and user-related](configuring-playbook.md#authentication-and-user-related) — extend and modify how users are authenticated on your homeserver
 
-- [Maintenance / upgrading services](maintenance-upgrading-services.md)
+- [Bots](configuring-playbook.md#bots) — bots provide various additional functionality to your installation
 
-- [Maintenance / Synapse](maintenance-synapse.md)
+- [Bridges](configuring-playbook.md#bridging-other-networks) — bridges can be used to connect your Matrix installation with third-party communication networks
 
-- [Maintenance / PostgreSQL](maintenance-postgres.md)
+- [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
+
+- [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
+
+## 👨‍🔧 Maintenance
+
+If your server and services experience issues, feel free to come to [our support room](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) and ask for help.
+
+<!-- NOTE: sort list items alphabetically -->
 
 - [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
 
+- [PostgreSQL maintenance](maintenance-postgres.md)
+
+- [Synapse maintenance](maintenance-synapse.md)
+
+- [Upgrading services](maintenance-upgrading-services.md)
+
+## 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
+
+<!-- NOTE: sort list items under faq.md alphabetically -->
+
+- [Alternative architectures](alternative-architectures.md)
+
+- [Container images used by the playbook](container-images.md)
+
+- [Obtaining an Access Token](obtaining-access-tokens.md)
+
+- [Playbook tags](playbook-tags.md)
+
+- [Registering users](registering-users.md)
+
+- [Running `just` commands](just.md)
+
+- [Self-building](self-building.md)
+
 - [Uninstalling](uninstalling.md)
+
+- [Updating users passwords](updating-users-passwords.md)

docs/alternative-architectures.md

@@ -1,26 +1,17 @@
 # Alternative architectures
 
-As stated in the [Prerequisites](prerequisites.md), currently only `x86_64` is fully supported. However, it is possible to set the target architecture, and some tools can be built on the host or other measures can be used.
+As stated in the [Prerequisites](prerequisites.md), currently only `amd64` (`x86_64`) is fully supported.
 
-To that end add the following variable to your `vars.yml` file (see [Configuring playbook](configuring-playbook.md)):
+The playbook automatically determines the target server's architecture (the `matrix_architecture` variable) to be one of the following:
 
-```yaml
-matrix_architecture: <your-matrix-server-architecture>
-```
-
-Currently supported architectures are the following:
-- `amd64` (the default)
-- `arm64`
+- `amd64` (`x86_64`)
 - `arm32`
+- `arm64`
 
-so for the Raspberry Pi, the following should be in your `vars.yml` file:
-
-```yaml
-matrix_architecture: "arm32"
-```
+Some tools and container images can be built on the host or other measures can be used to install on that architecture.
 
 ## Implementation details
 
 For `amd64`, prebuilt container images (see the [container images we use](container-images.md)) are used for all components (except [Hydrogen](configuring-playbook-client-hydrogen.md), which goes through self-building).
 
-For other architectures, components which have a prebuilt image make use of it. If the component is not available for the specific architecture, [self-building](self-building.md) will be used. Not all components support self-building though, so your mileage may vary.
+For other architecture (`arm64`, `arm32`), components which have a prebuilt image make use of it. If the component is not available for the specific architecture, [self-building](self-building.md) will be used. Not all components support self-building though, so your mileage may vary.

docs/ansible.md

@@ -3,26 +3,17 @@
 
 This playbook is meant to be run using [Ansible](https://www.ansible.com/).
 
-Ansible typically runs on your local computer and carries out tasks on a remote server.
-If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
-
+Ansible typically runs on your local computer and carries out tasks on a remote server. If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
 
 ## Supported Ansible versions
 
-Ansible 2.7.1 or newer is required ([last discussion about Ansible versions](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/743)).
-
-Note: Ubuntu 20.04 ships with Ansible 2.9.6 which is a buggy version (see this [bug](https://bugs.launchpad.net/ubuntu/+source/ansible/+bug/1880359)), which can't be used in combination with a host running new systemd (more details in [#517](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/517), [#669](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/669)). If this problem affects you, you can: avoid running Ubuntu 20.04 on your host; run Ansible from another machine targeting your host; or try to upgrade to a newer Ansible version (see below).
-
-
-## Checking your Ansible version
-
-In most cases, you won't need to worry about the Ansible version.
-The playbook will try to detect it and tell you if you're on an unsupported version.
-
 To manually check which version of Ansible you're on, run: `ansible --version`.
 
-If you're on an old version of Ansible, you should [upgrade Ansible to a newer version](#upgrading-ansible) or [use Ansible via Docker](#using-ansible-via-docker).
+For the **best experience**, we recommend getting the **latest version of Ansible available**.
 
+We're not sure what's the minimum version of Ansible that can run this playbook successfully. The lowest version that we've confirmed (on 2022-11-26) to be working fine is: `ansible-core` (`2.11.7`) combined with `ansible` (`4.10.0`).
+
+If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
 
 ## Upgrading Ansible
 
@@ -30,44 +21,93 @@ Depending on your distribution, you may be able to upgrade Ansible in a few diff
 
 - by using an additional repository (PPA, etc.), which provides newer Ansible versions. See instructions for [CentOS](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-rhel-centos-or-fedora), [Debian](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-debian), or [Ubuntu](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-ubuntu) on the Ansible website.
 
-- by removing the Ansible package (`yum remove ansible` or `apt-get remove ansible`) and installing via [pip](https://pip.pypa.io/en/stable/installing/) (`pip install ansible`).
+- by removing the Ansible package (`yum remove ansible` or `apt-get remove ansible`) and installing via [pip](https://pip.pypa.io/en/stable/installation/) (`pip install ansible`).
 
 If using the `pip` method, do note that the `ansible-playbook` binary may not be on the `$PATH` (https://linuxconfig.org/linux-path-environment-variable), but in some more special location like `/usr/local/bin/ansible-playbook`. You may need to invoke it using the full path.
 
-
-**Note**: Both of the above methods are a bad way to run system software such as Ansible.
-If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
-
+**Note**: Both of the above methods are a bad way to run system software such as Ansible. If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
 
 ## Using Ansible via Docker
 
-Alternatively, you can run Ansible on your computer from 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 [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
 
-Here's a sample command to get you started (run this from the playbook's directory):
+This ensures that:
 
-```bash
+- 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).
+
+### Running Ansible in a container on the Matrix server itself
+
+To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation. Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
+
+- 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).
+
+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 …`
+
+Run this from the playbook's directory:
+
+```sh
+docker run -it --rm \
+--privileged \
+--pid=host \
+-w /work \
+-v `pwd`:/work \
+--entrypoint=/bin/sh \
+docker.io/devture/ansible:2.18.1-r0-2
+```
+
+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.
+
+### Running Ansible in a container on another computer (not the Matrix server)
+
+Run this from the playbook's directory:
+
+```sh
 docker run -it --rm \
 -w /work \
 -v `pwd`:/work \
 -v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
 --entrypoint=/bin/sh \
-docker.io/devture/ansible:2.11.6-r1
+docker.io/devture/ansible:2.18.1-r0-2
 ```
 
-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_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.
 
-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.
+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.
 
-You can execute `ansible-playbook` commands as per normal now.
+First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
 
-### If you don't use SSH keys for authentication
+Finally, you execute `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`).
-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:
-```bash
+
+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:
+
+```sh
 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.
 
+#### 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:
+
+> fatal: unsafe repository ('/work' is owned by someone else)
+> To add an exception for this directory, call:
+>  git config --global --add safe.directory /work
+
+These errors can be resolved by making `git` trust the playbook directory by running `git config --global --add safe.directory /work`

docs/configuring-captcha.md

@@ -1,10 +1,14 @@
-(Adapted from the [upstream project](https://github.com/matrix-org/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
+(Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
 
 # Overview
-Captcha can be enabled for this home server. This file explains how to do that.
-The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google.
 
-## Getting keys
+Captcha can be enabled for this home server. This file explains how to do that.
+
+The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.
+
+## ReCaptcha
+
+### Getting keys
 
 Requires a site/secret key pair from:
 
@@ -12,12 +16,39 @@ Requires a site/secret key pair from:
 
 Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option
 
-## Setting ReCaptcha Keys
+### Setting ReCaptcha keys
 
-Once registered as above, set the following values:
+Once registered as above, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
+# for Synapse
 matrix_synapse_enable_registration_captcha: true
 matrix_synapse_recaptcha_public_key: 'YOUR_SITE_KEY'
 matrix_synapse_recaptcha_private_key: 'YOUR_SECRET_KEY'
+
+# for Dendrite
+matrix_dendrite_client_api_enable_registration_captcha: true
+matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
+matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
+```
+
+## hCaptcha
+
+### Getting keys
+
+Requires a site/secret key pair from:
+
+<https://dashboard.hcaptcha.com/sites/new>
+
+### Setting hCaptcha keys
+
+```yaml
+matrix_dendrite_client_api_enable_registration_captcha: true
+matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
+matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
+
+matrix_dendrite_client_api_recaptcha_siteverify_api: 'https://hcaptcha.com/siteverify'
+matrix_dendrite_client_api_recaptcha_api_js_url: 'https://js.hcaptcha.com/1/api.js'
+matrix_dendrite_client_api_recaptcha_form_field: 'h-captcha-response'
+matrix_dendrite_client_api_recaptcha_sitekey_class: 'h-captcha'
 ```

docs/configuring-dns.md

@@ -1,76 +1,43 @@
-# Configuring your DNS server
+# Configuring your DNS settings
+
+<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>
 
 To set up Matrix on your domain, you'd need to do some DNS configuration.
 
-To use an identifier like `@<username>:<your-domain>`, you don't actually need
-to install anything on the actual `<your-domain>` server.
-
-You do, however need to instruct the Matrix network that Matrix services for `<your-domain>` are delegated
-over to `matrix.<your-domain>`.
-As we discuss in [Server Delegation](howto-server-delegation.md), there are 2 different ways to set up such delegation:
-
-- either by serving a `https://<your-domain>/.well-known/matrix/server` file (from the base domain!)
-- or by  using a `_matrix._tcp` DNS SRV record (don't confuse this with the `_matrix-identity._tcp` SRV record described below)
-
-This playbook mostly discusses the well-known file method, because it's easier to manage with regard to certificates.
-If you decide to go with the alternative method ([Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)), please be aware that the general flow that this playbook guides you through may not match what you need to do.
-
 ## DNS settings for services enabled by default
 
-| Type  | Host                         | Priority | Weight | Port | Target                 |
-| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
-| A     | `matrix`                     | -        | -      | -    | `matrix-server-IP`     |
-| CNAME | `element`                    | -        | -      | -    | `matrix.<your-domain>` |
+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.
+**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 settings for optional services/features
+## DNS setting for server delegation (optional)
 
-| Type  | Host                         | Priority | Weight | Port | Target                 |
-| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
-| SRV   | `_matrix-identity._tcp`      | 10       | 0      | 443  | `matrix.<your-domain>` |
-| CNAME | `dimension`                  | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `jitsi`                      | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `stats`                      | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `goneb`                      | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `sygnal`                     | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `hydrogen`                   | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `cinny`                      | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `buscarron`                  | -        | -      | -    | `matrix.<your-domain>` |
+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`.
 
-## Subdomains setup
+To use such an ID, you don't need to install anything on the actual `example.com` server. Instead, you need to instruct the Matrix network that Matrix services for `example.com` are redirected over to `matrix.example.com`. This redirection is also known as "delegation".
 
-As the table above illustrates, you need to create 2 subdomains (`matrix.<your-domain>` and `element.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
+As we discuss in [Server Delegation](howto-server-delegation.md), server delegation can be configured in either of these ways:
 
-The `element.<your-domain>` subdomain may be necessary, because this playbook installs the [Element](https://github.com/vector-im/element-web) web client for you.
-If you'd rather instruct the playbook not to install Element (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.<your-domain>` DNS record.
+- Setting up a `/.well-known/matrix/server` file on the base domain (`example.com`)
+- Setting up a `_matrix._tcp` DNS SRV record
 
-The `dimension.<your-domain>` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. Dimension installation is disabled by default, because it's only possible to install it after the other Matrix services are working (see [Setting up Dimension](configuring-playbook-dimension.md) later). If you do not wish to set up Dimension, feel free to skip the `dimension.<your-domain>` DNS record.
+For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file, instead of using a DNS SRV record.
 
-The `jitsi.<your-domain>` subdomain may be necessary, because this playbook could install the [Jitsi video-conferencing platform](https://jitsi.org/) for you. Jitsi installation is disabled by default, because it may be heavy and is not a core required component. To learn how to install it, see our [Jitsi](configuring-playbook-jitsi.md) guide. If you do not wish to set up Jitsi, feel free to skip the `jitsi.<your-domain>` DNS record.
+If you choose the recommended method (file-based delegation), you do not need to configure the DNS record to enable server delegation. You will need to add a necessary configuration later, when you [finalize the installation](installing.md#finalize-the-installation) after installing and starting Matrix services.
 
-The `stats.<your-domain>` subdomain may be necessary, because this playbook could install [Grafana](https://grafana.com/) and setup performance metrics for you. Grafana installation is disabled by default, it is not a core required component. To learn how to install it, see our [metrics and graphs guide](configuring-playbook-prometheus-grafana.md). If you do not wish to set up Grafana, feel free to skip the `stats.<your-domain>` DNS record. It is possible to install Prometheus without installing Grafana, this would also not require the `stats.<your-domain>` subdomain.
+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)
 
-The `goneb.<your-domain>` subdomain may be necessary, because this playbook could install the [Go-NEB](https://github.com/matrix-org/go-neb) bot. The installation of Go-NEB is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Go-NEB guide](configuring-playbook-bot-go-neb.md). If you do not wish to set up Go-NEB, feel free to skip the `goneb.<your-domain>` DNS record.
+---------------------------------------------
 
-The `sygnal.<your-domain>` subdomain may be necessary, because this playbook could install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway. The installation of Sygnal is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Sygnal guide](configuring-playbook-sygnal.md). If you do not wish to set up Sygnal (you probably don't, unless you're also developing/building your own Matrix apps), feel free to skip the `sygnal.<your-domain>` DNS record.
-
-The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.<your-domain>` DNS record.
-
-The `cinny.<your-domain>` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up cinny, feel free to skip the `cinny.<your-domain>` DNS record.
-
-The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etke.cc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.<your-domain>` DNS record.
-
-## `_matrix-identity._tcp` SRV record setup
-
-To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook may optionally install for you) enable its federation features, set up an SRV record that looks like this:
-- Name: `_matrix-identity._tcp` (use this text as-is)
-- Content: `10 0 443 matrix.<your-domain>` (replace `<your-domain>` with your own)
-
-This is an optional feature for the optionally-installed [ma1sd service](configuring-playbook-ma1sd.md). See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
-
-Note: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
-
-When you're done with the DNS configuration and ready to proceed, continue with [Getting the playbook](getting-the-playbook.md).
+[▶️](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-playbook-alertmanager-receiver.md

@@ -0,0 +1,145 @@
+# 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.
+
+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
+
+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
+
+# 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"
+
+matrix_alertmanager_receiver_config_matrix_access_token: "ACCESS_TOKEN_HERE"
+
+# Optionally, configure some mappings (URL-friendly room name -> actual Matrix room ID).
+#
+# If you don't configure mappings, you can still deliver alerts using URLs like this:
+# https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!qporfwt:example.com
+#
+# If a mapping like the one below is configured, you can deliver alerts using friendlier URLs like this:
+# https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name
+matrix_alertmanager_receiver_config_matrix_room_mapping:
+  some-room-name: "!qporfwt:{{ matrix_domain }}"
+```
+
+### Adjusting the matrix-alertmanager-receiver URL (optional)
+
+By tweaking the `matrix_alertmanager_receiver_hostname` and `matrix_alertmanager_receiver_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_alertmanager_receiver_hostname: alertmanager.example.com
+matrix_alertmanager_receiver_path_prefix: /
+```
+
+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`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-alertmanager-receiver/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-alertmanager-receiver/templates/config.yaml.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_alertmanager_receiver_configuration_extension_yaml` variable
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**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
+
+Configure your Prometheus Alertmanager with configuration like this:
+
+```yaml
+receivers:
+  - name: matrix
+    webhook_configs:
+      - send_resolved: true
+        url: URL_HERE
+route:
+  group_by:
+    - namespace
+  group_interval: 5m
+  group_wait: 30s
+  receiver: "matrix"
+  repeat_interval: 12h
+  routes:
+    - 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`.
+
+## 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

@@ -0,0 +1,44 @@
+# Setting up Appservice Double Puppet (optional)
+
+The playbook can install and configure the Appservice Double Puppet service for you. It is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
+
+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 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
+
+To enable the Appservice Double Puppet service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+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
+```
+
+**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
+
+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

@@ -0,0 +1,107 @@
+# 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.
+
+Appservice mode can be used together with the regular [Draupnir bot](configuring-playbook-bot-draupnir.md) or independently. Details about the differences between the 2 modes are described below.
+
+## Draupnir Appservice mode compared to Draupnir bot mode
+
+The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
+
+Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All (Even though the commands do show up in help).
+
+Draupnir for all in the playbook is rate-limit-exempt automatically as its appservice configuration file does not specify any rate limits.
+
+Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as D4A even on the branch with the Avatar command (To be Upstreamed to Mainline Draupnir) that command is clunky as it requires the use of things like Element Web devtools. In normal Draupnir this is a quick operation where you login to Draupnir with a normal client and set Avatar and Display name normally.
+
+Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
+
+## Prerequisites
+
+### Create a main management room
+
+The playbook does not create a management room for your Main Draupnir. You **need to create the room manually** before setting up the bot.
+
+Note that the room must be unencrypted.
+
+The management room has to be given an alias, and your bot has to be invited to the room.
+
+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.
+
+> [!WARNING]
+> Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE`.
+
+```yaml
+matrix_appservice_draupnir_for_all_enabled: true
+
+matrix_appservice_draupnir_for_all_master_control_room_alias: "MANAGEMENT_ROOM_ALIAS_HERE"
+```
+
+### 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,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
+
+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.
+
+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.
+
+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 !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
+
+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.

docs/configuring-playbook-backup-borg.md

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

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

@@ -1,52 +1,76 @@
-# Serving the base domain
+# Serving the base domain (optional)
 
-This playbook sets up services on your Matrix server (`matrix.DOMAIN`).
-To have this server officially be responsible for Matrix services for the base domain (`DOMAIN`), you need to set up [Server Delegation](howto-server-delegation.md).
-This is normally done by [configuring well-known](configuring-well-known.md) files on the base domain.
+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.
 
-People who don't have a separate server to dedicate to the base domain have trouble arranging this.
+As we discuss in [Server Delegation](howto-server-delegation.md), server delegation / redirection can be configured in either of these ways:
+
+- Setting up a `/.well-known/matrix/server` file on the base domain (`example.com`)
+- Setting up a `_matrix._tcp` DNS SRV record
+
+For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file.
+
+However, those who don't have a separate server to dedicate to the base domain have trouble arranging this.
 
 Usually, there are 2 options:
 
 - either get a separate server for the base domain, just for serving the files necessary for [Server Delegation via a well-known file](howto-server-delegation.md#server-delegation-via-a-well-known-file)
 
-- or, arrange for the Matrix server to serve the base domain. This either involves you [using your own webserver](configuring-playbook-own-webserver.md) or making the integrated webserver (`matrix-nginx-proxy`) serve the base domain for you.
+- or, arrange for the Matrix server to serve the base domain. This either involves you [using your own webserver](configuring-playbook-own-webserver.md) or making the integrated webserver serve the base domain for you.
 
-This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver (`matrix-nginx-proxy`).
+This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver.
 
-Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then use the following configuration**:
+Just [**adjust your DNS records**](configuring-dns.md), so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then add the following configuration** to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_nginx_proxy_base_domain_serving_enabled: true
+matrix_static_files_container_labels_base_domain_enabled: true
 ```
 
 Doing this, the playbook will:
 
 - obtain an SSL certificate for the base domain, just like it does for all other domains (see [how we handle SSL certificates](configuring-playbook-ssl-certificates.md))
 
-- serve the `/.well-known/matrix/*` files which are necessary for [Federation Server Discovery](configuring-well-known.md#introduction-to-client-server-discovery) (also see [Server Delegation](howto-server-delegation.md)) and [Client-Server discovery](configuring-well-known.md#introduction-to-client-server-discovery)
-
-- serve a simple homepage at `https://DOMAIN` with content `Hello from DOMAIN` (configurable via the `matrix_nginx_proxy_base_domain_homepage_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain).
+- serve the `/.well-known/matrix/*` files which are necessary for [Federation Server Discovery](configuring-well-known.md#federation-server-discovery) (also see [Server Delegation](howto-server-delegation.md)) and [Client-Server discovery](configuring-well-known.md#client-server-discovery)
 
+- serve a simple homepage at `https://example.com` with content `Hello from example.com` (configurable via the `matrix_static_files_file_index_html_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain).
 
 ## Serving a static website at the base domain
 
-By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage in `/matrix/nginx-proxy/data/matrix-domain`.
-The content of this page is taken from the `matrix_nginx_proxy_base_domain_homepage_template` variable.
+By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage at `/matrix/static-files/public/index.html`. The content of this page is taken from the `matrix_static_files_file_index_html_template` variable.
 
 If you'd like to host your own static website (more than a single `index.html` page) at the base domain, you can disable the creation of this default `index.html` page like this:
 
 ```yaml
-matrix_nginx_proxy_base_domain_homepage_enabled: false
+# Enable base-domain serving
+matrix_static_files_container_labels_base_domain_enabled: true
+
+# Prevent the default index.html file from being installed
+matrix_static_files_file_index_html_enabled: false
+
+# Disable the automatic redirectin of `https://example.com/` to `https://matrix.example.com/`.
+# This gets automatically enabled when you disable `matrix_static_files_file_index_html_enabled`, as we're doing above.
+matrix_static_files_container_labels_base_domain_root_path_redirection_enabled: false
 ```
 
-With this configuration, Ansible will no longer mess around with the `/matrix/nginx-proxy/data/matrix-domain/index.html` file.
-
-You are then free to upload any static website files to `/matrix/nginx-proxy/data/matrix-domain` and they will get served at the base domain.
+With this configuration, Ansible will no longer mess around with the `/matrix/static-files/public/index.html` file.
 
+You are then free to upload any static website files to `/matrix/static-files/public` and they will get served at the base domain. You can do so manually or by using the [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role, which is part of this playbook already.
 
 ## Serving a more complicated website at the base domain
 
 If you'd like to serve an even more complicated (dynamic) website from the Matrix server, relying on the playbook to serve the base domain is not the best choice.
 
-Instead, we recommend that you switch to [using your own webserver](configuring-playbook-own-webserver.md) (preferrably nginx). You can then make that webserver host anything you wish, and still easily plug in Matrix services into it.
+You have 2 options.
+
+**One way is to host your base domain elsewhere**. This involves:
+- you stopping to serve it from the Matrix server: remove `matrix_static_files_container_labels_base_domain_enabled` from your configuration
+- [configuring Matrix Delegation via well-known](./configuring-well-known.md)
+
+**Another way is to serve the base domain from another (your own) container on the Matrix server**. This involves:
+- telling the playbook to only serve `example.com/.well-known/matrix` files by adjusting your `vars.yml` configuration like this:
+  - keep `matrix_static_files_container_labels_base_domain_enabled: true`
+  - add an extra: `matrix_static_files_container_labels_base_domain_traefik_path_prefix: /.well-known/matrix`
+- building and running a new container on the Matrix server:
+  - it should be connected to the `traefik` network, so that Traefik can reverse-proxy to it
+  - it should have appropriate [container labels](https://docs.docker.com/config/labels-custom-metadata/), which instruct Traefik to reverse-proxy to it
+
+How you'll be managing building and running this container is up-to-you. You may use of the primitives from [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role to organize it yourself, or you can set it up in another way.

docs/configuring-playbook-bot-baibot.md

@@ -0,0 +1,423 @@
+# Setting up baibot (optional)
+
+<p align="center">
+	<img src="https://github.com/etkecc/baibot/raw/main/etc/assets/baibot.svg" alt="baibot logo" width="150" />
+	<h1 align="center">baibot</h1>
+</p>
+
+🤖 [baibot](https://github.com/etkecc/baibot) (pronounced bye-bot) is a [Matrix](https://matrix.org/) bot developed by [etke.cc](https://etke.cc/) that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you. 🤖
+
+It supports [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/chatgpt/) models, as many well as other [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
+
+It's designed as a more private and [✨ featureful](https://github.com/etkecc/baibot/?tab=readme-ov-file#-features) alternative to [matrix-chatgpt-bot](./configuring-playbook-bot-chatgpt.md). See the [baibot](https://github.com/etkecc/baibot) project and its documentation for more information.
+
+## Prerequisites
+
+API access to one or more LLM [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
+
+## Adjusting the playbook configuration
+
+There are **a lot of configuration options** (some required, some possibly required, some optional), so they're **split into multiple sections below**:
+
+<!-- no toc -->
+- [Base configuration](#base-configuration)
+- [👮‍♂️ Administrator configuration](#️-administrator-configuration)
+- [👥 Initial users configuration](#-initial-users-configuration)
+- [🤖 Configuring agents via Ansible](#-configuring-agents-via-ansible)
+- [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers)
+
+Depending on your current `vars.yml` file and desired configuration, **you may require more than just the [base configuration](#base-configuration)**.
+
+### Base configuration
+
+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
+
+# 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 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 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.
+# It's highly recommended that you configure this to avoid losing access to encrypted messages.
+#
+# Changing this subsequently will also cause you to lose access to old messages in encrypted rooms.
+# For details about changing this subsequently or resetting, see `defaults/main.yml` in the baibot role.
+matrix_bot_baibot_config_user_encryption_recovery_passphrase: 'ANY_LONG_AND_SECURE_PASSPHRASE_STRING_HERE'
+
+# An optional secret for encrypting the bot's session data (see `matrix_bot_baibot_data_path`).
+# This must be 32-bytes (64 characters when HEX-encoded).
+# Generate it with: `openssl rand -hex 32`
+# Set to null or empty to avoid using encryption.
+# Changing this subsequently requires that you also throw away all data (see `matrix_bot_baibot_data_path`)
+matrix_bot_baibot_config_persistence_session_encryption_key: 'A_HEX_STRING_OF_64_CHARACTERS_HERE'
+
+# An optional secret for encrypting bot configuration stored in Matrix's account data.
+# This must be 32-bytes (64 characters when HEX-encoded).
+# Generate it with: `openssl rand -hex 32`
+# Set to null or empty to avoid using encryption.
+# Changing this subsequently will make you lose your configuration.
+matrix_bot_baibot_config_persistence_config_encryption_key: 'A_HEX_STRING_OF_64_CHARACTERS_HERE'
+```
+
+As mentioned above, **this may not be enough**. Continue with the configuration sections below.
+
+### 👮‍♂️ Administrator configuration
+
+This is an addition to the [base configuration](#base-configuration).
+
+To specify who is considered a bot [👮‍♂️ Administrator](https://github.com/etkecc/baibot/blob/main/docs/access.md#administrators), you either need to specify `matrix_bot_baibot_config_access_admin_patterns` or `matrix_admin`. The latter is a single variable which affects all bridges and bots.
+
+If `matrix_admin` is already configured in your `vars.yml` configuration, you can skip this section.
+
+**If necessary**, add the following configuration to your `vars.yml` file:
+
+```yaml
+# Uncomment to add one or more admins to this bridge:
+#
+# matrix_bot_baibot_config_access_admin_patterns:
+#   - "@*:example.com"
+#   - "@admin:example.net"
+#
+# … unless you've made yourself an admin of all bots/bridges like this:
+#
+# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
+```
+
+### 👥 Initial users configuration
+
+By default, **all users on your homeserver are considered allowed users**. If that's OK, you can skip this section.
+
+This is an addition to the [base configuration](#base-configuration).
+
+To specify who is considered a bot [👥 User](https://github.com/etkecc/baibot/blob/main/docs/access.md#user), you may:
+
+- define an **initial** value for `matrix_bot_baibot_config_initial_global_config_user_patterns` Ansible variable, as shown below
+- configure the list at runtime via the bot's `!bai access set-users SPACE_SEPARATED_PATTERNS` command
+
+Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is optional, but it can be useful to pre-configure the bot with a list of users who should have access to the bot's features.
+
+**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 `vars.yml` file:
+
+```yaml
+# Uncomment and adjust the bot users if necessary:
+#
+# Subsequent changes to `matrix_bot_baibot_config_initial_global_config_user_patterns` do not affect the bot's behavior.
+# Once initially configured, the allowed users list is managed via bot commands, not via Ansible.
+#
+# matrix_bot_baibot_config_initial_global_config_user_patterns:
+#   - "@*:{{ matrix_bot_baibot_config_homeserver_server_name }}"
+```
+
+### 🤖 Configuring agents via Ansible
+
+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.
+
+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).
+
+Besides the presets, the Ansible role also includes support for configuring additional statically-defined agents via the `matrix_bot_baibot_config_agents_static_definitions_custom` Ansible variable.
+
+Agents defined statically and those created dynamically (via chat) are named differently, so **conflict cannot arise**.
+
+Depending on your propensity for [GitOps](https://en.wikipedia.org/wiki/DevOps#GitOps), you may prefer to define agents statically via Ansible, or you may wish to do it dynamically via chat.
+
+Before proceeding, we recommend reading the upstream documentation on [How to choose a provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#how-to-choose-a-provider). In short, it's probably best to go with [OpenAI](#openai).
+
+#### Anthropic
+
+You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Anthropic provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#anthropic) with the help of the playbook's preset variables.
+
+Here's an example **addition** to your `vars.yml` file:
+
+```yaml
+matrix_bot_baibot_config_agents_static_definitions_anthropic_enabled: true
+
+matrix_bot_baibot_config_agents_static_definitions_anthropic_config_api_key: "YOUR_API_KEY_HERE"
+
+# 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 }}"
+```
+
+If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
+
+💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
+
+#### Groq
+
+You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Groq provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#groq) with the help of the playbook's preset variables.
+
+Here's an example **addition** to your `vars.yml` file:
+
+```yaml
+matrix_bot_baibot_config_agents_static_definitions_groq_enabled: true
+
+matrix_bot_baibot_config_agents_static_definitions_groq_config_api_key: "YOUR_API_KEY_HERE"
+
+# Specify the text-generation agent you'd like to use
+matrix_bot_baibot_config_agents_static_definitions_groq_config_text_generation_model_id: "llama3-70b-8192"
+
+# 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 Groq agent.
+# matrix_bot_baibot_config_agents_static_definitions_groq_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
+
+# Uncomment and adjust this part if you're not happy with these speech-to-text defaults:
+#
+# 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
+```
+
+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`.
+
+If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
+
+💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
+
+#### Mistral
+
+You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [🇫🇷 Mistral provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#mistral) with the help of the playbook's preset variables.
+
+Here's an example **addition** to your `vars.yml` file:
+
+```yaml
+matrix_bot_baibot_config_agents_static_definitions_mistral_enabled: true
+
+matrix_bot_baibot_config_agents_static_definitions_mistral_config_api_key: "YOUR_API_KEY_HERE"
+
+# 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 Mistral agent.
+# matrix_bot_baibot_config_agents_static_definitions_mistral_config_text_generation_prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
+
+# 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
+```
+
+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`.
+
+If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
+
+💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
+
+#### OpenAI
+
+You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai) with the help of the playbook's preset variables.
+
+The OpenAI provider is **only meant to be used with OpenAI's official API** and compatibility with other services (which do not fully adhere to the OpenAI API spec completely) is limited. **If you're targeting an OpenAI-compatible service**, use the [OpenAI Compatible](#openai-compatible) provider instead.
+
+Here's an example **addition** to your `vars.yml` file:
+
+```yaml
+matrix_bot_baibot_config_agents_static_definitions_openai_enabled: true
+
+matrix_bot_baibot_config_agents_static_definitions_openai_config_api_key: "YOUR_API_KEY_HERE"
+
+# 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 OpenAI agent.
+# 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
+```
+
+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`.
+
+If you'd like to use more than one model, take a look at the [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset) section below.
+
+💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
+
+#### OpenAI Compatible
+
+You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI Compatible provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai-compatible) with the help of the playbook's preset variables.
+
+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.
+
+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).
+
+#### Configuring additional agents (without a preset)
+
+The Ansible role may be lacking preset variables for some [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md), or you may wish to statically-define an agent on the same provider twice (or more) with different configuration.
+
+It's possible to inject your own agent configuration using the `matrix_bot_baibot_config_agents_static_definitions_custom` Ansible variable.
+
+You can also define providers at runtime, by chatting with the bot, so using Ansible is not a requirement.
+
+Below is an an **example** demonstrating **statically-defining agents via Ansible without using presets**:
+
+```yaml
+matrix_bot_baibot_config_agents_static_definitions_custom:
+  # This agent will use the GPT 3.5 model and will only support text-generation,
+  # even though the `openai` provider could support other features (e.g. image-generation).
+  - id: my-openai-gpt-3.5-turbo-agent
+    provider: openai
+    config:
+        base_url: https://api.openai.com/v1
+        api_key: "YOUR_API_KEY_HERE"
+        text_generation:
+          model_id: gpt-3.5-turbo-0125
+          prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
+          temperature: 1.0
+          max_response_tokens: 4096
+          max_context_tokens: 16385
+        speech_to_text: null
+        text_to_speech: null
+        image_generation: null
+
+  # This agent uses the `openai` provider, but adjusts the base URL, so that it points to some Ollama instance
+  # (which supports an OpenAI-compatible API).
+  - id: my-ollama-agent
+    provider: openai
+    config:
+      base_url: http://ollama-service:1234/v1
+      api_key: ""
+      text_generation:
+        model_id: "llama3.1:8b"
+        prompt: "{{ matrix_bot_baibot_config_agents_static_definitions_prompt }}"
+        temperature: 1.0
+        max_response_tokens: 4096
+        max_context_tokens: 128000
+          speech_to_text: null
+          text_to_speech: null
+          image_generation: null
+```
+
+Because these are [statically](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md#static-configuration)-defined agents, they will be given a `static/` ID prefix and will be named `static/my-openai-gpt-3.5-turbo-agent` and `static/my-ollama-agent`, respectively.
+
+💡 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).
+
+💡 You may also wish to use these new agents for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
+
+### 🤝 Configuring initial default handlers
+
+This section is only useful if you're [🤖 Configuring agents via Ansible](#-configuring-agents-via-ansible), as it lets you put these agents to use as soon as the bot starts (by adjusting the bot's **initial global configuration**).
+
+If you're not configuring agents via Ansible, you can skip this section.
+
+This section is only useful the first time around. **Once initially configured the global configuration cannot be managed Ansible**, but only via bot commands.
+
+baibot supports [various purposes](https://github.com/etkecc/baibot/blob/main/docs/features.md):
+
+- [💬 text-generation](https://github.com/etkecc/baibot/blob/main/docs/features.md#-text-generation): communicating with you via text
+
+- [🦻 speech-to-text](https://github.com/etkecc/baibot/blob/main/docs/features.md#-speech-to-text): turning your voice messages into text
+
+- [🗣️ text-to-speech](https://github.com/etkecc/baibot/blob/main/docs/features.md#-text-to-speech): turning bot or users text messages into voice messages
+
+- [🖌️ image-generation](https://github.com/etkecc/baibot/blob/main/docs/features.md#-image-generation): generating images based on instructions
+
+- ❓ catch-all: special purposes, indicating use as a fallback (when no specific handler is configured)
+
+[Mixing & matching models](https://github.com/etkecc/baibot/blob/main/docs/features.md#mixing--matching-models) is made possible by the bot's ability to have different [🤝 handlers](https://github.com/etkecc/baibot/blob/main/docs/configuration/handlers.md) configured for different purposes.
+
+This configuration can be done as a global fallback, or per-room. Both of these [🛠️ configurations](https://github.com/etkecc/baibot/blob/main/docs/configuration/README.md) are managed at runtime (viat chat), but **the global configuration can have some initial defaults configured via Ansible**.
+
+You can configure the **initial values** for these via Ansible, via the `matrix_bot_baibot_config_initial_global_config_handler_*` variables.
+
+Example **additional** `vars.yml` configuration:
+
+```yaml
+# 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 is managed via bot commands, not via Ansible.
+
+matrix_bot_baibot_config_initial_global_config_handler_catch_all: static/openai
+
+# In this example, there's no need to define any of these below.
+# Configuring the catch-all purpose handler is enough.
+matrix_bot_baibot_config_initial_global_config_handler_text_generation: null
+matrix_bot_baibot_config_initial_global_config_handler_text_to_speech: null
+matrix_bot_baibot_config_initial_global_config_handler_speech_to_text: null
+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:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password.
+
+## Usage
+
+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.
+
+After joining, the bot will introduce itself and show information about the [✨ features](https://github.com/etkecc/baibot/blob/main/docs/features.md) that are enabled for it.
+
+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 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.
+
+## 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-baibot`.
+
+### 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.
+matrix_bot_baibot_config_logging_level_baibot: debug
+
+# Adjust the logging level for the mxlink bot library used by the bot.
+matrix_bot_baibot_config_logging_level_mxlink: debug
+
+# Adjust the logging level for other libraries used by the bot.
+# Having this set to a value other than "warn" can be very noisy.
+matrix_bot_baibot_config_logging_level_other_libs: debug
+```
+
+**Alternatively**, you can use a single variable to set the logging level for all of the above (bot + all libraries):
+
+```yaml
+matrix_bot_baibot_config_logging: debug
+```

docs/configuring-playbook-bot-buscarron.md

@@ -1,75 +1,118 @@
 # Setting up Buscarron (optional)
 
-The playbook can install and configure [buscarron](https://gitlab.com/etke.cc/buscarron) for you.
+The playbook can install and configure [Buscarron](https://github.com/etkecc/buscarron) for you.
 
-It's a bot you can use to setup **your own helpdesk on matrix**
-It's a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) matrix room
+Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.
 
-## Registering the bot user
+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.
 
-By default, the playbook will set up the bot with a username like this: `@bot.buscarron:DOMAIN`.
+## Adjusting DNS records
 
-(to use a different username, adjust the `matrix_bot_buscarron_login` variable).
-
-You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
-
-```
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.buscarron password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
-```
-
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
+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
 
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/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
 
-# Adjust this to whatever password you chose when registering the bot user
+# 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 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
 matrix_bot_buscarron_forms:
-  - name: contact # (mandatory) Your form name, will be used as endpoint, eg: buscarron.DOMAIN/contact
-    room: "!yourRoomID:DOMAIN" # (mandatory) Room ID where form submission will be posted
-    redirect: https://DOMAIN # (mandatory) To what page user will be redirected after the form submission
+  - name: contact # (mandatory) Your form name, will be used as endpoint, eg: buscarron.example.com/contact
+    room: "!qporfwt:{{ matrix_domain }}" # (mandatory) Room ID where form submission will be posted
+    redirect: https://example.com # (mandatory) To what page user will be redirected after the form submission
     ratelimit: 1r/m # (optional) rate limit of the form, format: <max requests>r/<interval:s,m>, eg: 1r/s or 54r/m
+    hasemail: 1 # (optional) form has "email" field that should be validated
     extensions: [] # (optional) list of form extensions (not used yet)
 
-matrix_bot_buscarron_spam_hosts: [] # (optional) list of email domains/hosts that should be rejected automatically
-matrix_bot_buscarron_spam_emails: [] # (optional) list of email addresses that should be rejected automatically
+matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
 ```
 
-You will also need to add a DNS record so that buscarron can be accessed.
-By default buscarron will use https://buscarron.DOMAIN so you will need to create an CNAME record for `buscarron`.
-See [Configuring DNS](configuring-dns.md).
+### Adjusting the Buscarron URL (optional)
 
-If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):
+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 `vars.yml` file:
 
 ```yaml
-matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Buscarron.
+matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /buscarron subpath
+matrix_bot_buscarron_path_prefix: /buscarron
 ```
 
+After changing the domain, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-buscarron/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command again:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_buscarron_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password.
 
 ## Usage
 
-To use the bot, invite the `@bot.buscarron:DOMAIN` 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.DOMAIN/contact">
+<form method="POST" action="https://buscarron.example.com/contact">
 <!--your fields-->
 </form>
 ```
 
-You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/buscarron).
+**Note**: to fight against spam, Buscarron is **very aggressive when it comes to banning** and will ban you if:
+
+- you hit the homepage (HTTP `GET` request to `/`)
+- you submit a form to the wrong URL (`POST` request to `/non-existing-form`)
+- `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.
+
+## 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

@@ -0,0 +1,90 @@
+# 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.
+
+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!
+
+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.
+
+## Prerequisites
+
+### Obtain an OpenAI API key
+
+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):
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+```
+
+### Obtain an access token and create encryption keys
+
+The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+
+> [!WARNING]
+> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
+
+To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [Element documentation](https://element.io/help#encryption6).
+
+## Adjusting the playbook configuration
+
+To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `API_KEY_HERE` with the API key retrieved [here](#obtain-an-openai-api-key) and `ACCESS_TOKEN_HERE` with the access token created [here](#obtain-an-access-token-and-create-encryption-keys), respectively.
+
+```yaml
+matrix_bot_chatgpt_enabled: true
+
+matrix_bot_chatgpt_openai_api_key: 'API_KEY_HERE'
+
+# Uncomment and adjust this part if you'd like to use a username different than the default
+# matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt'
+
+matrix_bot_chatgpt_matrix_access_token: 'ACCESS_TOKEN_HERE'
+
+# Configuring the system promt used, needed if the bot is used for special tasks.
+# More information: https://github.com/mustvlad/ChatGPT-System-Prompts
+matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.'
+```
+
+### 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
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bot, invite it to the room you specified on your `vars.yml` file (`/invite @bot.chatgpt:example.com` where `example.com` is your base domain, not the `matrix.` domain).
+
+After the bot joins the room, you can send a message to it. When you do so, use the prefix if you configured it or mention the bot.
+
+## 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

@@ -0,0 +1,254 @@
+# 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://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](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
+
+## Prerequisites
+
+### 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 need to enable the native E2EE support (see [below](#native-e2ee-support)).
+
+Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
+
+## End-to-End Encryption support
+
+Decide whether you want to support having an encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled.
+
+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_enable_experimental_rust_crypto: 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_access_token: "CLEAN_ACCESS_TOKEN_HERE"
+```
+
+## Adjusting the playbook configuration
+
+To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created earlier.
+
+```yaml
+# Enable Draupnir
+matrix_bot_draupnir_enabled: true
+
+# Uncomment and adjust this part if you'd like to use a username different than the default
+# matrix_bot_draupnir_login: bot.draupnir
+
+# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
+# If creating the user on your own and using `matrix_bot_draupnir_access_token` to login you can comment out this line.
+matrix_bot_draupnir_password: PASSWORD_FOR_THE_BOT
+
+# Comment out if using `matrix_bot_draupnir_enable_experimental_rust_crypto: true` or `matrix_bot_draupnir_access_token` to login.
+matrix_bot_draupnir_login_native: true
+
+matrix_bot_draupnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
+```
+
+### 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
+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).
+
+> [!WARNING]
+> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
+
+#### Run the `curl` command
+
+To disable rate limiting, run the following command on systems that ship curl. Before running it, make sure to replace:
+
+- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account
+- `example.com` with your base domain
+- `@bot.draupnir:example.com` with the MXID of your Draupnir bot user
+
+```sh
+curl --header "Authorization: Bearer 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_abuse_reporting_enabled: true
+```
+
+<!--
+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
+
+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
+```
+
+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
+
+You can refer to the upstream [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) for additional ways to use and configure Draupnir and for a more detailed usage guide.
+
+Below is a **non-exhaustive quick-start guide** for the impatient.
+
+### Making Draupnir join and protect a room
+
+Draupnir can be told to self-join public rooms, but it's better to follow this flow which works well for all kinds of rooms:
+
+1. Invite the bot to the room manually ([inviting Draupnir to rooms](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#inviting-draupnir-to-rooms)). Before joining, the bot *may* ask for confirmation in the Management Room
+
+2. [Give the bot permissions to do its job](#giving-draupnir-permissions-to-do-its-job)
+
+3. Tell it to protect the room (using the [rooms command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#using-the-draupnir-rooms-command)) by sending the following command to the Management Room: `!draupnir rooms add !qporfwt:example.com`
+
+To have Draupnir provide useful room protection, you need do to a bit more work (at least the first time around). You may wish to [Subscribe to a public policy list](#subscribing-to-a-public-policy-list), [Create your own own policy and rules](#creating-your-own-policy-lists-and-rules) and [Enabling built-in protections](#enabling-built-in-protections).
+
+### Giving Draupnir permissions to do its job
+
+For Draupnir to do its job, you need to [give it permissions](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#giving-draupnir-permissions) in rooms it's protecting. This involves **giving it an Administrator power level**.
+
+**We recommend setting this power level as soon as the bot joins your room** (and before you create new rules), so that it can apply rules as soon as they are available. If the bot is under-privileged, it may fail to apply protections and may not retry for a while (or until your restart it).
+
+### Subscribing to a public policy list
+
+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.
+
+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`
+
+#### Creating your own policy lists and rules
+
+We also recommend **creating your own policy lists** with the [list create](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-policy-lists#using-draupnirs-list-create-command-to-create-a-policy-room) command.
+
+You can do so by sending the following command to the Management Room: `!draupnir list create my-bans my-bans-bl`. This will create a policy list having a name (shortcode) of `my-bans` and stored in a public `#my-bans-bl:example.com` room on your server. As soon as you run this command, the bot will invite you to the policy list room.
+
+A policy list does nothing by itself, so the next step is **adding some rules to your policy list**. Policies target a so-called `entity` (one of: `user`, `room` or `server`). These entities are mentioned on the [policy lists](https://the-draupnir-project.github.io/draupnir-documentation/concepts/policy-lists) documentation page and in the Matrix Spec [here](https://spec.matrix.org/v1.11/client-server-api/#mban-recommendation).
+
+The simplest and most useful entity to target is `user`. Below are a few examples using the [ban command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#the-ban-command) and targeting users.
+
+To create rules, you run commands in the Management Room (**not** in the policy list room).
+
+- (ban a single user on a given homeserver): `!draupnir ban @charles:example.com my-bans Rude to others`
+- (ban all users on a given homeserver by using a [wildcard](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#wildcards)): `!draupnir ban @*:example.org my-bans Spam server - all users are fake`
+
+As a result of running these commands, you may observe:
+
+- Draupnir creating `m.policy.rule.user` state events in the `#my-bans-bl:example.com` room on your server
+- applying these rules against all rooms that Draupnir is an Administrator in
+
+You can undo bans with the [unban command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#the-unban-command).
+
+### Enabling built-in protections
+
+You can also **turn on various built-in [protections](https://the-draupnir-project.github.io/draupnir-documentation/protections)** like `JoinWaveShortCircuit` ("If X amount of users join in Y time, set the room to invite-only").
+
+To **see which protections are available and which are enabled**, send a `!draupnir protections` command to the Management Room.
+
+To **see the configuration options for a given protection**, send a `!draupnir protections show PROTECTION_NAME` (e.g. `!draupnir protections show JoinWaveShortCircuit`).
+
+To **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`).

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

@@ -1,45 +1,43 @@
-# Setting up Go-NEB (optional)
+# 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.
 
 The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
 
 Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
 
-See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/go-neb/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+## Prerequisites
 
-## Registering the bot user
+### Register the bot account
 
-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.
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
-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):
 
-```
+```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
+### Obtain an access token
 
-## Getting 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).
 
-If you use curl, you can get an access token like this:
+> [!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.
 
-```
-curl -X POST --header 'Content-Type: application/json' -d '{
-    "identifier": { "type": "m.id.user", "user": "bot.go-neb" },
-    "password": "a strong password",
-    "type": "m.login.password"
-}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
-```
+## Adjusting DNS records
 
-Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token), but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start).
+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
 
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/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 `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
@@ -48,18 +46,18 @@ 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_homeserver_container_url }}"
+    HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: true
     AutoJoinRooms: true
     DisplayName: "Go-NEB!"
     AcceptVerificationFromUsers: [":{{ matrix_domain }}"]
 
   - UserID: "@another_goneb:{{ matrix_domain }}"
-    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+    AccessToken: "ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE"
     DeviceID: "DEVICE2"
-    HomeserverURL: "{{ matrix_homeserver_container_url }}"
+    HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: false
     AutoJoinRooms: false
     DisplayName: "Go-NEB!"
@@ -75,7 +73,7 @@ matrix_bot_go_neb_realms:
 matrix_bot_go_neb_sessions:
   - SessionID: "your_github_session"
     RealmID: "github_realm"
-    UserID: "@YOUR_USER_ID:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
+    UserID: "@alice:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
     Config:
       # Populate these fields by generating a "Personal Access Token" on github.com
       AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
@@ -118,7 +116,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"
@@ -138,7 +136,7 @@ matrix_bot_go_neb_services:
     Config:
       feeds:
         "http://lorem-rss.herokuapp.com/feed?unit=second&interval=60":
-          rooms: ["!qmElAGdFYCHoCJuaNt:{{ matrix_domain }}"]
+          rooms: ["!qporfwt:{{ matrix_domain }}"]
           must_include:
             author:
               - author1
@@ -162,17 +160,17 @@ matrix_bot_go_neb_services:
     UserID: "@another_goneb:{{ matrix_domain }}"
     Config:
       RealmID: "github_realm"
-      ClientUserID: "@YOUR_USER_ID:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
+      ClientUserID: "@alice:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
       Rooms:
-        "!someroom:id":
+        "!qporfwt:example.com":
           Repos:
-            "matrix-org/synapse":
+            "element-hq/synapse":
               Events: ["push", "issues"]
             "matrix-org/dendron":
               Events: ["pull_request"]
-        "!anotherroom:id":
+        "!aaabaa:example.com":
           Repos:
-            "matrix-org/synapse":
+            "element-hq/synapse":
               Events: ["push", "issues"]
             "matrix-org/dendron":
               Events: ["pull_request"]
@@ -183,7 +181,7 @@ matrix_bot_go_neb_services:
     Config:
       Hooks:
         "hook1":
-          RoomID: "!someroom:id"
+          RoomID: "!qporfwt:example.com"
           MessageType: "m.text" # default is m.text
 
   - ID: "alertmanager_service"
@@ -197,30 +195,67 @@ matrix_bot_go_neb_services:
       webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
       # Each room will get the notification with the alert rendered with the given template
       rooms:
-        "!someroomid:domain.tld":
+        "!qporfwt:example.com":
           text_template: "{% raw %}{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}{% endraw %}"
           html_template: "{% raw %}{{range .Alerts -}}  {{ $severity := index .Labels \"severity\" }}    {{ if eq .Status \"firing\" }}      {{ if eq $severity \"critical\"}}        <font color='red'><b>[FIRING - CRITICAL]</b></font>      {{ else if eq $severity \"warning\"}}        <font color='orange'><b>[FIRING - WARNING]</b></font>      {{ else }}        <b>[FIRING - {{ $severity }}]</b>      {{ end }}    {{ else }}      <font color='green'><b>[RESOLVED]</b></font>    {{ end }}  {{ index .Labels \"alertname\"}} : {{ index .Annotations \"description\"}}   <a href=\"{{ .GeneratorURL }}\">source</a><br/>{{end -}}{% endraw %}"
           msg_type: "m.text"  # Must be either `m.text` or `m.notice`
 ```
 
+### Adjusting the Go-NEB URL (optional)
+
+By tweaking the `matrix_bot_go_neb_hostname` and `matrix_bot_go_neb_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Go-NEB.
+matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /go-neb subpath
+matrix_bot_go_neb_path_prefix: /go-neb
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-go-neb/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bot-go-neb/templates/config.yaml.j2` for the bot's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bot_go_neb_configuration_extension_yaml` variable
 
 ## Installing
 
-Don't forget to add `goneb.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-After configuring the playbook, run the [installation](installing.md) command again:
-
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
-To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:DOMAIN` where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
+To use the bot, invite it to any existing Matrix room (`/invite @bot.go-neb:example.com` where `example.com` is your base domain, not the `matrix.` domain). Make sure you are granted with the sufficient permission if you are not the room owner.
 
 Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
 
-If you enabled the github_cmd service 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,55 +1,95 @@
 # Setting up Honoroit (optional)
 
-The playbook can install and configure [Honoroit](https://gitlab.com/etke.cc/honoroit) for you.
+The playbook can install and configure [Honoroit](https://github.com/etkecc/honoroit) for you.
 
 It's a bot you can use to setup **your own helpdesk on matrix**
 
-See the project's [documentation](https://gitlab.com/etke.cc/honoroit#how-it-looks-like) to learn what it does with screenshots and why it might be useful to you.
+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)
 
-## Registering the bot user
-
-By default, the playbook will set up the bot with a username like this: `@honoroit:DOMAIN`.
-
-(to use a different username, adjust the `matrix_bot_honoroit_login` variable).
-
-You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
-
-```
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=honoroit password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
-```
-
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
+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
 
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/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
 
-# Adjust this to whatever password you chose when registering the bot user
+# 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 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: "!yourRoomID:DOMAIN"
+matrix_bot_honoroit_roomid: "!qporfwt:{{ matrix_domain }}"
 ```
 
+### Adjusting the Honoroit URL (optional)
+
+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 `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_bot_honoroit_hostname: honoroit.example.com
+matrix_bot_honoroit_path_prefix: /
+```
+
+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`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-honoroit/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command again:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_honoroit_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password.
 
 ## Usage
 
-To use the bot, invite the `@honoroit:DOMAIN` to the room you specified in config, after that any matrix user can send a message to the `@honoroit:DOMAIN` 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.
 
-You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/honoroit#features).
+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

@@ -2,47 +2,23 @@
 
 The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
 
-The bot allows you to easily **create and manage registration tokens**. It can be used for an invitation-based server,
-where you invite someone by sending them a registration token. They can register as normal but have to provide a valid
-registration token in a final step  of the registration.
+The bot allows you to easily **create and manage registration tokens** aka. invitation codes. It can be used for an invitation-based server, where you invite someone by sending them a registration token (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process.
 
-See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
-does and why it might be useful to you.
-
-
-## Registering the bot user
-
-By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`.
-
-(to use a different username, adjust the `matrix_bot_matrix_registration_bot_matrix_user_id_localpart` variable).
-
-You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
-
-```
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-registration-bot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
-```
-
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
-
-## Obtaining an admin access token
-
-In order to use the bot you need to add an admin user's access token token to the configuration. As you created an admin user for the
-bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
-(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
-You can expand "Access token" to copy it.
-
-![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
-
-**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
+See the project's [documentation](https://github.com/moan0s/matrix-registration-bot/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/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_registration_bot_enabled: true
-# Token obtained via logging into the bot account (see above)
-matrix_bot_matrix_registration_bot_bot_access_token: "syt_bW9hbm9z_XXXXXXXXXXXXXr_2kuzbE"
+
+# By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:example.com`.
+# Uncomment and adjust this part if you'd like to use a username different than the default
+# matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot
+
+# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
+matrix_bot_matrix_registration_bot_bot_password: PASSWORD_FOR_THE_BOT
 
 # Enables registration
 matrix_synapse_enable_registration: true
@@ -51,22 +27,61 @@ matrix_synapse_enable_registration: true
 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 the [installation](installing.md) command again:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_matrix_registration_bot_bot_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_registration_bot_bot_password` to let the bot know its new password.
 
 ## Usage
 
-To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+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 [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md) or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
+
+To clean the cache (session & encryption data) after you changed the bot's username, changed the login method from access_token to password etc… you can use:
+
+```sh
+just run-tags bot-matrix-registration-bot-clean-cache
+```
+
+## 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

@@ -4,56 +4,76 @@ The playbook can install and configure [matrix-reminder-bot](https://github.com/
 
 It's a bot you can use to **schedule one-off & recurring reminders and alarms**.
 
-See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you.
-
-
-## Registering the bot user
-
-By default, the playbook will set up the bot with a username like this: `@bot.matrix-reminder-bot:DOMAIN`.
-
-(to use a different username, adjust the `matrix_bot_matrix_reminder_bot_matrix_user_id_localpart` variable).
-
-You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
-
-```
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-reminder-bot password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
-```
-
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
-
+See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/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
 
-# Adjust this to whatever password you chose when registering the bot user
+# 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 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 the [installation](installing.md) command again:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password.
 
 ## Usage
 
-To use the bot, start a chat with `@bot.matrix-reminder-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+To use the bot, start a chat with `@bot.matrix-reminder-bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-You can also add the bot to any existing Matrix room (`/invite @bot.matrix-reminder-bot:DOMAIN`).
+You can also add the bot to any existing Matrix room (`/invite @bot.matrix-reminder-bot:example.com`).
 
 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

@@ -0,0 +1,126 @@
+# Setting up maubot (optional)
+
+The playbook can install and configure [maubot](https://github.com/maubot/maubot) for you.
+
+After setting up maubot, you can use the web management interface to make it do things. The default location of the management interface is `matrix.example.com/_matrix/maubot/`
+
+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 the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+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 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:
+  - yourusername: securepassword
+```
+
+You can add multiple admins. The admin accounts are only used to access the maubot administration interface.
+
+### Adjusting the maubot URL (optional)
+
+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 `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_bot_maubot_hostname: maubot.example.com
+matrix_bot_maubot_path_prefix: /
+```
+
+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`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bot.
+
+Take a look at:
+
+- `roles/custom/matrix-bot-maubot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bot-maubot/templates/config.yaml.j2` for the bot's default configuration
+
+## Customizing the maubot container image
+
+Certain [maubot plugins](https://plugins.mau.bot/) require additional dependencies to be installed.
+
+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
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_maubot_initial_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password.
+
+## Usage
+
+By default, you can visit `matrix.example.com/_matrix/maubot/` to manage your available plugins, clients and instances.
+
+You should start in the following order
+1. **Create one or more clients**: A client is a Matrix account which the bot will use to message. By default, the playbook creates a `bot.maubot` account (as per the configuration above). You only need to [obtain an access token](#obtaining-an-access-token) for it
+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)
+
+## 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 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

@@ -2,96 +2,145 @@
 
 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) to learn what it does and why it might be useful to 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.
 
+## Prerequisites
 
-## 1. Register the bot account
+### Register the bot account
 
-The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
-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):
 
-```
+```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
 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.
 
+### Obtain an access token
 
-## 2. Get 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).
 
-If you use curl, you can get an access token like this:
+> [!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.
 
-```
-curl -X POST --header 'Content-Type: application/json' -d '{
-    "identifier": { "type": "m.id.user", "user": "bot.mjolnir" },
-    "password": "PASSWORD_FOR_THE_BOT",
-    "type": "m.login.password"
-}' 'https://matrix.DOMAIN/_matrix/client/r0/login'
-```
+### Make sure the account is free from rate limiting
 
-Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token).
+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.**
 
+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.
 
-## 3. Make sure the account is free from rate limiting
+**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).
 
-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. [Currently there is no Synapse config option for this](https://github.com/matrix-org/synapse/issues/6286) so you have to manually edit the Synapse database. Manually editing the Synapse database is rarely a good idea but in this case it is required. Please ask for help if you are uncomfortable with these steps.
+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).
 
-1. Copy the statement below into a text editor. 
+#### Add the configuration
 
-	```
-	INSERT INTO ratelimit_override VALUES ('@bot.mjolnir:DOMAIN', 0, 0);
-	```
-
-1. Change the username (`@bot.mjolnir:DOMAIN`) to the username you used when you registered the bot's account. You must change `DOMAIN` to your server's domain.
-
-1. Get a database terminal by following these steps: [maintenance-postgres.md#getting-a-database-terminal](maintenance-postgres.md#getting-a-database-terminal)
-
-1. Connect to Synapse's database by typing `\connect synapse` into the database terminal
-
-1. Paste in the `INSERT INTO` command that you edited and press enter.
-
-You can run `SELECT * FROM ratelimit_override;` to see if it worked. If the output looks like this:
-
-```
-      user_id          | messages_per_second | burst_count
------------------------+---------------------+-------------
- @bot.mjolnir:raim.ist |                   0 |           0`
-```
-then you did it correctly.
-
-
-## 4. 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. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
-
-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 you can do this by going to the room's settings, clicking Advanced, and then coping the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`.
-
-Finally invite the `@bot.mjolnir:DOMAIN` account you created earlier into the room.
-
-
-## 5. Adjusting the playbook configuration
-
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
-
-You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with the your own values.
+To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_bot_mjolnir_enabled: true
-
-matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
-
-matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
 ```
 
-## 6. Adding mjolnir synapse antispam module (optional)
+#### Obtain an access token for admin account
 
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+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
+
+To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created just now.
+
+```yaml
+# Enable Mjolnir
+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 `vars.yml` file (adapt to your needs):
+
+```yaml
+# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
+matrix_pantalaimon_enabled: true
+
+# Tell Mjolnir to use Pantalaimon
+matrix_bot_mjolnir_pantalaimon_use: true
+
+# User name and password for the bot you have created above. Required when using Pantalaimon.
+matrix_bot_mjolnir_pantalaimon_username: "bot.mjolnir"
+matrix_bot_mjolnir_pantalaimon_password: "PASSWORD_FOR_THE_BOT"
+```
+
+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`:
+
+```yaml
+# Endpoint URL that Mjolnir uses to interact with the Matrix homeserver (client-server API).
+# Set this to the pantalaimon URL if you're using that.
+matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_mjolnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
+
+# Endpoint URL that Mjolnir 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_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+```
+
+#### 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 `vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
+
+```yaml
+matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_HERE"
+```
+
+### Adding Mjolnir synapse antispam module (optional)
+
+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
@@ -101,23 +150,15 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
 ```
 
+### Extending the configuration
 
-## 7. Installing
+There are some additional things you may wish to configure about the bot.
 
-After configuring the playbook, run the [installation](installing.md) command:
+Take a look at:
 
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
-```
+- `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
 
-
-## 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.DOMAIN/vars.yml` file.
-
-For example to change mjolnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
+For example, to change Mjolnir's `recordIgnoredInvites` option to `true`, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_bot_mjolnir_configuration_extension_yaml: |
@@ -130,3 +171,40 @@ 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,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the 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,67 +1,100 @@
-# Setting up Appservice Discord (optional)
+# 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) bridge supported by the playbook.
+**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.
+- For using as a Bot we are recommend the Appservice Discord bridge (the one being discussed here), because it supports plumbing.
+- For personal use we recommend the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge, because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
 
-The playbook can install and configure [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) for you.
+The playbook can install and configure [matrix-appservice-discord](https://github.com/matrix-org/matrix-appservice-discord) for you.
 
-See the project's [documentation](https://github.com/Half-Shot/matrix-appservice-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/matrix-appservice-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+## Prerequisites
 
-## Setup Instructions
+Create a Discord Application [here](https://discordapp.com/developers/applications). Then retrieve Client ID, and create a bot from the Bot tab and retrieve the Bot token.
 
-Instructions loosely based on [this](https://github.com/Half-Shot/matrix-appservice-discord#setting-up).
+## Adjusting the playbook configuration
 
-1. Create a Discord Application [here](https://discordapp.com/developers/applications).
-2. Retrieve Client ID.
-3. Create a bot from the Bot tab and retrieve the Bot token.
-4. Enable the bridge with the following configuration in your `vars.yml` file:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_appservice_discord_enabled: true
 matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
 matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
+
+# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
+# Note: This deprecated method is considered insecure.
+#
+# matrix_synapse_configuration_extension_yaml: |
+#   use_appservice_legacy_authorization: true
 ```
 
-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.
+### Extending the configuration
 
-Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.
+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
+```
+
+**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.
 
 ## Self-Service Bridging (Manual)
 
-Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. This is disabled by default, so it must be enabled by adding this to your `vars.yml`:
+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
 ```
 
-_Note: If self-service bridging is not enabled, `!discord help` commands will return no results._
+**Note**: If self-service bridging is not enabled, `!discord help` commands will return no results.
 
-Once self-service is enabled:
+### Usage
 
-1. Start a chat with `@_discord_bot:<YOUR_DOMAIN>` and say `!discord help bridge`.
-2. 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.
+Once self-service is enabled, start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
 
-_Note: Encrypted Matrix rooms are not supported as of writing._
+Then, follow the instructions in the help output message.
 
-On the Discord side, you can say `!matrix help` to get a list of available commands to manage the bridge and Matrix users.
+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, 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.
 
 ## Portal Bridging (Automatic)
 
-Through portal bridging, Matrix rooms will automatically be created by the bot and bridged to the relevant Discord room. This is done by simply joining a room with a specific name pattern (`#_discord_<guildID>_<channlID>`).
+Through portal bridging, Matrix rooms will automatically be created by the bot and bridged to the relevant Discord room. This is done by simply joining a room with a specific name pattern (`#_discord_<guildID>_<channelID>`).
 
 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.
 
-If you want to disable portal bridging, set the following in `vars.yml`:
+To disable portal bridging, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_appservice_discord_bridge_disablePortalBridging: true
 ```
 
+### Usage
+
 To get started with Portal Bridging:
 
 1. To invite the bot to Discord, retrieve the invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
 2. Room addresses follow this syntax: `#_discord_<guildID>_<channelID>`. You can easily find the guild and channel IDs by logging into Discord in a browser and opening the desired channel. The URL will have this format: `discord.com/channels/<guildID>/<channelID>`.
-3. Once you have figured out the appropriate room address, you can join by doing `/join #_discord_<guildID>_<channelID>` in your Matrix client. 
+3. Once you have figured out the appropriate room address, you can join by doing `/join #_discord_<guildID>_<channelID>` in your Matrix client.
 
 ## Getting Administrator access in a portal bridged room
 
@@ -69,9 +102,24 @@ By default, you won't have Administrator access in rooms created by the bridge.
 
 To adjust room access privileges or do various other things (change the room name subsequently, etc.), you'd wish to become an Administrator.
 
-There's the Discord bridge's guide for [setting privileges on bridge managed rooms](https://github.com/Half-Shot/matrix-appservice-discord/blob/master/docs/howto.md#set-privileges-on-bridge-managed-rooms). To do the same with our container setup, run the following command on the server:
+There's the Discord bridge's guide for [setting privileges on bridge managed rooms](https://github.com/matrix-org/matrix-appservice-discord/blob/master/docs/howto.md#set-privileges-on-bridge-managed-rooms). To do the same with our container setup, run the following command on the server:
 
 ```sh
 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 "!ROOM_ID:SERVER" -u "@USER:SERVER" -p 100'
+/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,4 +1,4 @@
-# Setting up Appservice IRC (optional)
+# 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.
 
@@ -6,7 +6,9 @@ The playbook can install and configure the [matrix-appservice-irc](https://githu
 
 See the project's [documentation](https://github.com/matrix-org/matrix-appservice-irc/blob/master/HOWTO.md) to learn what it does and why it might be useful to you.
 
-You'll need to use the following playbook configuration:
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_appservice_irc_enabled: true
@@ -58,4 +60,52 @@ matrix_appservice_irc_ircService_servers:
       lineLimit: 3
 ```
 
-You then need to start a chat with `@irc_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-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
+```
+
+**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 `@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

@@ -0,0 +1,70 @@
+# 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, 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.
+
+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.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_appservice_kakaotalk_enabled: true
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bridge-appservice-kakaotalk/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_kakaotalk_configuration_extension_yaml` variable
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+You then need to send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-appservice-kakaotalk`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_appservice_kakaotalk_logging_level: DEBUG
+```

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

@@ -1,112 +1,150 @@
-# Setting up Appservice Slack (optional)
+# Setting up Appservice Slack bridging (optional)
 
-**Note**: bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) bridge supported by the playbook.
+**Notes**:
+- Bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook.
+- Currently (as of November, 2024) **this component is not available for new installation unless you have already created a classic Slack application** (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
 
 The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
 
 See the project's [documentation](https://github.com/matrix-org/matrix-appservice-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-## Setup Instructions:
+## Prerequisites
 
-loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)
+### Create a Classic Slack App
 
-1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can
-be done in Element by making a message, opening the options for that message and choosing "view source". The
-room ID will be displayed near the top.
-2. Enable the bridge with the following configuration in your `vars.yml` file:
+First, you need to create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
+
+Name the app "matrixbot" (or anything else you'll remember). Select the team/workspace this app will belong to. Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
+
+Then, click on Event Subscriptions and enable them and use the request url: `https://matrix.example.com/appservice-slack`.
+
+Add the following events as `Bot User Events` and save:
+
+- team_domain_change
+- message.channels
+- message.groups (if you want to bridge private channels)
+- reaction_added
+- reaction_removed
+
+Next, click on "OAuth & Permissions" and add the following scopes:
+
+- chat:write:bot
+- users:read
+- reactions:write
+- files:write:user (if you want to bridge files)
+
+**Note**: In order to make Slack files visible to Matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
+
+Click on "Install App" and "Install App to Workspace". Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
+
+### Create an administration control room on Matrix
+
+Create a new Matrix room to act as the administration control room.
+
+Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_appservice_slack_enabled: true
-matrix_appservice_slack_control_room_id: "Your matrix admin room id"
+matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
+
+# Uncomment to enable puppeting (optional, but recommended)
+# matrix_appservice_slack_puppeting_enabled: true
+# matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
+# matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
+
+# Uncomment to enable Team Sync (optional)
+# See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
+# matrix_appservice_slack_team_sync_enabled: true
 ```
 
-3. 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.
-4. Invite the bridge bot user into the admin room:
+### Extending the configuration
 
-```
-    /invite @slackbot:MY.DOMAIN
+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"
 ```
 
-Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
+## Installing
 
-5. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-    Name the app "matrixbot" (or anything else you'll remember).
+<!-- 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
+```
 
-    Select the team/workspace this app will belong to.
+**Notes**:
 
-    Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-6. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-     Bot User Events:
+  `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.
 
-    - team_domain_change
-    - message.channels
-    - message.groups (if you want to bridge private channels)
-    - reaction_added
-    - reaction_removed
+## Usage
 
-7. Click on OAuth & Permissions and add the following scopes:
+To use the bridge, you need to send `/invite @slackbot:example.com` to invite the bridge bot user into the admin room.
 
-    - chat:write:bot
-    - users:read
-    - reactions:write
+If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
 
-    If you want to bridge files, also add the following:
+- 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:
 
-    - files:write:user
+    with file bridging:
 
-    Note: In order to make Slack files visible to matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
-
-8. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
-
-9. 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 !aBcDeF: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:MY.DOMAIN` for matrix.
-
-    * Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel id>/details/`.
-
-    * Issue a link command in the administration control room with these collected values as arguments:
-
-        with file bridging:
     ```
-        link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
-    ```
-        without file bridging:
-    ```
-        link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
-    ```
-        These arguments can be shortened to single-letter forms:
-    ```
-        link -I CHANNELID -R !the-matrix:room.id -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
+    link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
     ```
 
-Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
+    without file bridging:
 
-10. Unlinking
-
-    Channels can be unlinked again like this:
     ```
-       unlink --room !the-matrix:room.id
+    link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
     ```
 
-    Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
+    These arguments can be shortened to single-letter forms:
+
+    ```
+    link -I CHANNELID -R !qporfwt:example.com -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
+    ```
+
+### Unlinking
+
+Channels can be unlinked again by sending this:
+
+```
+unlink --room !qporfwt:example.com
+```
+
+Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
 
 ## Troubleshooting
 
-* as always, check the logs:
-`journalctl -fu matrix-appservice-slack`
+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"
-This typically means that you haven't used the correct slack channel id. Unlink the room and recheck 'Determine the "channel ID"' from above.
+### Linking: "Room is now pending-name"
 
-* Messages work from M to S, but not the other way around
-Check you logs, if they say something like
+This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
 
-`WARN SlackEventHandler Ignoring message from unrecognised slack channel id : %s (%s) <the channel id> <some other id>`
+### Messages work from Matrix to Slack, but not the other way around
 
-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.
+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>`
+
+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,47 +1,67 @@
-# Setting up Appservice Webhooks (optional)
+# Setting up Appservice Webhooks bridging (optional, deprecated)
 
-The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you.
+**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 is no longer maintained. While not a 1:1 replacement, the bridge's author suggests taking a look at [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) as a replacement, which can also be installed using [this playbook](configuring-playbook-bridge-hookshot.md).
+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.
 
-This bridge provides support for Slack-compatible webhooks.
+See the project's [documentation](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-Setup Instructions:
+## Adjusting the playbook configuration
 
-loosely based on [this](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md)
-
-1. All you basically need is to adjust your `inventory/host_vars/matrix.<domain-name>/vars.yml`:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_appservice_webhooks_enabled: true
 matrix_appservice_webhooks_api_secret: '<your_secret>'
+
+# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
+# Note: This deprecated method is considered insecure.
+#
+# matrix_synapse_configuration_extension_yaml: |
+#   use_appservice_legacy_authorization: true
 ```
 
-2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
-you can adjust this in `inventory/host_vars/matrix.<domain-name>/vars.yml` as well.
+### Extending the configuration
 
-*Note*: default value is: `info` and availabe log levels are : `info`, `verbose`
+There are some additional things you may wish to configure about the bridge.
 
-```yaml
-matrix_appservice_webhooks_log_level: '<log_level>'
+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
 ```
 
-3. 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.
+**Notes**:
 
-4. If you're using the [Dimension Integration Manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL"  & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively. 
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-5. Invite the bridge bot user to your room:
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-    - either with `/invite @_webhook:<domain.name>` (*Note*: Make sure you have administration permissions in your room)
+  `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.
 
-    - or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
+## Usage
+
+To use the bridge, you need to invite the bridge bot user to your room in either way.
+
+- Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
+- Add the bridge bot to a private channel (personal channels imply you being an administrator)
+
+You then need to send a message to the bridge bot to receive a private message including the webhook link:
 
-6. Send a message to the bridge bot in order to receive a private message including the webhook link.
 ```
 !webhook
 ```
 
-7. The JSON body for posting messages will have to look like this:
+The JSON body for posting messages will have to look like this:
+
 ```json
 {
     "text": "Hello world!",
@@ -53,7 +73,7 @@ matrix_appservice_webhooks_log_level: '<log_level>'
 
 You can test this via curl like so:
 
-```
+```sh
 curl --header "Content-Type: application/json" \
 --data '{
 "text": "Hello world!",
@@ -61,5 +81,26 @@ curl --header "Content-Type: application/json" \
 "displayName": "My Cool Webhook",
 "avatar_url": "http://i.imgur.com/IDOBtEJ.png"
 }' \
-<the link you've gotten in 5.>
+<the webhook link you've gotten from the bridge bot>
+```
+
+### Setting Webhooks with Dimension integration manager
+
+If you're using the [Dimension integration manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge with it.
+
+To configure it, open the Dimension integration manager, and go to "Settings" and "Bridges", then select edit action for "Webhook Bridge".
+
+On the UI, press "Add self-hosted Bridge" button and populate "Provisioning URL"  and "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
+
+## 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,59 +1,70 @@
-# Setting up Beeper Linkedin (optional)
+# Setting up Beeper Linkedin bridging (optional)
 
-The playbook can install and configure [beeper-linkedin](https://gitlab.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://gitlab.com/beeper/linkedin/-/blob/master/README.md) to learn what it does and why it might be useful to you.
+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:
 
 ```yaml
 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:
-```yaml
-matrix_beeper_linkedin_configuration_extension_yaml: |
-  bridge:
-    encryption:
-      allow: true
-      default: true
+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 `_beeper_linkedin_`.
+
+## 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
 ```
 
-If you would like to be able to administrate the bridge from your account it can be configured like this:
-```yaml
-matrix_beeper_linkedin_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@YOUR_USERNAME:YOUR_DOMAIN': admin
-```
+**Notes**:
 
-You may wish to look at `roles/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
+- 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`
 
-## Set up Double Puppeting
-
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
-
-### Method 1: automatically, by enabling Shared Secret Auth
-
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) 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.
-
+  `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
 
-You then need to start a chat with `@linkedinbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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.
-
-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), if you haven't already done so.
+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).
 
+You then need to send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
 
 ## 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

@@ -0,0 +1,65 @@
+# 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, 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 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
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+## 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,38 +1,83 @@
-# Setting up Heisenbridge (optional)
+# 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 [README](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).
+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)
 
-Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/matrix-bridge-heisenbridge/defaults/main.yml).
+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.
 
-At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
+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:
 
 ```yaml
 matrix_heisenbridge_enabled: true
 
-# set owner (optional)
-matrix_heisenbridge_owner: "@you:your-homeserver"
+# Setting the owner is optional as the first local user to DM `@heisenbridge:example.com` will be made the owner.
+# If you are not using a local user you must set it as otherwise you can't DM it at all.
+matrix_heisenbridge_owner: "@alice:{{ matrix_domain }}"
 
-# to enable identd on host port 113/TCP (optional)
-matrix_heisenbridge_identd_enabled: true
+# Uncomment to enable identd on host port 113/TCP (optional)
+# matrix_heisenbridge_identd_enabled: true
 ```
 
-That's it! A registration file is automatically generated during the setup phase.
+### Adjusting the Heisenbridge URL (optional)
 
-Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.
-If you are not using a local user you must set it as otherwise you can't DM it at all.
+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 `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_heisenbridge_hostname: heisenbridge.example.com
+matrix_heisenbridge_path_prefix: /
+```
+
+If you've changed the default hostname, you may need to create a CNAME record for the Heisenbridge domain (`heisenbridge.example.com`), which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-heisenbridge/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**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
 
-After the bridge is successfully running just DM `@heisenbridge:your-homeserver` to start setting it up.
+To use the bridge, you need to start a chat with `@heisenbridge:example.com` (where `example.com` is your base domain, not the `matrix.` domain). If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
+
 Help is available for all commands with the `-h` switch.
-If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
 
 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,70 +1,180 @@
-# Setting up Hookshot (optional)
+# 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/hookshot.html) to learn what it does in detail and why it might be useful to you.
+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 is soon to be archived by its author and to be replaced by hookshot.
+**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/setup.html) to learn what the individual options do.
+### Download GitHub app private key (optional)
 
-1. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) as required.
-2. 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).
-3. 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-matrix-aux-role) explained below. 
-4. 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`.
-5. Refer to [Hookshot's official instructions](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) to start using the bridge. **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.
+If you're setting up the GitHub bridge, you need to create your GitHub app, and generate a private key file of it.
 
-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/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).
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `GITHUB_PRIVATE_KEY_HERE` with the one created [above](#download-github-app-private-key).
+
+```yaml
+matrix_hookshot_enabled: true
+
+# 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
+
+To use the bridge, you need to create a room and invite the Hookshot bot (`@hookshot:example.com`) to it.
+
+Make sure the bot is able to send state events (usually the Moderator power level in clients).
+
+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.
+
+💡 **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
 
 ### URLs for bridges setup
 
 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 |
 |---|---|---|---|
-| webhooks | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | generics, GitHub "Webhook URL", GitLab "URL", etc. |
+| - | `/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 | `/hookshot/metrics/` (on `stats.` subdomain) | `matrix_hookshot_metrics_endpoint` | Prometheus |
+| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
 
-See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml).
+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/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 matrix-aux role
+### 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/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 `matrix-aux` role to copy the file from an arbitrary path on your ansible client to the correct path on the server.
 
-To use `matrix-aux`, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add to `matrix-aux` configuration like this:
+- 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 configuration to your `vars.yml` file:
+
 ```yaml
-matrix_aux_file_definitions:
+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 }}"
     group: "{{ matrix_user_groupname }}"
 ```
-For more info see the documentation in the [matrix-aux base configuration file](/roles/matrix-aux/defaults/main.yml).
+
+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
-
-If metrics are enabled, they will be automatically available in the builtin Prometheus and Grafana, but you need to set up your own Dashboard for now. If additionally metrics proxying for use with external Prometheus is enabled (`matrix_nginx_proxy_proxy_synapse_metrics`), hookshot metrics will also be available (at `matrix_hookshot_metrics_endpoint`, default `/hookshot/metrics`, on the stats subdomain) and with the same password. See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).
+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`.
 
 ### 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_user_id_prefix: '_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 metics.
+
+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,20 +1,22 @@
-# Setting up matrix-sms-bridge (optional)
+# 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 page to learn what it does and why it might be useful to 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
 
-To enable the bridge just use the following
-playbook configuration:
+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
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_sms_bridge_enabled: true
 
-# (optional but recommended) a room id to a default room
-matrix_sms_bridge_default_room: "" 
+# (optional but recommended) a room ID to a default room
+matrix_sms_bridge_default_room: ""
 
 # (optional but recommended) configure your server location
 matrix_sms_bridge_default_region: DE
@@ -28,10 +30,37 @@ 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
+```
+
+**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
 
 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-bridges.md

@@ -0,0 +1,213 @@
+# 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,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 `@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

@@ -0,0 +1,86 @@
+# 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.
+
+The playbook can install and configure [mautrix-discord](https://github.com/mautrix/discord) for you.
+
+See the project's [documentation](https://docs.mau.fi/bridges/go/discord/index.html) to learn what it does and why it might be useful to you.
+
+## Prerequisites
+
+There are 2 ways to login to discord using this bridge, either by [scanning a QR code](#method-1-login-using-qr-code-recommended) using the Discord mobile app **or** by using a [Discord token](#method-2-login-using-discord-token-not-recommended).
+
+If this is a dealbreaker for you, consider using one of the other Discord bridges supported by the playbook: [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) or [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md). These come with their own complexity and limitations, however, so we recommend that you proceed with this one if possible.
+
+### 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:
+
+```yaml
+matrix_mautrix_discord_enabled: true
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+<!-- NOTE: common relay mode is not supported for this bridge -->
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@discordbot: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/discord/authentication.html).
+
+After logging in, the bridge will create portal rooms for some recent direct messages.
+
+### Bridge guilds
+
+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.
+
+After bridging, spaces will be created automatically, and rooms will be created if necessary when messages are received. You can also pass `--entire` to the bridge command to immediately create all rooms.
+
+If you want to manually bridge channels, invite the bot to the room you want to bridge, and run `!discord bridge CHANNEL_ID_HERE` to bridge the room. Make sure to replace `CHANNEL_ID_HERE` with the channel's ID.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-discord`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_discord_logging_level: 'debug'
+```

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

@@ -1,77 +1,74 @@
-# Setting up Mautrix Facebook (optional)
+# Setting up Mautrix Facebook bridging (optional, deprecated)
+
+<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.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mautrix_facebook_enabled: true
 ```
 
-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:
-```yaml
-matrix_mautrix_facebook_configuration_extension_yaml: |
-  bridge:
-    encryption:
-      allow: true
-      default: true
+There are some additional things you may wish to configure about the bridge.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
-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:
-      '@YOUR_USERNAME:YOUR_DOMAIN': admin
-```
+**Notes**:
 
-You may wish to look at `roles/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` to find other things you would like to configure.
+- 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`
 
-## Set up Double Puppeting
-
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
-
-### Method 1: automatically, by enabling Shared Secret Auth
-
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) 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
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-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. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Facebook", "initial_device_display_name": "Mautrix-Facebook"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
-
-- 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
-
+  `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
 
-You then need to start a chat with `@facebookbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+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.
 
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), 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-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.
@@ -82,8 +79,8 @@ The easiest way to do this may be to use [sshuttle](https://sshuttle.readthedocs
 
 Example command for proxying your traffic through the Matrix server:
 
-```
-sshuttle -r root@matrix.DOMAIN:22 0/0
+```sh
+sshuttle -r root@matrix.example.com:22 0/0
 ```
 
 Once connected, you should be able to verify that you're browsing the web through the Matrix server's IP by checking [icanhazip](https://icanhazip.com/).
@@ -91,3 +88,5 @@ Once connected, you should be able to verify that you're browsing the web throug
 Then proceed to log in to [Facebook/Messenger](https://www.facebook.com/).
 
 Once logged in, proceed to [set up bridging](#usage).
+
+If that doesn't work, enable 2FA (see: [Facebook help page on enabling 2FA](https://www.facebook.com/help/148233965247823)) and try to login again with a new password, and entering the 2FA code when prompted, it may take more then one try, in between attempts, check facebook.com to see if they are requiring another password change

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

@@ -0,0 +1,68 @@
+# 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.
+
+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_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
+```
+
+**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 `@gmessagesbot: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/gmessages/authentication.html).
+
+After logging in, the bridge will create portal rooms for recent chats.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-gmessages`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_gmessages_logging_level: 'debug'
+```

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

@@ -1,58 +1,69 @@
-# Setting up Mautrix Google Chat (optional)
+# 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.
 
-To enable the [Google Chat](https://chat.google.com/) bridge just use the following playbook configuration:
+## 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.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
+
+## Adjusting the playbook configuration
+
+To enable the [Google Chat](https://chat.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mautrix_googlechat_enabled: true
 ```
 
+### Extending the configuration
 
-## Set up Double Puppeting
+There are some additional things you may wish to configure about the bridge.
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+<!-- 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.
 
-### Method 1: automatically, by enabling Shared Secret Auth
+## Installing
 
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-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
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-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. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-googlechat", "initial_device_display_name": "Mautrix-googlechat"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
+<!-- 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
 ```
 
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+**Notes**:
 
-- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature
+- 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 bot is enabled you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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 some 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`.
 
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
+### 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_googlechat_logging_level: DEBUG
+```

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

@@ -1,60 +1,17 @@
-# The [Mautrix Hangouts Bridge](https://mau.dev/mautrix/hangouts) is no longer maintained.  It has changed to a [Google Chat Bridge](https://github.com/mautrix/googlechat). Setup instructions for the Google Chat Bridge can be [found here](configuring-playbook-bridge-mautrix-googlechat.md). 
+# Setting up Mautrix Hangouts bridging (optional, deprecated)
 
-# Setting up Mautrix Hangouts (optional)
+🪦 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.
 
-The playbook can install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts) for you.
+You may wish to use the [Google Chat bridge](https://github.com/mautrix/googlechat) instead.
 
-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.
+## Uninstalling the bridge manually
 
-To enable the [Google Hangouts](https://hangouts.google.com/) bridge just use the following playbook configuration:
+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:
 
+```sh
+systemctl disable --now matrix-mautrix-hangouts.service
 
-```yaml
-matrix_mautrix_hangouts_enabled: true
+rm -rf /matrix/mautrix-hangouts
+
+/matrix/postgres/bin/cli-non-interactive 'DROP DATABASE matrix_mautrix_hangouts;'
 ```
-
-
-## Set up Double Puppeting
-
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
-
-### Method 1: automatically, by enabling Shared Secret Auth
-
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) 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
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-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. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Hangouts", "initial_device_display_name": "Mautrix-Hangouts"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
-
-- 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
-
-
-## Usage
-
-Once the bot is enabled you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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).
-
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
-

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

@@ -1,17 +1,58 @@
-# Setting up Mautrix Instagram (optional)
+# Setting up Mautrix Instagram bridging (optional, deprecated)
+
+<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
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mautrix_instagram_enabled: true
 ```
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**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
 
-You then need to start a chat with `@instagrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+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

@@ -0,0 +1,84 @@
+# 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).
+
+## Prerequisites
+
+### Migrating from the old mautrix-instagram bridge
+
+If you've been using the [mautrix-instagram](./configuring-playbook-bridge-mautrix-instagram.md) bridge, **you'd better get rid of it first** or the 2 bridges will be in conflict:
+
+- both trying to use `@instagrambot:example.com` as their username. This conflict may be resolved by adjusting `matrix_mautrix_instagram_appservice_bot_username` or `matrix_mautrix_meta_instagram_appservice_username`
+- both trying to bridge the same DMs
+
+To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@instagrambot:example.com`). It gives you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
+
+Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
+
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_mautrix_meta_instagram_enabled: true
+```
+
+Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@instagrambot: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/meta/authentication.html).
+
+After logging in, the bridge will sync recent chats.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-meta-instagram`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
+matrix_mautrix_meta_instagram_logging_min_level: debug
+```

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

@@ -0,0 +1,99 @@
+# 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).
+
+## Prerequisites
+
+### Migrating from the old mautrix-facebook bridge
+
+If you've been using the [mautrix-facebook](./configuring-playbook-bridge-mautrix-facebook.md) bridge, it's possible to migrate the database using [instructions from the bridge documentation](https://docs.mau.fi/bridges/go/meta/facebook-migration.html) (advanced).
+
+Then you may wish to get rid of the Facebook bridge. To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@facebookbot:example.com`). It gives you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
+
+Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
+
+**Note**: the user ID of the new bridge bot is `@messengerbot:example.com`, not `@facebookbot:example.com`. After disabling the old bridge, its bot user will stop responding to a command.
+
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_mautrix_meta_messenger_enabled: true
+```
+
+Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
+
+### Bridge mode
+
+As mentioned above, the [mautrix-meta](https://github.com/mautrix/meta) bridge supports multiple modes of operation.
+
+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
+- (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.).
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@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 can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
+
+After logging in, the bridge will sync recent chats.
+
+**Note**: given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-meta-messenger`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
+matrix_mautrix_meta_messenger_logging_min_level: debug
+```

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

@@ -1,91 +1,75 @@
-# Setting up Mautrix Signal (optional)
+# 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/Prerequisite**: If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing. However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
+## Prerequisites (optional)
 
-Use the following playbook configuration:
+### Prepare Postgres database on external Postgres server
+
+If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing.
+
+However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
+
+### 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_signal_enabled: true
 ```
 
-There are some additional things you may wish to configure about the bridge before you continue.
+### 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:
-```yaml
-matrix_mautrix_signal_relaybot_enabled: true
-```
-If you want to activate the relay bot in a room, use `!signal set-relay`.
-Use `!signal unset-relay` to deactivate.
-By default, any user on your homeserver will be able to use the bridge.
-If you enable the relay bot functionality, it will relay every user's messages in a portal room - no matter which homeserver they're from.
+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.
+## Installing
 
-The permissions are following the sequence: nothing < relay < user < admin.
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-The default permissions are set as follows:
-```yaml
-permissions:
-  '*': relay
-  YOUR_DOMAIN: user
+<!-- 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
 ```
 
-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:
-      '@YOUR_USERNAME:YOUR_DOMAIN': admin
-```
+**Notes**:
 
-This will add the admin permission to the specific user, while keepting the default permissions.
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-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: |
-  '@ADMIN:YOUR_DOMAIN': admin
-  '@USER:YOUR_DOMAIN' : user
-```
-
-You may wish to look at `roles/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
-
-## Set up Double Puppeting
-
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
-
-### Method 1: automatically, by enabling Shared Secret Auth
-
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) 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
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-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. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Signal", "initial_device_display_name": "Mautrix-Signal"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
-
-- 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
+- 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
 
-You then need to start a chat with `@signalbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+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).
+
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/signal/authentication.html).
+
+After logging in, the bridge will bridge chats as you receive messages.
+
+**Note**: Signal does not support any kind of message history (even on official apps), so the bridge won't backfill any messages.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-signal`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_signal_logging_level: 'debug'
+```

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

@@ -0,0 +1,78 @@
+# Setting up Mautrix Slack bridging (optional)
+
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
+**Note**: bridging to [Slack](https://slack.com/) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) bridges supported by the playbook.
+- For using as a Bot we recommend the [Appservice Slack](configuring-playbook-bridge-appservice-slack.md), because it supports plumbing. Note that it is not available for new installation unless you have already created a classic Slack application, because the creation of classic Slack applications, which this bridge makes use of, has been discontinued.
+- For personal use with a slack account we recommend the `mautrix-slack` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Slack bridges supported by the playbook.
+
+The playbook can install and configure [mautrix-slack](https://github.com/mautrix/slack) for you.
+
+See the project's [documentation](https://docs.mau.fi/bridges/go/slack/index.html) to learn what it does and why it might be useful to you.
+
+See the [features and roadmap](https://github.com/mautrix/slack/blob/main/ROADMAP.md) for more information.
+
+## Prerequisites
+
+For using this bridge, you would need to authenticate by **providing your username and password** (legacy) or by using a **token login**. See more information in the [docs](https://docs.mau.fi/bridges/go/slack/authentication.html).
+
+Note that neither of these methods are officially supported by Slack. [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) uses a Slack bot account which is the only officially supported method for bridging a Slack channel.
+
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_mautrix_slack_enabled: true
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+<!-- NOTE: relay mode is not supported for this bridge -->
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@slackbot: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/slack/authentication.html).
+
+If you authenticated using a token, the recent chats will be bridged automatically (depending on the `conversation_count` setting). Otherwise (i.e. logging with the Discord application), the chats the bot is in will be bridged automatically.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-slack`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_slack_logging_level: 'debug'
+```

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

@@ -1,10 +1,32 @@
-# Setting up Mautrix Telegram (optional)
+# 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.
 
-You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then use the following playbook configuration:
+## 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.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Notes**:
+
+- Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
+
+- If you decided to enable Double Puppeting manually, send `login-matrix` to the bot in order to receive an instruction about how to send an access token to it.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `YOUR_TELEGRAM_APP_ID` and `YOUR_TELEGRAM_API_HASH`.
 
 ```yaml
 matrix_mautrix_telegram_enabled: true
@@ -12,40 +34,11 @@ matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
 matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
 ```
 
-## Set up Double Puppeting
+### Relaying
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+### Enable relay-bot (optional)
 
-### Method 1: automatically, by enabling Shared Secret Auth
-
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) 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
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging.
-
-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. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Telegram", "initial_device_display_name": "Mautrix-Telegram"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
-
-- send `login-matrix` to the bot and follow instructions about how to send the access token to it
-
-- make sure you don't log out the `Mautrix-Telegram` device some time in the future, as that would break the Double Puppeting feature
-
-
-## Usage
-
-You then need to start a chat with `@telegrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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, use the following additional playbook configuration:
+If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
@@ -55,13 +48,60 @@ 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)
+
+You might also want to give permissions to a user to administrate the bot. See [this section](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional) on the common guide for details about it.
+
+More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
+
+### Use the bridge for direct chats only (optional)
+
+If you want to exclude all groups from syncing and use the Telegram-Bridge only for direct chats, add the following configuration to your `vars.yml` file:
+
 ```yaml
-matrix_mautrix_telegram_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@user:DOMAIN': admin
+matrix_mautrix_telegram_filter_mode: whitelist
 ```
 
-More details about permissions in this example:
-https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+<!-- NOTE: common relay mode is not supported for this bridge -->
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/telegram/authentication.html).
+
+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.
+
+## 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,35 +1,70 @@
-# Setting up Mautrix Twitter (optional)
+# Setting up Mautrix Twitter bridging (optional)
+
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
 
 **Note**: bridging to [Twitter](https://twitter.com/) can also happen via the [mx-puppet-twitter](configuring-playbook-bridge-mx-puppet-twitter.md) bridge supported by the playbook.
 
 The playbook can install and configure [mautrix-twitter](https://github.com/mautrix/twitter) for you.
 
-See the project's [documentation](https://github.com/mautrix/twitter) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/mautrix/twitter/blob/master/README.md) to learn what it does and why it might be useful to you.
+
+## 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_twitter_enabled: true
 ```
 
+### Extending the configuration
 
-## Set up Double Puppeting
+There are some additional things you may wish to configure about the bridge.
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+<!-- 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.
 
-### Method 1: automatically, by enabling Shared Secret Auth
+## Installing
 
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-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.
+<!-- 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
+```
 
-### Method 2: manually, by asking each user to provide a working access token
+**Notes**:
 
-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`
+- 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
 
-1. You then need to start a chat with `@twitterbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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.
+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).
 
-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).
 
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
+After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-twitter`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_twitter_logging_level: 'debug'
+```

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

@@ -1,62 +1,71 @@
-# Setting up Mautrix Whatsapp (optional)
+# 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.
 
-Use the following playbook configuration:
+## 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.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mautrix_whatsapp_enabled: true
-``` 
-Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
-
-## Enable backfilling history
-This requires a server with MSC2716 support, which is currently an experimental feature in synapse.
-Note that as of Synapse 1.46, there are still some bugs with the implementation, especially if using event persistence workers.
-Use the following playbook configuration:
-
-```yaml
-matrix_synapse_configuration_extension_yaml: |
-  experimental_features:
-    msc2716_enabled: true
-```
-```yaml
-matrix_mautrix_whatsapp_configuration_extension_yaml:
-  bridge:
-    history_sync:
-      backfill: true
 ```
 
-## Set up Double Puppeting
+### Extending the configuration
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+There are some additional things you may wish to configure about the bridge.
 
-### Method 1: automatically, by enabling Shared Secret Auth
+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.
 
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+## Installing
 
-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.
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-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. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Whatsapp", "initial_device_display_name": "Mautrix-Whatsapp"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
+<!-- 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
 ```
 
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+**Notes**:
 
-- make sure you don't log out the `Mautrix-Whatsapp` device some time in the future, as that would break the Double Puppeting feature
+- 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
 
-You then need to start a chat with `@whatsappbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+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).
+
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/whatsapp/authentication.html).
+
+Approximately in a minute after logging in, the bridge will create portal rooms for recent chats.
+
+**Note**: your linked devices will be logged out if you don’t use your phone for over 14 days (see the official FAQ entry [here](https://faq.whatsapp.com/general/download-and-installation/about-linked-devices)). The bridge will warn you if it doesn't receive any data from the phone over 12 days.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-whatsapp`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_whatsapp_logging_level: 'debug'
+```

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

@@ -0,0 +1,73 @@
+# 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:
+
+```yaml
+matrix_mautrix_wsproxy_enabled: true
+
+matrix_mautrix_androidsms_appservice_token: 'secret token from bridge'
+matrix_mautrix_androidsms_homeserver_token: 'secret token from bridge'
+matrix_mautrix_imessage_appservice_token: 'secret token from bridge'
+matrix_mautrix_imessage_homeserver_token: 'secret token from bridge'
+matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
+```
+
+Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device.
+
+### Adjusting the wsproxy URL (optional)
+
+By tweaking the `matrix_mautrix_wsproxy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Change the default hostname
+matrix_mautrix_wsproxy_hostname: ws.example.com
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+Follow the [mautrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).
+
+## 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,36 +1,46 @@
-# Setting up MX Puppet Discord (optional)
+# 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) bridge 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 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://github.com/matrix-discord/mx-puppet-discord) for you.
+The playbook can install and configure [mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://gitlab.com/mx-puppet/discord/mx-puppet-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-**Note**: we actually use the [Beeper](https://www.beeper.com/)-maintained [fork of mx-puppet-discord](https://gitlab.com/beeper/mx-puppet-monorepo), because `matrix-discord/mx-puppet-discord` is a low-quality and poorly maintained project.
-
-To enable the [Discord](https://discordapp.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Discord](https://discordapp.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_discord_enabled: true
 ```
 
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**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 bot is enabled you need to start a chat with `Discord Puppet Bridge` with
-the handle `@_discordpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
-domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Discord Puppet Bridge` with the handle `@_discordpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Three authentication methods are available, Legacy Token, OAuth and xoxc token.
-See mx-puppet-discord [documentation](https://github.com/matrix-discord/mx-puppet-discord)
-for more information about how to configure the bridge.
+Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-discord [documentation](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) for more information about how to configure the bridge.
 
 Once logged in, send `list` to the bot user to list the available rooms.
 
-Clicking rooms in the list will result in you receiving an invitation to the
-bridged room.
+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,24 +1,37 @@
-# Setting up MX Puppet GroupMe (optional)
+# Setting up MX Puppet GroupMe bridging (optional)
 
-The playbook can install and configure
-[mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) for you.
+The playbook can install and configure [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-To enable the [GroupMe](https://groupme.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [GroupMe](https://groupme.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_groupme_enabled: true
 ```
 
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `GroupMe Puppet Bridge` with
-the handle `@_groupmepuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
-domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `GroupMe Puppet Bridge` with the handle `@_groupmepuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 One authentication method is available.
 
@@ -30,7 +43,6 @@ link <access token>
 
 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.
+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,24 +1,37 @@
-# Setting up mx-puppet-instagram (optional)
+# 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.
+The playbook can install and configure [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) for you.
 
 This allows you to bridge Instagram DirectMessages into Matrix.
 
-To enable the [Instagram](https://www.instagram.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Instagram](https://www.instagram.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_instagram_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
+```
+
+**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 bot is enabled, you need to start a chat with `Instagram Puppet Bridge` with
-the handle `@_instagrampuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
-domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Instagram Puppet Bridge` with the handle `@_instagrampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `link <username> <password>` to the bridge bot to link your instagram account.
 
@@ -32,5 +45,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,30 +1,5 @@
-# Setting up MX Puppet Skype (optional)
+# Setting up MX Puppet Skype bridging (optional, removed)
 
-The playbook can install and configure
-[mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) for you.
+🪦 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.
 
-See the project page to learn what it does and why it might be useful to you.
-
-To enable the [Skype](https://www.skype.com/) bridge just use the following
-playbook configuration:
-
-
-```yaml
-matrix_mx_puppet_skype_enabled: true
-```
-
-
-## Usage
-
-Once the bot is enabled you need to start a chat with `Skype Puppet Bridge` with
-the handle `@_skypepuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
-domain, not the `matrix.` domain).
-
-Send `link <username> <password>` to the bridge bot to link your skype account.
-
-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.
+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,47 +1,51 @@
-# Setting up MX Puppet Slack (optional)
+# 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)
-bridge supported by the playbook.
+**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.
 
-The playbook can install and configure [Beeper](https://www.beeper.com/)-maintained fork of
-[mx-puppet-slack](https://gitlab.com/beeper/mx-puppet-monorepo) for you.
+The playbook can install and configure [mx-puppet-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://gitlab.com/mx-puppet/slack/mx-puppet-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-## Setup
+## Prerequisite
 
-To enable the [Slack](https://slack.com/) bridge:
+Follow the [OAuth credentials](https://gitlab.com/mx-puppet/slack/mx-puppet-slack#option-2-oauth) instructions to create a new Slack app, setting the redirect URL to `https://matrix.example.com/slack/oauth`.
 
-1. Follow the
-   [OAuth credentials](https://github.com/Sorunome/mx-puppet-slack#option-2-oauth)
-   instructions to create a new Slack app, setting the redirect URL to
-   `https://matrix.YOUR_DOMAIN/slack/oauth`.
-2. Update your `vars.yml` with the following:
-    ```yaml
-    matrix_mx_puppet_slack_enabled: true
-    # Client ID must be quoted so YAML does not parse it as a float.
-    matrix_mx_puppet_slack_oauth_client_id: "<SLACK_APP_CLIENT_ID>"
-    matrix_mx_puppet_slack_oauth_client_secret: "<SLACK_APP_CLIENT_SECRET>"
-    ```
-3. Run playbooks with `setup-all` and `start` tags:
-    ```
-    ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
-    ```
+## Adjusting the playbook configuration
+
+To enable the [Slack](https://slack.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_mx_puppet_slack_enabled: true
+# Client ID must be quoted so YAML does not parse it as a float.
+matrix_mx_puppet_slack_oauth_client_id: "<SLACK_APP_CLIENT_ID>"
+matrix_mx_puppet_slack_oauth_client_secret: "<SLACK_APP_CLIENT_SECRET>"
+```
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**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 bot is enabled you need to start a chat with `Slack Puppet Bridge` with
-the handle `@_slackpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
-domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Slack Puppet Bridge` with the handle `@_slackpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Three authentication methods are available, Legacy Token, OAuth and xoxc token.
-See mx-puppet-slack [documentation](https://github.com/Sorunome/mx-puppet-slack)
-for more information about how to configure the bridge.
+Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-slack [documentation](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) for more information about how to configure the bridge.
 
 Once logged in, send `list` to the bot user to list the available rooms.
 
-Clicking rooms in the list will result in you receiving an invitation to the
-bridged room.
+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,32 +1,42 @@
-# Setting up MX Puppet Steam (optional)
+# 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.
+The playbook can install and configure [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/icewind1991/mx-puppet-steam/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-To enable the [Steam](https://steampowered.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Steam](https://steampowered.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_steam_enabled: true
 ```
 
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `Steam Puppet Bridge` with
-the handle `@_steampuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
-domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Steam Puppet Bridge` with the handle `@_steampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Three authentication methods are available, Legacy Token, OAuth and xoxc token.
-See mx-puppet-steam [documentation](https://github.com/icewind1991/mx-puppet-steam)
-for more information about how to configure the bridge.
+Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-steam [documentation](https://github.com/icewind1991/mx-puppet-steam) for more information about how to configure the bridge.
 
 Once logged in, send `list` to the bot user to list the available rooms.
 
-Clicking rooms in the list will result in you receiving an invitation to the
-bridged room.
+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,14 +1,18 @@
-# Setting up MX Puppet Twitter (optional)
+# 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.
 
-The playbook can install and configure
-[mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) for you.
+The playbook can install and configure [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/Sorunome/mx-puppet-twitter/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-To enable the [Twitter](https://twitter.com) bridge, make an app on [developer.twitter.com](https://developer.twitter.com/en/apps)
-and fill out the following playbook configuration.
+## Prerequisite
+
+Make an app on [developer.twitter.com](https://developer.twitter.com/en/apps).
+
+## Adjusting the playbook configuration
+
+To enable the [Twitter](https://twitter.com) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_twitter_enabled: true
@@ -19,18 +23,31 @@ matrix_mx_puppet_twitter_access_token_secret: ''
 matrix_mx_puppet_twitter_environment: ''
 ```
 
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**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 bot is enabled you need to start a chat with `Twitter Puppet Bridge` with
-the handle `@_twitterpuppet_bot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
-domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Twitter Puppet Bridge` with the handle `@_twitterpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 To log in, use `link` and click the link.
 
 Once logged in, send `list` to the bot user to list the available rooms.
 
-Clicking rooms in the list will result in you receiving an invitation to the
-bridged room.
+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

@@ -0,0 +1,103 @@
+# Setting up Postmoogle email bridging (optional)
+
+The playbook can install and configure [Postmoogle](https://github.com/etkecc/postmoogle) for you.
+
+Postmoogle is a bridge you can use to have its bot user forward emails to Matrix rooms. It runs an SMTP email server and allows you to assign mailbox addresses to the rooms.
+
+See the project's [documentation](https://github.com/etkecc/postmoogle/blob/master/README.md) to learn what it does and why it might be useful to you.
+
+## Prerequisites
+
+Open the following ports on your server to be able to receive incoming emails:
+
+  - `25/tcp`: SMTP
+  - `587/tcp`: Submission (TLS-encrypted SMTP)
+
+If you don't open these ports, you will still be able to send emails, but not receive any.
+
+These port numbers are configurable via the `matrix_postmoogle_smtp_host_bind_port` and `matrix_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
+
+## 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:
+
+```yaml
+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 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:
+#
+# matrix_postmoogle_admins:
+#  - '@yourAdminAccount:{{ matrix_domain }}'
+#
+# … unless you've made yourself an admin of all bots/bridges like this:
+#
+# matrix_admin: '@yourAdminAccount:{{ matrix_domain }}'
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-postmoogle/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create a user account of the bridge's bot.
+
+- 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 bridge's bot password (`matrix_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_postmoogle_password` to let the bot know its new password.
+
+## Usage
+
+To use the bridge, invite the `@postmoogle:example.com` bot user into a room you want to use as a mailbox.
+
+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 bot in the room to see the available commands.
+
+You can also refer to the upstream [documentation](https://github.com/etkecc/postmoogle).
+
+## 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-postmoogle`.
+
+### 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

@@ -0,0 +1,59 @@
+# Setting up WeChat bridging (optional)
+
+The playbook can install and configure [matrix-wechat](https://github.com/duo/matrix-wechat) for you, for bridging to [WeChat](https://www.wechat.com/).
+
+See the project's [documentation](https://github.com/duo/matrix-wechat/blob/master/README.md) to learn what it does and why it might be useful to you.
+
+> [!WARNING]
+> This bridge does not work against newer versions of Synapse anymore. See [this issue](https://github.com/duo/matrix-wechat/issues/33). Don't even bother installing it. Unless bridge maintenance is resumed and fixes this issue, we have no choice but to remove it from the playbook.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_wechat_enabled: true
+```
+
+### 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,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 `@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

@@ -0,0 +1,149 @@
+# Setting up Cactus Comments (optional)
+
+The playbook can install and configure the [Cactus Comments](https://cactus.chat) system for you.
+
+Cactus Comments is a **federated comment system** built on Matrix. It respects your privacy, and puts you in control.
+
+See the project's [documentation](https://cactus.chat/docs/getting-started/introduction/) to learn what it does and why it might be useful to you.
+
+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-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).
+
+## 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
+# 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
+```
+
+### Adjusting the Cactus Comments' client URL (optional)
+
+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 `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix to host the client assets at a different location
+# These variables are used only if (`matrix_cactus_comments_client_enabled: true`)
+matrix_cactus_comments_client_hostname: cactus.example.com
+matrix_cactus_comments_client_path_prefix: /
+```
+
+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`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the components.
+
+For `matrix-cactus-comments`, take a look at:
+
+- `roles/custom/matrix-cactus-comments/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+For `matrix-cactus-comments-client`, take a look at:
+
+- `roles/custom/matrix-cactus-comments-client/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**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 component, you need to start a chat with `@bot.cactusbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+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.
+
+Now you are good to go and can embed the comment section on your website!
+
+## Embed Cactus Comments
+
+The official [documentation](https://cactus.chat/docs/getting-started/quick-start/) provides a useful guide to embed Cactus Comments on your website.
+
+After including the JavaScript and CSS asset files, insert a `<div>` where you'd like to display the comment section:
+
+````html
+<div id="comment-section"></div>
+````
+
+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>
+initComments({
+  node: document.getElementById("comment-section"),
+  defaultHomeserverUrl: "https://matrix.example.com:8448",
+  serverName: "example.com",
+  siteName: "YOUR_SITE_NAME_HERE",
+  commentSectionId: "1"
+})
+</script>
+```
+
+### Adjust the domain name for self-hosting
+
+To have the assets served from your homeserver (not from `cactus.chat`), you need to adjust the domain name on the official documentation.
+
+Make sure to replace `example.com` with your base domain before you include the following lines, instead of the one provided by the official documentation:
+
+```html
+<script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
+<link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">
+```
+
+**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,21 +1,67 @@
-# Configuring Cinny (optional)
+# Setting up Cinny (optional)
 
-This playbook can install 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.
-cinny can be installed alongside or instead of Element.
+The playbook can install and configure the [Cinny](https://github.com/ajbura/cinny) Matrix web client for you.
 
-If you'd like cinny to be installed, add the following to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+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).
+
+💡 **Note**: the latest version of Cinny 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:
+
+- [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:
 
 ```yaml
 matrix_client_cinny_enabled: true
 ```
 
-You will also need to add a DNS record so that cinny can be accessed.
-By default cinny will use https://cinny.DOMAIN so you will need to create an CNAME record
-for `cinny`. See [Configuring DNS](configuring-dns.md).
+### Adjusting the Cinny URL (optional)
 
-If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):
+By tweaking the `matrix_client_cinny_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
- matrix_server_fqn_cinny: "app.{{ matrix_domain }}"
+# 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
 ```
+
+After changing the domain, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server.
+
+**Note**: while there is a `matrix_client_cinny_path_prefix` variable for changing the path where Cinny is served, overriding it is [not possible](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path. You'd need to serve Cinny at a dedicated subdomain.
+
+### Extending the configuration
+
+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
+
+After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-client-cinny`.

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

@@ -0,0 +1,135 @@
+# 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/)
+
+## Adjusting DNS records
+
+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`.
+
+When setting, replace `example.com` with your own.
+
+## Adjusting the playbook configuration
+
+### Set the country code for phone number inputs
+
+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:
+
+```yaml
+matrix_client_element_default_country_code: "FR"
+```
+
+### Themes
+
+#### Change the default theme
+
+You can change the default theme from `light` to `dark`. To do so, add the following configuration to your `vars.yml` file:
+
+```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.
+
+#### Define themes manually
+
+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 `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 Element Web.
+matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /element subpath
+matrix_client_element_path_prefix: /element
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the Element domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the 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:
+
+<!-- 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-element`.

docs/configuring-playbook-client-element.md

@@ -1,41 +0,0 @@
-# Configuring Element (optional)
-
-By default, this playbook installs the [Element](https://github.com/vector-im/element-web) Matrix client web application.
-If that's okay, you can skip this document.
-
-
-## Disabling Element
-
-If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
-
-```yaml
-matrix_client_element_enabled: false
-```
-
-
-## Configuring Element settings
-
-The playbook provides some customization variables you could use to change Element's settings.
-
-Their defaults are defined in [`roles/matrix-client-element/defaults/main.yml`](../roles/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/matrix-client-element/templates/config.json.j2`](../roles/matrix-client-element/templates/config.json.j2) template.
-
-**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.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
-
-Alternatively, **if there is no pre-defined variable** for an Element 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's various settings that rarely get used.
-
-- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/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/matrix-client-element/defaults/main.yml`](../roles/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/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
-
-
-## Themes
-
-To change the look of Element, you can define your own themes manually by using the `matrix_client_element__settingDefaults_custom_themes` setting.
-
-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`).
-
-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.
-
-Note that for a custom theme to work well, all Element instances that you use must have the same theme installed.

docs/configuring-playbook-client-hydrogen.md

@@ -1,21 +1,64 @@
-# Configuring Hydrogen (optional)
+# Setting up Hydrogen (optional)
 
-This playbook can install the [Hydrogen](https://github.com/vector-im/hydrogen-web) Matrix web client for you.
-Hydrogen is a lightweight web client that supports mobile and legacy web browsers.
-Hydrogen can be installed alongside or instead of Element.
+The playbook can install and configure the [Hydrogen](https://github.com/element-hq/hydrogen-web) Matrix web client for you.
 
-If you'd like Hydrogen to be installed, add the following to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+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:
 
 ```yaml
 matrix_client_hydrogen_enabled: true
 ```
 
-You will also need to add a DNS record so that Hydrogen can be accessed. 
-By default Hydrogen will use https://hydrogen.DOMAIN so you will need to create an CNAME record
-for `hydrogen`. See [Configuring DNS](configuring-dns.md).
+### Adjusting the Hydrogen URL (optional)
 
-If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):
+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 `vars.yml` file:
 
 ```yaml
- matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}"
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Hydrogen.
+matrix_client_hydrogen_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /hydrogen subpath
+matrix_client_hydrogen_path_prefix: /hydrogen
 ```
+
+After changing the domain, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the 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:
+
+<!-- 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-hydrogen`.

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

@@ -0,0 +1,132 @@
+# Setting up SchildiChat Web (optional)
+
+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.
+
+💡 **Note**: the latest version of SchildiChat 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:
+
+- [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:
+
+```yaml
+matrix_client_schildichat_enabled: true
+```
+
+### Set the country code for phone number inputs
+
+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:
+
+```yaml
+matrix_client_schildichat_default_country_code: "FR"
+```
+
+### Themes
+
+#### Change the default theme
+
+You can change the default theme from `light` to `dark`. To do so, add the following configuration to your `vars.yml` file:
+
+```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.
+
+#### Define themes manually
+
+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 `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 SchildiChat Web.
+matrix_client_schildichat_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /schildichat subpath
+matrix_client_schildichat_path_prefix: /schildichat
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the SchildiChat 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.
+
+### 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:
+
+<!-- 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-schildichat`.

docs/configuring-playbook-conduit.md

@@ -0,0 +1,79 @@
+# Configuring Conduit (optional)
+
+The playbook can install and configure the [Conduit](https://conduit.rs) Matrix server for you.
+
+See the project's [documentation](https://docs.conduit.rs/) 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**: 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 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))
+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)
+6. You can now use your server safely. Additional users can be created by messaging the internal Conduit bot
+
+## Configuring bridges / appservices
+
+For other homeserver implementations (like Synapse and Dendrite), the playbook automatically registers appservices (for bridges, bots, etc.) with the homeserver.
+
+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:
+
+    @conduit:example.com: register-appservice
+    ```
+    as_token: <token>
+    de.sorunome.msc2409.push_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-conduit`.

docs/configuring-playbook-conduwuit.md

@@ -0,0 +1,97 @@
+# 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
+
+## 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
+    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-dendrite.md

@@ -0,0 +1,77 @@
+# Configuring Dendrite (optional)
+
+The playbook can install and configure the [Dendrite](https://github.com/element-hq/dendrite) Matrix server for you.
+
+See the project's [documentation](https://element-hq.github.io/dendrite/) 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.
+
+> [!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 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
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the server.
+
+Take a look at:
+
+- `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
+
+For example, to override some Dendrite settings, add the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_dendrite_configuration_extension_yaml: |
+  # 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
+
+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.
+
+## 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,98 +1,129 @@
-# Setting up Dimension (optional)
+# 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**: 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_synapse_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).
+The playbook can install and configure the [Dimension](https://dimension.t2bot.io) integration manager for you.
 
+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
 
-The `dimension.<your-domain>` DNS record must be created. See [Configuring your DNS server](configuring-dns.md) on how to set up DNS record correctly.
+### 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.
 
-## Enable
+### Install Matrix services
 
-[Dimension integrations manager](https://dimension.t2bot.io) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+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 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
 
-## Define admin users
-
-These users can modify the integrations this Dimension supports. 
-Add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/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:
-  - "@user1:{{ matrix_domain }}"
-  - "@user2:{{ matrix_domain }}"
+  - "@alice:{{ matrix_domain }}"
+  - "@bob:{{ matrix_domain }}"
 ```
 
-The admin interface is accessible within Element by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element by the "Add widgets, bridges, & bots" link in the room information.
+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**.
+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.
 
-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 one of two options:
-
-*Through an interactive login*:
-
-1. In a private browsing session (incognito window), open Element.
-1. Log in with the `dimension` user and its password.
-1. Set the display name and avatar, if required.
-1. In the settings page choose "Help & About", scroll down to the bottom and expand the `Access Token` section.
-1. Copy the access token to your configuration.
-1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
-
-*With CURL*
-
-```
-curl -X POST --header 'Content-Type: application/json' -d '{
-    "identifier": { "type": "m.id.user", "user": "YourDimensionUsername" },
-    "password": "YourDimensionPassword",
-    "type": "m.login.password"
-}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
-```
-*Change `YourDimensionUsername`, `YourDimensionPassword`, and `YOURDOMAIN` accordingly.*
-
-**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.<your-domain>/vars.yml`):
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
-matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Dimension.
+matrix_dimension_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /dimension subpath
+# matrix_dimension_path_prefix: /dimension
 ```
 
-For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens).
+After changing the domain, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
 
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
-## Installation
+**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.
 
-After these variables have been set, please run the following command to re-run setup and to restart Dimension:
+### 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
+
+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
 ```
 
-After Dimension has been installed you may need to log out and log back in for it to pick up the new integrations manager. Then you can access integrations in Element 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.
+**Notes**:
 
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-## Jitsi domain
+  `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.
 
-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.
+## Usage
 
-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, go to *Manage Integrations* &rightarrow; *Settings* &rightarrow; *Widgets* &rightarrow; *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
+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.
 
+### Set up a Jitsi widget
 
-## Additional features
+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.
 
-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/matrix-dimension/defaults/main.yml) of the Dimension component.
+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.
 
-You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).
+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.
+
+## 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,27 +1,55 @@
-# Dynamic DNS
+# Setting up Dynamic DNS (optional)
 
-## Setup
+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.
 
-Most cloud providers / ISPs will charge you extra for a static IP address. If you're
-not hosting a highly reliable homeserver you can workaround this via dynamic DNS. To
-set this up, you'll need to get the username/password from your DNS provider. For
-google domains, this process is described [here](https://support.google.com/domains/answer/6147083).
-After you've gotten the proper credentials you can add the following config to your `inventory/host_vars/matrix.DOMAIN/vars.yml`:
+Most cloud providers / ISPs will charge you extra for a static IP address. If you're not hosting a highly reliable homeserver you can workaround this via dynamic DNS.
+
+## Prerequisite
+
+You'll need to get a username and password from your DNS provider. Please consult with the provider about how to retrieve them.
+
+## Adjusting the playbook configuration
+
+To enable dynamic DNS, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_dynamic_dns_enabled: true
 
 matrix_dynamic_dns_domain_configurations:
-  - provider: domains.google.com
+  - provider: example.net
     protocol: dyndn2
-    username: XXXXXXXXXXXXXXXX
-    password: XXXXXXXXXXXXXXXX
+    username: YOUR_USERNAME_HERE
+    password: YOUR_PASSWORD_HERE
     domain: "{{ matrix_domain }}"
 ```
 
+### 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:
+
+<!-- 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.
 
 ## Additional Reading
 
 Additional resources:
 
 - https://matrix.org/docs/guides/free-small-matrix-server
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-dynamic-dns`.

docs/configuring-playbook-email.md

@@ -2,54 +2,60 @@
 
 By default, this playbook sets up an [Exim](https://www.exim.org/) email server through which all Matrix services send emails.
 
-The email server would attempt to deliver emails directly to their final destination.
-This may or may not work, depending on your domain configuration (SPF settings, etc.)
+The email server would attempt to deliver emails directly to their final destination. This may or may not work, depending on your domain configuration (SPF settings, etc.)
 
-By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `matrix_mailer_sender_address` playbook variable).
+By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.
 
-**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.   
+> [!WARNING]
+> On some cloud providers (Google Cloud, etc.), [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible. You will need to [relay email through another SMTP server](#relaying-email-through-another-smtp-server).
 
+💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.
 
 ## Firewall settings
 
 No matter whether you send email directly (the default) or you relay email through another host (see how below), you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).
 
+## Adjusting the playbook configuration
 
-## Relaying email through another SMTP server
+### Relaying email through another SMTP server
 
-If you'd like to relay email through another SMTP server, feel free to redefine a few playbook variables.
-Example:
+If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
-matrix_mailer_sender_address: "another.sender@example.com"
-matrix_mailer_relay_use: true
-matrix_mailer_relay_host_name: "mail.example.com"
-matrix_mailer_relay_host_port: 587
-matrix_mailer_relay_auth: true
-matrix_mailer_relay_auth_username: "another.sender@example.com"
-matrix_mailer_relay_auth_password: "some-password"
+exim_relay_sender_address: "another.sender@example.com"
+exim_relay_relay_use: true
+exim_relay_relay_host_name: "mail.example.com"
+exim_relay_relay_host_port: 587
+exim_relay_relay_auth: true
+exim_relay_relay_auth_username: "another.sender@example.com"
+exim_relay_relay_auth_password: "PASSWORD_FOR_THE_RELAY_HERE"
 ```
 
 **Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
 
+### Sending emails using Sendgrid
 
-### Configuations for sending emails using Sendgrid
-An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `matrix_mailer_sender_address`.
+An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/). Its free tier allows for up to 100 emails per day to be sent.
 
-The only other thing you need to change is the `matrix_mailer_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
-
-Note that the `matrix_mailer_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
+To set it up, add the following configuration to your `vars.yml` file (adapt to your needs):
 
 ```yaml
-matrix_mailer_sender_address: "arbitrary@email.com"
-matrix_mailer_relay_use: true
-matrix_mailer_relay_host_name: "smtp.sendgrid.net"
-matrix_mailer_relay_host_port: 587
-matrix_mailer_relay_auth: true
-matrix_mailer_relay_auth_username: "apikey"
-matrix_mailer_relay_auth_password: "<your api key password>" 
+exim_relay_sender_address: "example@example.org"
+exim_relay_relay_use: true
+exim_relay_relay_host_name: "smtp.sendgrid.net"
+exim_relay_relay_host_port: 587
+exim_relay_relay_auth: true
+
+# This needs to be literally the string "apikey". It is always the same for Sendgrid.
+exim_relay_relay_auth_username: "apikey"
+
+# You can generate the API key password at this URL: https://app.sendgrid.com/settings/api_keys
+# The password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
+exim_relay_relay_auth_password: "YOUR_API_KEY_PASSWORD_HERE"
 ```
 
 ## Troubleshooting
 
-If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-mailer`.
+If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs.
+
+To do so, log in to the server with SSH and run `journalctl -f -u matrix-exim-relay`.

docs/configuring-playbook-email2matrix.md

@@ -1,80 +1,138 @@
-# Setting up Email2Matrix (optional)
+# Setting up Email2Matrix (optional, deprecated)
 
-The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you.
+**Note**: this component has been deprecated. We recommend not bothering with installing it. While not a 1:1 replacement, the author suggests taking a look at [Postmoogle](https://github.com/etkecc/postmoogle) as a replacement, which can also be installed using [this playbook](configuring-playbook-bridge-postmoogle.md). Consider using that component instead of this one.
+
+The playbook can install and configure [Email2Matrix](https://github.com/devture/email2matrix) for you.
 
 See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
 
-
 ## Preparation
 
 ### Port availability
 
 Ensure that port 25 is available on your Matrix server and open in your firewall.
+
 If you have `postfix` or some other email server software installed, you may need to manually remove it first (unless you need it, of course).
 
 If you really need to run an email server on the Matrix machine for other purposes, it may be possible to run Email2Matrix on another port (with a configuration like `matrix_email2matrix_smtp_host_bind_port: "127.0.0.01:2525"`) and have your other email server relay messages there.
+
 For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/), see [here](https://github.com/devture/email2matrix/blob/master/docs/setup_with_postfix.md).
 
-### Creating a user
+### Register a dedicated Matrix user (optional, recommended)
 
-Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side.
-Refer to [Registering users](registering-users.md) for ways to do that. A regular (non-admin) user works best.
+We recommend that you create a dedicated Matrix user for Email2Matrix.
 
-### Creating a shared room
+Generate a strong password for the user. You can create one with a command like `pwgen -s 64 1`.
 
-After creating a sender user, you should create one or more Matrix rooms that you share with that user.
-It doesn't matter who creates and owns the rooms and who joins later (you or the sender user).
+You can use the playbook to [register a new user](registering-users.md):
 
-What matters is that both you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there.
-Inviting additional people to the room is okay too.
-
-Take note of each room's room id (different clients show the room id in a different place).
-You'll need the room id when doing [Configuration](#configuration) below.
-
-
-### Obtaining an access token for the sender user
-
-In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it.
-
-To do this, you can execute a command like this:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "email2matrix" }, "password": "MATRIX_PASSWORD_FOR_THE_USER", "type": "m.login.password", "device_id": "Email2Matrix", "initial_device_display_name": "Email2Matrix"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
+```sh
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=email2matrix password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user
 ```
 
-Take note of the `access_token` value. You'll need the access token when doing [Configuration](#configuration) below.
+Take note of the user's ID as it needs to be specified as `MatrixUserId` on your `inventory/host_vars/matrix.example.com/vars.yml` file later.
 
+### Obtain an access token
 
-## Configuration
+Email2Matrix requires an access token for the sender user to be able to send messages to the room. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
-After doing the preparation steps above, adjust your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration like this:
+> [!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 sender user manually
+
+ℹ️ **Email2Matrix does not accept room invitations automatically**. To deliver messages to rooms, the sender user must be joined to all rooms manually.
+
+For each new room you would like the user to deliver messages to, invite the user to the room.
+
+Then, log in as the sender user using any Matrix client of your choosing, accept the room invitation from the user's account.
+
+Make sure that you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there, then log out.
+
+Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below.
+
+## Adjusting DNS records
+
+To increase the chances that incoming emails reach your server, you can set up a `MX` record for `matrix.example.com` that looks like this:
+
+| Type | Host     | Priority | Weight | Port | Target                             |
+|------|----------|----------|--------|------|------------------------------------|
+| MX   | `matrix` | 10       | 0      | -    | `matrix.example.com`               |
+
+## Adjusting the playbook configuration
+
+To enable Email2Matrix, add the following configuration to your `vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE` and `ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE` with the ones created [above](#obtain-an-access-token).
 
 ```yaml
 matrix_email2matrix_enabled: true
 
+# You need at least 1 mailbox.
 matrix_email2matrix_matrix_mappings:
-  - MailboxName: "my-mailbox"
-    MatrixRoomId: "!someRoom:DOMAIN"
-    MatrixHomeserverUrl: "https://matrix.DOMAIN"
-    MatrixUserId: "@email2matrix:DOMAIN"
-    MatrixAccessToken: "ACCESS_TOKEN_GOES_HERE"
+  - MailboxName: "mailbox1"
+    MatrixRoomId: "!qporfwt:{{ matrix_domain }}"
+    MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
+    MatrixUserId: "@email2matrix1:{{ matrix_domain }}"
+    MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE"
     IgnoreSubject: false
     IgnoreBody: false
     SkipMarkdown: false
 
-  - MailboxName: "my-mailbox2"
-    MatrixRoomId: "!anotherRoom:DOMAIN"
-    MatrixHomeserverUrl: "https://matrix.DOMAIN"
-    MatrixUserId: "@email2matrix:DOMAIN"
-    MatrixAccessToken: "ACCESS_TOKEN_GOES_HERE"
+  - MailboxName: "mailbox2"
+    MatrixRoomId: "!aaabaa:{{ matrix_domain }}"
+    MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
+    MatrixUserId: "@email2matrix2:{{ matrix_domain }}"
+    MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE"
     IgnoreSubject: true
     IgnoreBody: false
     SkipMarkdown: true
 ```
 
-You can also set `MatrixHomeserverUrl` to `http://matrix-synapse:8008`, instead of the public `https://matrix.DOMAIN`.
-However, that's more likely to break in the future if you switch to another server implementation than Synapse.
+where:
 
-Re-run the playbook (`--tags=setup-email2matrix,start`) and try sending an email to `my-mailbox@matrix.DOMAIN`.
+* MailboxName — local-part of the email address, through which emails are bridged to the room whose ID is defined with MatrixRoomId
+* MatrixRoomId — internal ID of the room, to which received emails are sent as Matrix message
+* MatrixHomeserverUrl — URL of your Matrix homeserver, through which to send Matrix messages. You can also set `MatrixHomeserverUrl` to the container URL where your homeserver's Client-Server API lives by using the `{{ matrix_addons_homeserver_client_api_url }}` variable
+* MatrixUserId — the full ID of the sender user which sends bridged messages to the room. On this configuration it is `@email2matrix1:example.com` and `@email2matrix2:example.com` (where `example.com` is your base domain, not the `matrix.` domain)
+* MatrixAccessToken — sender user's access token
+* IgnoreSubject — if set to "true", the subject is not bridged to Matrix
+* IgnoreBody — if set to "true", the message body is not bridged to Matrix
+* SkipMarkdown — if set to "true", emails are bridged as plain text Matrix message instead of Markdown (actually HTML)
+
+Refer to the official documentation [here](https://github.com/devture/email2matrix/blob/master/docs/configuration.md).
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-email2matrix/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+**Notes**:
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-service email2matrix` or `just setup-all`
+
+  `just install-service email2matrix` 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.
+
+- After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected.
+
+## 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-email2matrix`.
+
+### 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_email2matrix_misc_debug: true
+```

docs/configuring-playbook-etherpad.md

@@ -1,48 +1,123 @@
 # Setting up Etherpad (optional)
 
-[Etherpad](https://etherpad.org) is is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io)
+The playbook can install and configure [Etherpad](https://etherpad.org) for you.
+
+Etherpad is an open source collaborative text editor. It can not only be integrated with Element clients ([Element Web](configuring-playbook-client-element-web.md)/Desktop, Android and iOS) as a widget, but also be used as standalone web app.
 
 When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
 
-## Prerequisites
+## Adjusting DNS records
 
-For the self-hosted Etherpad instance to be available to your users, you must first enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
+By default, this playbook installs Etherpad on the `etherpad.` subdomain (`etherpad.example.com`) and requires you to create a CNAME record for `etherpad`, which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+## Adjusting the playbook configuration
+
+To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+etherpad_enabled: true
+
+# Uncomment and adjust this part if you'd like to enable the admin web UI
+# etherpad_admin_username: YOUR_USERNAME_HERE
+# etherpad_admin_password: YOUR_PASSWORD_HERE
+```
+
+### Adjusting the Etherpad URL (optional)
+
+By tweaking the `etherpad_hostname` and `etherpad_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 Etherpad.
+etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /etherpad subpath
+etherpad_path_prefix: /etherpad
+```
+
+After changing the domain, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+### Configure the default text (optional)
+
+You can also edit the default text on a new pad with the variable `etherpad_default_pad_text`.
+
+To do so, add the following configuration to your `vars.yml` file (adapt to your needs):
+
+```yaml
+# Note: the whole text (all of its belonging lines) under the variable needs to be indented with 2 spaces.
+etherpad_default_pad_text: |
+  Welcome to Etherpad!
+
+  This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!
+
+  Get involved with Etherpad at https://etherpad.org
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- [etherpad role](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad)'s [`defaults/main.yml`](https://github.com/mother-of-all-self-hosting/ansible-role-etherpad/blob/main/defaults/main.yml) for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `etherpad_configuration_extension_json` variable
 
 ## Installing
 
-[Etherpad](https://etherpad.org) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```yaml
-matrix_etherpad_enabled: true
+<!-- 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
 ```
 
-## Set Dimension default to the self-hosted Etherpad
+**Notes**:
 
-The Dimension administrator users can configure the default URL template. The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab. Replace `scalar.vector.im` with your own Dimension domain.
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the Etherpad admin user (`etherpad_admin_username`).
 
-### Removing the integrated Etherpad chat
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
-Example: `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`
+  `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.
 
-### Etherpad Admin access (optional)
+- If you change the Etherpad admin user's password (`etherpad_admin_password` in your `vars.yml` file) subsequently, the admin user's credentials on the homeserver won't be updated automatically. If you'd like to change the admin user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `etherpad_admin_password` to let the admin user know its new password.
 
-Etherpad comes with a admin web-UI which is disabled by default. You can enable it by setting a username and password in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+## Usage
 
-```yaml
-matrix_etherpad_admin_username: admin
-matrix_etherpad_admin_password: some-password
-```
+The Etherpad UI should be available at `https://etherpad.example.com`, while the admin UI (if enabled) should then be available at `https://etherpad.example.com/admin`.
 
-The admin web-UI should then be available on: `https://dimension.<your-domain>/etherpad/admin`
+If you've [decided on another hostname or path-prefix](#adjusting-the-etherpad-url-optional) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before using it.
 
 ### Managing / Deleting old pads
 
-If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above.
+If you want to manage and remove old unused pads from Etherpad, you will first need to create the Etherpad admin user as described above.
 
-Then from the plugin manager page (`https://dimension.<your-domain>/etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
+After logging in to the admin web UI, go to the plugin manager page, and install the `adminpads2` plugin.
 
-## Known issues
+Once the plugin is installed, you should have a "Manage pads" section in the UI.
 
-If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.
-`$roomId_$padName` can end up being longer than 50 characters. You can avoid having this problem by altering the template so it only contains the three word random identifier `$padName`.
+### Integrating a Etherpad widget in a room
+
+**Note**: this is how it works in Element Web. It might work quite similar with other clients:
+
+To integrate a standalone Etherpad in a room, create your pad by visiting `https://etherpad.example.com`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` 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-etherpad`.
+
+### 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
+etherpad_configuration_extension_json: |
+ {
+  "loglevel": "DEBUG",
+ }
+```

docs/configuring-playbook-external-postgres.md

@@ -1,16 +1,13 @@
 # Using an external PostgreSQL server (optional)
 
-By default, this playbook would set up a PostgreSQL database server on your machine, running in a Docker container.
-If that's alright, you can skip this.
+By default, this playbook would set up a PostgreSQL database server on your machine, running in a Docker container. If that's okay, you can skip this document.
 
-If you'd like to use an external PostgreSQL server that you manage, you can edit your configuration file  (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
+**Note**: using **an external Postgres server is currently [not very seamless](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1682#issuecomment-1061461683) when it comes to enabling various other playbook services** — you will need to create a new database/credentials for each service and to point each service to its corresponding database using custom `vars.yml` configuration. **For the best experience with the playbook, stick to using the integrated Postgres server**.
 
-**NOTE**: using **an external Postgres server is currently [not very seamless](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1682#issuecomment-1061461683) when it comes to enabling various other playbook services** - you will need to create a new database/credentials for each service and to point each service to its corresponding database using custom `vars.yml` configuration. **For the best experience with the playbook, stick to using the integrated Postgres server**.
-
-If you'd like to use an external Postgres server, use a custom `vars.yml` configuration like this:
+If you'd like to use an external Postgres server that you manage, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
-matrix_postgres_enabled: false
+postgres_enabled: false
 
 # Rewire Synapse to use your external Postgres server
 matrix_synapse_database_host: "your-postgres-server-hostname"
@@ -20,11 +17,10 @@ matrix_synapse_database_database: "your-postgres-server-database-name"
 
 # Rewire any other service (each `matrix-*` role) you may wish to use to use your external Postgres server.
 # Each service expects to have its own dedicated database on the Postgres server
-# and uses its own variable names (see `roles/matrix-*/defaults/main.yml) for configuring Postgres connectivity.
+# and uses its own variable names (see `roles/custom/matrix-*/defaults/main.yml`) for configuring Postgres connectivity.
 ```
 
-The database (as specified in `matrix_synapse_database_database`) must exist and be accessible with the given credentials.
-It must be empty or contain a valid Synapse database. If empty, Synapse would populate it the first time it runs.
+The database (as specified in `matrix_synapse_database_database`) must exist and be accessible with the given credentials. It must be empty or contain a valid Synapse database. If empty, Synapse would populate it the first time it runs.
 
 **Note**: the external server that you specify in `matrix_synapse_database_host` must be accessible from within the `matrix-synapse` Docker container (and possibly other containers too). This means that it either needs to be a publicly accessible hostname or that it's a hostname on the same Docker network where all containers installed by this playbook run (a network called `matrix` by default). Using a local PostgreSQL instance on the host (running on the same machine, but not in a container) is not possible.
 

docs/configuring-playbook-federation.md

@@ -1,39 +1,37 @@
 # Controlling Matrix federation (optional)
 
-By default, your server federates with the whole Matrix network.
-That is, people on your server can communicate with people on any other Matrix server.
+By default, your server federates with the whole Matrix network. That is, people on your server can communicate with people on any other Matrix server.
 
+**Note**: 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` and set up [server delegation](howto-server-delegation.md) / redirection. Without a proper configuration, your server will effectively not be part of the Matrix network. If you find your server is not federated, make sure to [check whether services work](maintenance-and-troubleshooting.md#how-to-check-if-services-work) and your server is properly delegated.
 
 ## Federating only with select servers
 
-To make your server only federate with servers of your choosing, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+To make your server only federate with servers of your choosing, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_federation_domain_whitelist:
 - example.com
-- another.com
+- example.net
 ```
 
 If you wish to disable federation, you can do that with an empty list (`[]`), or better yet by completely disabling federation (see below).
 
-
 ## Exposing the room directory over federation
 
 By default, your server's public rooms directory is not exposed to other servers via federation.
 
-If you wish to expose it, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+To expose it, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_synapse_allow_public_rooms_over_federation: true
 ```
 
-
 ## Disabling federation
 
-To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+To completely disable federation, isolating your server from the rest of the Matrix network, add the following configuration to your `vars.yml` file:
 
 ```yaml
-matrix_synapse_federation_enabled: false
+matrix_homeserver_federation_enabled: false
 ```
 
 With that, your server's users will only be able to talk among themselves, but not to anyone who is on another server.
@@ -41,20 +39,22 @@ With that, your server's users will only be able to talk among themselves, but n
 **Disabling federation does not necessarily disable the federation port** (`8448`). Services like [Dimension](configuring-playbook-dimension.md) and [ma1sd](configuring-playbook-ma1sd.md) normally rely on `openid` APIs exposed on that port. Even if you disable federation and only if necessary, we may still be exposing the federation port and serving the `openid` APIs there. To override this and completely disable Synapse's federation port use:
 
 ```yaml
+matrix_homeserver_federation_enabled: false
+
 # This stops the federation port on the Synapse side (normally `matrix-synapse:8048` on the container network).
 matrix_synapse_federation_port_enabled: false
 
-# This removes the `8448` virtual host from the matrix-nginx-proxy reverse-proxy server.
-matrix_nginx_proxy_proxy_matrix_federation_api_enabled: false
+# This stops the federation port on the synapse-reverse-proxy-companion side (normally `matrix-synapse-reverse-proxy-companion:8048` on the container network).
+matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
 ```
 
 ## Changing the federation port from 8448 to a different port to use a CDN that only accepts 443/80 ports
 
 Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
 
-The following changes in the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
+To make it possible to proxy the federation through a CDN such as CloudFlare or any other, add the following configuration to your `vars.yml` file:
 
-```
+```yaml
 matrix_synapse_http_listener_resource_names: ["client","federation"]
 # Any port can be used but in this case we use 443
 matrix_federation_public_port: 443

docs/configuring-playbook-jitsi.md

@@ -1,164 +1,408 @@
-# Jitsi
+# Setting up the Jitsi video-conferencing platform (optional)
 
-The playbook can install the [Jitsi](https://jitsi.org/) video-conferencing platform and integrate it with [Element](configuring-playbook-client-element.md).
+The playbook can install and configure the [Jitsi](https://jitsi.org/) video-conferencing platform for you.
 
-Jitsi installation is **not enabled by default**, because it's not a core component of Matrix services.
+Jitsi can not only be integrated with Element clients ([Element Web](configuring-playbook-client-element-web.md)/Desktop, Android and iOS) as a widget, but also be used as standalone web app.
 
-The setup done by the playbook is very similar to [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the documentation there for many of the options here.
+See the project's [documentation](https://jitsi.github.io/handbook/) to learn what it does and why it might be useful to you.
 
+**Note**: the configuration by the playbook is similar to the one by [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the official documentation for Docker deployment [here](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/).
 
 ## Prerequisites
 
-Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record. See [Configuring DNS](configuring-dns.md).
+You may need to open the following ports to your server:
 
-You may also need to open the following ports to your server:
+- `4443/tcp` — RTP media fallback over TCP
+- `10000/udp` — RTP media over UDP. Depending on your firewall/NAT configuration, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
 
-- `4443/tcp` - RTP media fallback over TCP
-- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/matrix-jitsi/defaults/main.yml)).
+## Adjusting DNS records
 
+By default, this playbook installs Jitsi on the `jitsi.` subdomain (`jitsi.example.com`) and requires you to create a CNAME record for `jitsi`, which targets `matrix.example.com`.
 
-## Installation
+When setting, replace `example.com` with your own.
 
-Add this to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
+## Adjusting the playbook configuration
+
+To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_jitsi_enabled: true
-
-# Run `bash inventory/scripts/jitsi-generate-passwords.sh` to generate these passwords,
-# or define your own strong passwords manually.
-matrix_jitsi_jicofo_auth_password: ""
-matrix_jitsi_jvb_auth_password: ""
-matrix_jitsi_jibri_recorder_password: ""
-matrix_jitsi_jibri_xmpp_password: ""
+jitsi_enabled: true
 ```
 
+### Adjusting the Jitsi URL (optional)
 
-## (Optional) Configure Jitsi authentication and guests mode
+By tweaking the `jitsi_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
 
-By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.
-
-If you're fine with such an open Jitsi instance, please skip to [Apply changes](#apply-changes).
-
-If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow this step to enable Jitsi's authentication and guests mode. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms.
-
-Add these lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
+Example additional configuration for your `vars.yml` file:
 
 ```yaml
-matrix_jitsi_enable_auth: true
-matrix_jitsi_enable_guests: true
-matrix_jitsi_prosody_auth_internal_accounts:
-  - username: "jitsi-moderator"
-    password: "secret-password"
-  - username: "another-user"
-    password: "another-password"
+# Change the default hostname
+jitsi_hostname: call.example.com
 ```
 
-**Caution:** Accounts added here and subsquently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook.
+After changing the domain, **you may need to adjust your DNS** records to point the Jitsi domain to the Matrix server.
 
-**If you get an error** like this: "Error: Account creation/modification not supported.", it's likely that you had previously installed Jitsi without auth/guest support. In such a case, you should look into [Rebuilding your Jitsi installation](#rebuilding-your-jitsi-installation).
+### Configure Jitsi authentication and guests mode (optional)
 
+By default the Jitsi instance does not require for anyone to log in, and is open to use without an account. To control who is allowed to start meetings on your Jitsi instance, you'd need to enable Jitsi's authentication and optionally guests mode.
 
-### (Optional) LDAP authentication
+Authentication type must be one of them: `internal` (default), `jwt`, `matrix` or `ldap`. Currently, only `internal`, `matrix` and `ldap` mechanisms are supported by the [Jitsi role](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi).
 
-The default authentication mode of Jitsi is `internal`, however LDAP is also supported. An example LDAP configuration could be:
+With authentication enabled, all meetings have to be started by a registered user. After the meeting is started by that user, then guests are free to join. If the registered user is not yet present, the guests are put on hold in individual waiting rooms.
+
+**Note**: authentication is not tested by the playbook's self-checks. We therefore recommend that you would make sure by yourself that authentication is configured properly. To test it, start a meeting at `jitsi.example.com` on your browser.
+
+#### Authenticate using Jitsi accounts: Auth-Type `internal` (recommended)
+
+The default authentication mechanism is `internal` auth, which requires a Jitsi account to have been configured. This is a recommended method, as it also works in federated rooms.
+
+To enable authentication with a Jitsi account, add the following configuration to your `vars.yml` file. Make sure to replace `USERNAME_…` and `PASSWORD_…` with your own values.
 
 ```yaml
-matrix_jitsi_enable_auth: true
-matrix_jitsi_auth_type: ldap
-matrix_jitsi_ldap_url: "ldap://ldap.DOMAIN"
-matrix_jitsi_ldap_base: "OU=People,DC=DOMAIN
-#matrix_jitsi_ldap_binddn: ""
-#matrix_jitsi_ldap_bindpw: ""
-matrix_jitsi_ldap_filter: "uid=%u"
-matrix_jitsi_ldap_auth_method: "bind"
-matrix_jitsi_ldap_version: "3"
-matrix_jitsi_ldap_use_tls: true
-matrix_jitsi_ldap_tls_ciphers: ""
-matrix_jitsi_ldap_tls_check_peer: true
-matrix_jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
-matrix_jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
-matrix_jitsi_ldap_start_tls: false
+jitsi_enable_auth: true
+jitsi_enable_guests: true
+jitsi_prosody_auth_internal_accounts:
+  - username: "USERNAME_FOR_THE_FIRST_USER_HERE"
+    password: "PASSWORD_FOR_THE_FIRST_USER_HERE"
+  - username: "USERNAME_FOR_THE_SECOND_USER_HERE"
+    password: "PASSWORD_FOR_THE_SECOND_USER_HERE"
+```
+
+**Note**: as Jitsi account removal function is not integrated into the playbook, these accounts will not be able to be removed from the Prosody server automatically, even if they are removed from your `vars.yml` file subsequently.
+
+#### Authenticate using Matrix OpenID: Auth-Type `matrix`
+
+> [!WARNING]
+> This breaks the Jitsi instance on federated rooms probably and does not allow sharing conference links with guests.
+
+This authentication method requires [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service), which can be installed using this [playbook](configuring-playbook-user-verification-service.md). It verifies against Matrix openID, and requires a user-verification-service to run.
+
+To enable authentication with Matrix OpenID, add the following configuration to your `vars.yml` file:
+
+```yaml
+jitsi_enable_auth: true
+jitsi_auth_type: matrix
+matrix_user_verification_service_enabled: true
+```
+
+For more information see also [https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification](https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification).
+
+#### Authenticate using LDAP: Auth-Type `ldap`
+
+To enable authentication with LDAP, add the following configuration to your `vars.yml` file (adapt to your needs):
+
+```yaml
+jitsi_enable_auth: true
+jitsi_auth_type: ldap
+jitsi_ldap_url: "ldap://ldap.example.com"
+jitsi_ldap_base: "OU=People,DC=example.com"
+#jitsi_ldap_binddn: ""
+#jitsi_ldap_bindpw: ""
+jitsi_ldap_filter: "uid=%u"
+jitsi_ldap_auth_method: "bind"
+jitsi_ldap_version: "3"
+jitsi_ldap_use_tls: true
+jitsi_ldap_tls_ciphers: ""
+jitsi_ldap_tls_check_peer: true
+jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
+jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
+jitsi_ldap_start_tls: false
 ```
 
 For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
 
+### Configure `JVB_ADVERTISE_IPS` for running behind NAT or on a LAN environment (optional)
 
-## (Optional) Making your Jitsi server work on a LAN
+When running Jitsi in a LAN environment, or on the public Internet via NAT, the `JVB_ADVERTISE_IPS` enviornment variable should be set.
 
-By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
+This variable allows to control which IP addresses the JVB will advertise for WebRTC media traffic. It is necessary to set it regardless of the use of a reverse proxy, since it's the IP address that will receive the media (audio / video) and not HTTP traffic, hence it's oblivious to the reverse proxy.
 
-The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://github.com/jitsi/docker-jitsi-meet#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `DOCKER_HOST_ADDRESS` in enviornment variable to make it work.
+If your users are coming in over the Internet (and not over LAN), this will likely be your public IP address. If this is not set up correctly, calls will crash when more than two users join a meeting.
 
-Here is how to do it in the playbook.
-
-Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
+To set the variable, add the following configuration to your `vars.yml` file. Make sure to replace `LOCAL_IP_ADDRESS_OF_THE_HOST_HERE` with a proper value.
 
 ```yaml
-matrix_jitsi_jvb_container_extra_arguments:
-  - '--env "DOCKER_HOST_ADDRESS=<Local IP adress of the host>"'
+jitsi_jvb_container_extra_arguments:
+  - '--env "JVB_ADVERTISE_IPS=LOCAL_IP_ADDRESS_OF_THE_HOST_HERE"'
 ```
 
-## (Optional) Fine tune Jitsi
+Check [the official documentation](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/#running-behind-nat-or-on-a-lan-environment) for more details about it.
 
-Sample **additional** `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration to save up resources (explained below):
+### Set a maximum number of participants on a Jitsi conference (optional)
+
+You can set a maximum number of participants allowed to join a Jitsi conference. By default the number is not specified.
+
+To set it, add the following configuration to your `vars.yml` file (adapt to your needs):
 
 ```yaml
-matrix_jitsi_web_custom_config_extension: |
+jitsi_prosody_max_participants: 4 # example value
+```
+
+### Enable Gravatar (optional)
+
+In the default Jisti Meet configuration, `gravatar.com` is enabled as an avatar service.
+
+Since the Element clients send the URL of configured Matrix avatars to the Jitsi instance, our default configuration has disabled the Gravatar service.
+
+To enable the Gravatar service, add the following configuration to your `vars.yml` file:
+
+```yaml
+jitsi_disable_gravatar: false
+```
+
+> [!WARNING]
+> This will result in third party request leaking data to the Gravatar Service (`gravatar.com`, unless configured otherwise). Besides metadata, the Matrix user_id and possibly the room ID (via `referrer` header) will be also sent to the third party.
+
+### Fine tune Jitsi (optional)
+
+If you'd like to have Jitsi save up resources, add the following configuration to your `vars.yml` file (adapt to your needs):
+
+```yaml
+jitsi_web_config_resolution_width_ideal_and_max: 480
+jitsi_web_config_resolution_height_ideal_and_max: 240
+jitsi_web_custom_config_extension: |
   config.enableLayerSuspension = true;
 
   config.disableAudioLevels = true;
 
-  // Limit the number of video feeds forwarded to each client
   config.channelLastN = 4;
-
-matrix_jitsi_web_config_resolution_width_ideal_and_max: 480
-matrix_jitsi_web_config_resolution_height_ideal_and_max: 240
 ```
 
-You may want to **suspend unused video layers** until they are requested again, to save up resources on both server and clients.
-Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/)
-For this add this line to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
+These configurations:
 
-You may wish to **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.
+- **limit the maximum video resolution**, to save up resources on both server and clients
+- **suspend unused video layers** until they are requested again, to save up resources on both server and clients. Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/).
+- **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved
+- **limit the number of video feeds forwarded to each client**, to save up resources on both server and clients. As clients’ bandwidth and CPU may not bear the load, use this setting to avoid lag and crashes. This feature is available by default on other webconference applications such as Office 365 Teams (the number is limited to 4). Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/5ff195985edf46c9399dcf263cb07167f0a2c724/doc/allocation.md).
 
-You may want to **limit the number of video feeds forwarded to each client**, to save up resources on both server and clients. As clients’ bandwidth and CPU may not bear the load, use this setting to avoid lag and crashes.
-This feature is found by default in other webconference applications such as Office 365 Teams (limit is set to 4).
-Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/doc/last-n.md) and performance evaluation on this [study](https://jitsi.org/wp-content/uploads/2016/12/nossdav2015lastn.pdf).
+### Extending the configuration
 
-You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
+There are some additional things you may wish to configure about the component.
 
+Take a look at:
 
-## Apply changes
+- [Jitsi role](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi)'s [`defaults/main.yml`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml) for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using these variables:
+  - `jitsi_web_custom_interface_config_extension`: custom configuration to be appended to `interface_config.js`, passed to Jitsi Web
+  - `jitsi_web_custom_config_extension`: custom configuration to be injected into `custom-config.js`, passed to Jitsi Web
+  - `jitsi_jvb_custom_config_extension`: custom configuration to be injected into `custom-sip-communicator.properties`, passed to Jitsi JVB
 
-Then re-run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+### Example configurations
 
+Here is an example set of configurations for running a Jitsi instance with:
+
+- authentication using a Jitsi account (username: `US3RNAME`, password: `passw0rd`)
+- guests: allowed
+- maximum participants: 6 people
+- fine tuning with the configurations presented above
+- other miscellaneous options (see the official Jitsi documentation [here](https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-configuration) and [here](https://jitsi.github.io/handbook/docs/user-guide/user-guide-advanced))
+
+```yaml
+jitsi_enabled: true
+jitsi_enable_auth: true
+jitsi_enable_guests: true
+jitsi_prosody_auth_internal_accounts:
+  - username: "US3RNAME"
+    password: "passw0rd"
+jitsi_prosody_max_participants: 6
+jitsi_web_config_resolution_width_ideal_and_max: 480
+jitsi_web_config_resolution_height_ideal_and_max: 240
+jitsi_web_custom_config_extension: |
+  config.enableLayerSuspension = true;
+  config.disableAudioLevels = true;
+  config.channelLastN = 4;
+  config.requireDisplayName = true; // force users to set a display name
+  config.startAudioOnly = true; // start the conference in audio only mode (no video is being received nor sent)
+```
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 
 You can use the self-hosted Jitsi server in multiple ways:
 
-- **by adding a widget to a room via Element** (the one configured by the playbook at `https://element.DOMAIN`). Just start a voice or a video call in a room containing more than 2 members and that would create a Jitsi widget which utilizes your self-hosted Jitsi server.
+- **by adding a widget to a room via Element Web** (the one configured by the playbook at `https://element.example.com`). Just start a voice or a video call in a room containing more than 2 members and that would create a Jitsi widget which utilizes your self-hosted Jitsi server.
 
-- **by adding a widget to a room via the Dimension Integration Manager**. You'll have to point the widget to your own Jitsi server manually. See our [Dimension](./configuring-playbook-dimension.md) documentation page for more details. Naturally, Dimension would need to be installed first (the playbook doesn't install it by default).
+- **directly (without any Matrix integration)**. Just go to `https://jitsi.example.com`
 
-- **directly (without any Matrix integration)**. Just go to `https://jitsi.DOMAIN`
+### Set up additional JVBs for more video-conferences (optional)
 
-**Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/vector-im/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
+By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)) is deployed on the same host as the Matrix server. To allow more video-conferences to happen at the same time, you'd need to provision additional JVB services on other hosts.
 
+These settings below will allow you to provision those extra JVB instances. The instances will register themselves with the Prosody service, and be available for Jicofo to route conferences too.
+
+#### Add the `jitsi_jvb_servers` section on `hosts` file
+
+For additional JVBs, you'd need to add the section titled `jitsi_jvb_servers` on the ansible `hosts` file with the details of the JVB hosts as below:
+
+```INI
+[jitsi_jvb_servers]
+jvb-2.example.com ansible_host=192.168.0.2
+```
+
+Make sure to replace `jvb-2.example.com` with your hostname for the JVB and `192.168.0.2` with your JVB's external IP address, respectively.
+
+You could add JVB hosts as many as you would like. When doing so, add lines with the details of them.
+
+#### Prepare `vars.yml` files for additional JVBs
+
+If the main server is `matrix.example.com` and the additional JVB instance is going to be deployed at `jvb-2.example.com`, the variables for the latter need to be specified on `vars.yml` in its directory (`inventory/host_vars/jvb-2.example.com`).
+
+Note that most (if not all) variables are common for both servers.
+
+If you are setting up multiple JVB instances, you'd need to create `vars.yml` files for each of them too (`inventory/host_vars/jvb-3.example.com/vars.yml`, for example).
+
+#### Set the server ID to each JVB
+
+Each JVB requires a server ID to be set, so that it will be uniquely identified. The server ID allows Jitsi to keep track of which conferences are on which JVB.
+
+The server ID can be set with the variable `jitsi_jvb_server_id`. It will end up as the `JVB_WS_SERVER_ID` environment variables in the JVB docker container.
+
+To set the server ID to `jvb-2`, add the following configuration to either `hosts` or `vars.yml` files (adapt to your needs).
+
+- On `hosts`:
+
+  Add `jitsi_jvb_server_id=jvb-2` after your JVB's external IP addresses as below:
+
+  ```INI
+  [jitsi_jvb_servers]
+  jvb-2.example.com ansible_host=192.168.0.2 jitsi_jvb_server_id=jvb-2
+  jvb-3.example.com ansible_host=192.168.0.3 jitsi_jvb_server_id=jvb-2
+  ```
+
+- On `vars.yml` files:
+
+  ```yaml
+  jitsi_jvb_server_id: 'jvb-2'
+  ```
+
+Alternatively, you can specify the variable as a parameter to [the ansible command](#run-the-playbook).
+
+**Note**: the server ID `jvb-1` is reserved for the JVB instance running on the Matrix host, therefore should not be used as the ID of an additional JVB host.
+
+#### Set colibri WebSocket port
+
+The additional JVBs will need to expose the colibri WebSocket port.
+
+To expose the port, add the following configuration to your `vars.yml` files:
+
+```yaml
+jitsi_jvb_container_colibri_ws_host_bind_port: 9090
+```
+
+#### Set Prosody XMPP server
+
+The JVB will also need to know the location of the Prosody XMPP server.
+
+Similar to the server ID (`jitsi_jvb_server_id`), this can be set with the variable for the JVB by using the variable `jitsi_xmpp_server`.
+
+##### Set the Matrix domain
+
+The Jitsi Prosody container is deployed on the Matrix server by default, so the value can be set to the Matrix domain. To set the value, add the following configuration to your `vars.yml` files:
+
+```yaml
+jitsi_xmpp_server: "{{ matrix_domain }}"
+```
+
+##### Set an IP address of the Matrix server
+
+Alternatively, the IP address of the Matrix server can be set. This can be useful if you would like to use a private IP address.
+
+To set the IP address of the Matrix server, add the following configuration to your `vars.yml` files:
+
+```yaml
+jitsi_xmpp_server: "192.168.0.1"
+```
+
+##### Expose XMPP port
+
+By default, the Matrix server does not expose the XMPP port (`5222`); only the XMPP container exposes it internally inside the host. This means that the first JVB (which runs on the Matrix server) can reach it but the additional JVBs cannot. Therefore, the XMPP server needs to expose the port, so that the additional JVBs can connect to it.
+
+To expose the port and have Docker forward the port, add the following configuration to your `vars.yml` files:
+
+```yaml
+jitsi_prosody_container_jvb_host_bind_port: 5222
+```
+
+#### Reverse-proxy with Traefik
+
+To make Traefik reverse-proxy to these additional JVBs, add the following configuration to your main `vars.yml` file (`inventory/host_vars/matrix.example.com/vars.yml`):
+
+```yaml
+# Traefik proxying for additional JVBs. These can't be configured using Docker
+# labels, like the first JVB is, because they run on different hosts, so we add
+# the necessary configuration to the file provider.
+traefik_provider_configuration_extension_yaml: |
+  http:
+   routers:
+     {% for host in groups['jitsi_jvb_servers'] %}
+
+     additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-router:
+       entryPoints:
+         - "{{ traefik_entrypoint_primary }}"
+       rule: "Host(`{{ jitsi_hostname }}`) && PathPrefix(`/colibri-ws/{{ hostvars[host]['jitsi_jvb_server_id'] }}/`)"
+       service: additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service
+       {% if traefik_entrypoint_primary != 'web' %}
+
+       tls:
+         certResolver: "{{ traefik_certResolver_primary }}"
+
+       {% endif %}
+
+     {% endfor %}
+
+   services:
+     {% for host in groups['jitsi_jvb_servers'] %}
+
+     additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service:
+       loadBalancer:
+         servers:
+           - url: "http://{{ host }}:9090/"
+
+     {% endfor %}
+```
+
+#### Run the playbook
+
+After configuring `hosts` and `vars.yml` files, run the playbook with [playbook tags](playbook-tags.md) as below:
+
+```sh
+ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start
+```
 
 ## 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 the commands below:
+- `journalctl -fu matrix-jitsi-web`
+- `journalctl -fu matrix-jitsi-prosody`
+- `journalctl -fu matrix-jitsi-jicofo`
+- `journalctl -fu matrix-jitsi-jvb`
+
+### `Error: Account creation/modification not supported`
+
+If you get an error like `Error: Account creation/modification not supported` with authentication enabled, it's likely that you had previously installed Jitsi without auth/guest support.
+
+In this case, you should consider to rebuild your Jitsi installation.
+
 ### Rebuilding your Jitsi installation
 
-**If you ever run into any trouble** or **if you change configuration (`matrix_jitsi_*` variables) too much**, we urge you to rebuild your Jitsi setup.
+If you ever run into any trouble or if you have changed configuration (`jitsi_*` variables) too much, you can rebuild your Jitsi installation.
 
-We normally don't require such manual intervention for other services, but Jitsi services generate a lot of configuration files on their own.
+We normally don't recommend manual intervention, but Jitsi services tend to generate a lot of configuration files, and it is often wise to start afresh setting the services up, rather than messing with the existing configuration files. Since not all of those files are managed by Ansible (at least not yet), you may sometimes need to delete them by yourself manually.
 
-These files are not all managed by Ansible (at least not yet), so you may sometimes need to delete them all and start fresh.
+To rebuild your Jitsi configuration, follow the procedure below:
 
-To rebuild your Jitsi configuration:
-
-- SSH into the server and do this:
-  - stop all Jitsi services (`systemctl stop matrix-jitsi-*`).
-  - remove all Jitsi configuration & data (`rm -rf /matrix/jitsi`)
-- ask Ansible to set up Jitsi anew and restart services (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-jitsi,start`)
+- run this command locally to stop all Jitsi services: `just run-tags stop-group --extra-vars=group=jitsi`
+- log in the server with SSH
+- run this command remotely to remove all Jitsi configuration & data: `rm -rf /matrix/jitsi`
+- run this command locally to set up Jitsi anew and restart services: `just install-service jitsi`

docs/configuring-playbook-ldap-auth.md

@@ -2,13 +2,15 @@
 
 The playbook can install and configure the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider for you.
 
-See that project's documentation to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/matrix-synapse-ldap3/blob/main/README.rst) to learn what it does and why it might be useful to you.
 
-If you decide that you'd like to let this playbook install it for you, you need some configuration like this:
+If you decide that you'd like to let this playbook install it for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_ext_password_provider_ldap_enabled: true
-matrix_synapse_ext_password_provider_ldap_uri: "ldap://ldap.mydomain.tld:389"
+matrix_synapse_ext_password_provider_ldap_uri:
+  - "ldap://ldap-01.example.com:389"
+  - "ldap://ldap-02.example.com:389"
 matrix_synapse_ext_password_provider_ldap_start_tls: true
 matrix_synapse_ext_password_provider_ldap_base: "ou=users,dc=example,dc=com"
 matrix_synapse_ext_password_provider_ldap_attributes_uid: "uid"
@@ -19,7 +21,6 @@ matrix_synapse_ext_password_provider_ldap_bind_password: ""
 matrix_synapse_ext_password_provider_ldap_filter: ""
 ```
 
-
 ## Authenticating only using a password provider
 
 If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
@@ -28,5 +29,12 @@ If you wish for users to **authenticate only against configured password provide
 matrix_synapse_password_config_localdb_enabled: false
 ```
 
-## Using ma1sd Identity Server for authentication
-If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).
+## Using ma1sd Identity Server for authentication (not recommended)
+
+The playbook can instead configure [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for LDAP authentication. However, **we recommend not bothering with installing it** as ma1sd has been unmaintained for years.
+
+If you wish to install it anyway, consult the [ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).
+
+## Handling user registration
+
+If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md).

docs/configuring-playbook-ma1sd.md

@@ -1,61 +1,87 @@
-# Adjusting ma1sd Identity Server configuration (optional)
+# Setting up ma1sd Identity Server (optional)
 
-The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you.
+**⚠️Note**: ma1sd itself has also been unmaintained for years (the latest commit and release being from 2021). The role of identity servers in the Matrix specification also has an uncertain future. **We recommend not bothering with installing it unless it's the only way you can do what you need to do**. For example, certain things like LDAP integration can also be implemented via [the LDAP provider module for Synapse](./configuring-playbook-ldap-auth.md).
 
-ma1sd, being an Identity Server, is not strictly needed. It is only used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features).
+The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you. It is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.
 
-This server is private by default, potentially at the expense of user discoverability.
+ma1sd is used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features). It is private by default, potentially at the expense of user discoverability.
 
-*ma1sd is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.*
+See the project's [documentation](https://github.com/ma1uta/ma1sd/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-**Note**: enabling ma1sd, 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).
+## Prerequisites
 
-To enable ma1sd, use the following additional configuration in your `vars.yml` file:
+### Open Matrix Federation port
+
+Enabling the ma1sd 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.
+
+## Adjusting DNS records
+
+To make the ma1sd Identity Server enable its federation features, set up a SRV record that looks like this:
+
+- Name: `_matrix-identity._tcp` (use this text as-is)
+- Content: `10 0 443 matrix.example.com` (replace `example.com` with your own)
+
+See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
+
+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`.
+
+**Note**: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
+
+## Adjusting the playbook configuration
+
+To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_ma1sd_enabled: true
 ```
 
-
-## Matrix.org lookup forwarding
+### Matrix.org lookup forwarding
 
 To ensure maximum discovery, you can make your identity server also forward lookups to the central matrix.org Identity server (at the cost of potentially leaking all your contacts information).
 
 Enabling this is discouraged and you'd better [learn more](https://github.com/ma1uta/ma1sd/blob/master/docs/features/identity.md#lookups) before proceeding.
 
-Enabling matrix.org forwarding can happen with the following configuration:
+To enable matrix.org forwarding, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_ma1sd_matrixorg_forwarding_enabled: true
 ```
 
+### Extending the configuration
 
-## Customizing email templates
+There are some additional things you may wish to configure about the component.
 
-If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables
-(in the `roles/matrix-ma1sd/defaults/main.yml` file.
+Take a look at:
 
+- `roles/custom/matrix-ma1sd/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_ma1sd_configuration_extension_yaml` variable
 
-## ma1sd-controlled Registration
+You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
+
+#### Customizing email templates
+
+If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables (in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.
+
+#### ma1sd-controlled Registration
 
 To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) feature of ma1sd, you can make use of the following variables:
 
-- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse
+- `matrix_synapse_enable_registration` — to enable user-initiated registration in Synapse
 
-- `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring_captcha.md) documentation.
+- `matrix_synapse_enable_registration_captcha` — to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring-captcha.md) documentation.
 
-- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering
+- `matrix_synapse_registrations_require_3pid` — a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering
 
-- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
+- variables prefixed with `matrix_ma1sd_container_labels_` (e.g. `matrix_ma1sd_container_labels_matrix_client_3pid_registration_enabled`) — to configure the Traefik reverse-proxy to capture and send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
 
-- `matrix_ma1sd_configuration_extension_yaml` - to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
+- `matrix_ma1sd_configuration_extension_yaml` — to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
 
-**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.DOMAIN:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
+**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
 
+#### Authentication
 
-## Authentication
+[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver.
 
-[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver. The following configuration can be used to authenticate against an LDAP server:
+To enable authentication against an LDAP server, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_synapse_ext_password_provider_rest_auth_enabled: true
@@ -75,20 +101,7 @@ matrix_ma1sd_configuration_extension_yaml: |
       bindPassword: TheUserPassword
 ```
 
-## Additional features
-
-What this playbook configures for your is some bare minimum Identity Server functionality, so that you won't need to rely on external 3rd party services.
-
-A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
-
-Still, ma1sd can do much more.
-You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
-
-To use a more custom configuration, you can define a `matrix_ma1sd_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_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
-
-## Example: SMS verification
+#### Example: SMS verification
 
 If your use case requires mobile verification, it is quite simple to integrate ma1sd with [Twilio](https://www.twilio.com/), an online telephony services gateway. Their prices are reasonable for low-volume projects and integration can be done with the following configuration:
 
@@ -104,7 +117,7 @@ matrix_ma1sd_configuration_extension_yaml: |
             number: '+<msisdn-number>'
 ```
 
-## Example: Open Registration for every Domain
+#### Example: Open Registration for every Domain
 
 If you want to open registration for any domain, you have to setup the allowed domains with ma1sd's `blacklist` and `whitelist`. The default behavior when neither the `blacklist`, nor the `whitelist` match, is to allow registration. Beware: you can't block toplevel domains (aka `.xy`) because the internal architecture of ma1sd doesn't allow that.
 
@@ -120,14 +133,30 @@ matrix_ma1sd_configuration_extension_yaml: |
             whitelist: ~
 ```
 
+## 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.
+
 ## Troubleshooting
 
 If email address validation emails sent by ma1sd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md).
 
-If you'd like additional logging information, temporarily enable verbose logging for ma1sd.
+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-ma1sd`.
 
-Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
+### 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
+# See: https://github.com/ma1uta/ma1sd/blob/master/docs/troubleshooting.md#increase-verbosity
 matrix_ma1sd_verbose_logging: true
 ```

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

@@ -0,0 +1,470 @@
+# Setting up Matrix Authentication Service (optional)
+
+The playbook can install and configure [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) (MAS) — a service operating alongside your existing [Synapse](./configuring-playbook-synapse.md) homeserver and providing [better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/).
+
+Matrix Authentication Service is an implementation of [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and still work in progress, tracked at the [areweoidcyet.com](https://areweoidcyet.com/) website.
+
+**Before going through with starting to use Matrix Authentication Service**, make sure to read:
+
+- the [Reasons to use Matrix Authentication Service](#reasons-to-use-matrix-authentication-service) section below
+- the [Expectations](#expectations) section below
+- the [FAQ section on areweoidcyet.com](https://areweoidcyet.com/#faqs)
+
+**If you've already been using Synapse** and have user accounts in its database, you can [migrate to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service).
+
+## Reasons to use Matrix Authentication Service
+
+You may be wondering whether you should make the switch to Matrix Authentication Service (MAS) or keep using your existing authentication flow via Synapse (password-based or [OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)-enabled).
+
+Matrix Authentication Service is **still an experimental service** and **not a default** for this Ansible playbook.
+
+The [Expectations](#expectations) section contains a list of what works and what doesn't (**some services don't work with MAS yet**), as well as the **relative irreversability** of the migration process.
+
+Below, we'll try to **highlight some potential reasons for switching** to Matrix Authentication Service:
+
+- To use SSO in [Element X](https://element.io/blog/element-x-ignition/). The old [Synapse OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) login flow is only supported in old Element clients and will not be supported in Element X. Element X will only support the new SSO-based login flow provided by MAS, so if you want to use SSO with Element X, you will need to switch to MAS.
+
+- To help drive adoption of the "Next-generation auth for Matrix" by switching to what's ultimately coming anyway
+
+- To help discover (and potentially fix) MAS integration issues with this Ansible playbook
+
+- To help discover (and potentially fix) MAS integration issues with various other Matrix components (bridges, bots, clients, etc.)
+
+- To reap some of the security benefits that Matrix Authentication Service offers, as outlined in the [Better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/) article.
+
+## Prerequisites
+
+- ⚠️ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
+
+- ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.
+
+## Expectations
+
+This section details what you can expect when switching to the Matrix Authentication Service (MAS).
+
+- ❌ **Synapse password providers will need to be disabled**. You can no longer use [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc. When the authentication flow is handled by MAS (not by Synapse anymore), it doesn't make sense to extend the Synapse authentication flow with additional modules. Many bridges used to rely on shared-secret-auth for doing double-puppeting (impersonating other users), but most (at least the mautrix bridges) nowadays use [Appservice Double Puppet](./configuring-playbook-appservice-double-puppet.md) as a better alternative. Older/maintained bridges may still rely on shared-secret-auth, as do other services like [matrix-corporal](./configuring-playbook-matrix-corporal.md).
+
+- ❌ Certain **tools like [synapse-admin](./configuring-playbook-synapse-admin.md) do not have full compatibility with MAS yet**. synapse-admin already supports [login with access token](https://github.com/etkecc/synapse-admin/pull/58), browsing users (which Synapse will internally fetch from MAS) and updating user avatars. However, editing users (passwords, etc.) now needs to happen directly against MAS using the [MAS Admin API](https://element-hq.github.io/matrix-authentication-service/api/index.html), which synapse-admin cannot interact with yet.
+
+- ❌ **Some services experience issues when authenticating via MAS**:
+
+  - [Postmoogle](./configuring-playbook-bridge-postmoogle.md) works the first time around, but it consistently fails after restarting:
+
+    > cannot initialize matrix bot error="olm account is marked as shared, keys seem to have disappeared from the server"
+
+  - [matrix-reminder-bot](./configuring-playbook-bot-matrix-reminder-bot.md) fails to start (see [element-hq/matrix-authentication-service#3439](https://github.com/element-hq/matrix-authentication-service/issues/3439))
+  - Other services may be similarly affected. This list is not exhaustive.
+
+- ❌ **Encrypted appservices** do not work yet (related to [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190) and [PR 17705 for Synapse](https://github.com/element-hq/synapse/pull/17705)), so all bridges/bots that rely on encryption will fail to start (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3658) for Hookshot). You can use these bridges/bots only if you **keep end-to-bridge encryption disabled** (which is the default setting).
+
+- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
+
+- ⚠️ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.
+
+- ⚠️ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration).
+
+- ⚠️ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed — all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md).
+
+- ✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad.
+
+- ✅ Various clients ([Cinny](./configuring-playbook-client-cinny.md), [Element Web](./configuring-playbook-client-element-web.md), Element X, FluffyChat) will be able to use the **new SSO-based login flow** provided by Matrix Authentication Service
+
+- ✅ The **old login flow** (called `m.login.password`) **will still continue to work**, so clients (old Element Web, etc.) and bridges/bots that don't support the new OIDC-based login flow will still work
+
+- ✅ [Registering users](./registering-users.md) via **the playbook's `register-user` tag remains unchanged**. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS. Registering users via the command-line is no longer done via the `/matrix/synapse/bin/register` script, but via `/matrix/matrix-authentication-service/bin/register-user`.
+
+- ✅ Users that are prepared by the playbook (for bots, bridges, etc.) will continue to be registered automatically as expected. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS.
+
+## Installation flows
+
+### New homeserver
+
+For new homeservers (which don't have any users in their Synapse database yet), follow the [Adjusting the playbook configuration](#adjusting-the-playbook-configuration) instructions and then proceed with [Installing](#installing).
+
+### Existing homeserver
+
+Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
+
+For existing Synapse homeservers:
+
+- when following the [Adjusting the playbook configuration](#adjusting-the-playbook-configuration) instructions, make sure to **disable the integration between Synapse and MAS** by **uncommenting** the `matrix_authentication_service_migration_in_progress: true` line as described in the [Marking an existing homeserver for migration](#marking-an-existing-homeserver-for-migration) section below.
+
+- then follow the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) instructions to perform the installation and migration
+
+## Adjusting DNS records (optional)
+
+By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (https://matrix.example.com/auth). 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-authentication-service-url-optional) for details about DNS configuration.
+
+## Adjusting the playbook configuration
+
+To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_authentication_service_enabled: true
+
+# Generate this encryption secret with: `openssl rand -hex 32`
+matrix_authentication_service_config_secrets_encryption: ''
+
+# When migrating an existing homeserver to Matrix Authentication Service, uncomment the line below.
+# Learn more about the migration process in the "Marking an existing homeserver for migration" section below.
+# For brand-new installations which start directly on MAS, this line can be removed.
+# matrix_authentication_service_migration_in_progress: true
+```
+
+In the sub-sections that follow, we'll cover some additional configuration options that you may wish to adjust.
+
+There are many other configuration options available. Consult the [`defaults/main.yml` file](../roles/custom/matrix-authentication-service/defaults/main.yml) in the [matrix-authentication-service role](../roles/custom/matrix-authentication-service/) to discover them.
+
+### Adjusting the Matrix Authentication Service URL (optional)
+
+By tweaking the `matrix_authentication_service_hostname` and `matrix_authentication_service_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_authentication_service_hostname: auth.example.com
+matrix_authentication_service_path_prefix: /
+```
+
+If you've changed the default hostname, you may need to create a CNAME record for the Matrix Authentication Service domain (`auth.example.com`), which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+### Marking an existing homeserver for migration
+
+The [configuration above](#adjusting-the-playbook-configuration) instructs existing users wishing to migrate to add `matrix_authentication_service_migration_in_progress: true` to their configuration.
+
+This is done temporarily. The migration steps are described in more detail in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) section below.
+
+### Upstream OAuth2 configuration
+
+To make Matrix Authentication Service delegate to an existing upstream OAuth 2.0/OIDC provider, you can use its [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers).
+
+The playbook exposes a `matrix_authentication_service_config_upstream_oauth2_providers` variable for controlling this setting.
+
+<details>
+<summary>Click to expand the example configuration:</summary>
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+matrix_authentication_service_config_upstream_oauth2_providers:
+  - # A unique identifier for the provider
+    # Must be a valid ULID
+    id: 01HFVBY12TMNTYTBV8W921M5FA
+    # The issuer URL, which will be used to discover the provider's configuration.
+    # If discovery is enabled, this *must* exactly match the `issuer` field
+    # advertised in `<issuer>/.well-known/openid-configuration`.
+    issuer: https://example.com/
+    # A human-readable name for the provider,
+    # which will be displayed on the login page
+    #human_name: Example
+    # A brand identifier for the provider, which will be used to display a logo
+    # on the login page. Values supported by the default template are:
+    #  - `apple`
+    #  - `google`
+    #  - `facebook`
+    #  - `github`
+    #  - `gitlab`
+    #  - `twitter`
+    #brand_name: google
+    # The client ID to use to authenticate to the provider
+    client_id: mas-fb3f0c09c4c23de4
+    # The client secret to use to authenticate to the provider
+    # This is only used by the `client_secret_post`, `client_secret_basic`
+    # and `client_secret_jwk` authentication methods
+    #client_secret: f4f6bb68a0269264877e9cb23b1856ab
+    # Which authentication method to use to authenticate to the provider
+    # Supported methods are:
+    #   - `none`
+    #   - `client_secret_basic`
+    #   - `client_secret_post`
+    #   - `client_secret_jwt`
+    #   - `private_key_jwt` (using the keys defined in the `secrets.keys` section)
+    token_endpoint_auth_method: client_secret_post
+    # Which signing algorithm to use to sign the authentication request when using
+    # the `private_key_jwt` or the `client_secret_jwt` authentication methods
+    #token_endpoint_auth_signing_alg: RS256
+    # The scopes to request from the provider
+    # In most cases, it should always include `openid` scope
+    scope: "openid email profile"
+    # How the provider configuration and endpoints should be discovered
+    # Possible values are:
+    #  - `oidc`: discover the provider through OIDC discovery,
+    #     with strict metadata validation (default)
+    #  - `insecure`: discover through OIDC discovery, but skip metadata validation
+    #  - `disabled`: don't discover the provider and use the endpoints below
+    #discovery_mode: oidc
+    # Whether PKCE should be used during the authorization code flow.
+    # Possible values are:
+    #  - `auto`: use PKCE if the provider supports it (default)
+    #    Determined through discovery, and disabled if discovery is disabled
+    #  - `always`: always use PKCE (with the S256 method)
+    #  - `never`: never use PKCE
+    #pkce_method: auto
+    # The provider authorization endpoint
+    # This takes precedence over the discovery mechanism
+    #authorization_endpoint: https://example.com/oauth2/authorize
+    # The provider token endpoint
+    # This takes precedence over the discovery mechanism
+    #token_endpoint: https://example.com/oauth2/token
+    # The provider JWKS URI
+    # This takes precedence over the discovery mechanism
+    #jwks_uri: https://example.com/oauth2/keys
+    # How user attributes should be mapped
+    #
+    # Most of those attributes have two main properties:
+    #   - `action`: what to do with the attribute. Possible values are:
+    #      - `ignore`: ignore the attribute
+    #      - `suggest`: suggest the attribute to the user, but let them opt out
+    #      - `force`: always import the attribute, and don't fail if it's missing
+    #      - `require`: always import the attribute, and fail if it's missing
+    #   - `template`: a Jinja2 template used to generate the value. In this template,
+    #      the `user` variable is available, which contains the user's attributes
+    #      retrieved from the `id_token` given by the upstream provider.
+    #
+    # Each attribute has a default template which follows the well-known OIDC claims.
+    #
+    claims_imports:
+      # The subject is an internal identifier used to link the
+      # user's provider identity to local accounts.
+      # By default it uses the `sub` claim as per the OIDC spec,
+      # which should fit most use cases.
+      subject:
+        #template: "{% raw %}{{ user.sub }}{% endraw %}"
+      # The localpart is the local part of the user's Matrix ID.
+      # For example, on the `example.com` server, if the localpart is `alice`,
+      #  the user's Matrix ID will be `@alice:example.com`.
+      localpart:
+        #action: force
+        #template: "{% raw %}{{ user.preferred_username }}{% endraw %}"
+      # The display name is the user's display name.
+      displayname:
+        #action: suggest
+        #template: "{% raw %}{{ user.name }}{% endraw %}"
+      # An email address to import.
+      email:
+        #action: suggest
+        #template: "{% raw %}{{ user.email }}{% endraw %}"
+        # Whether the email address must be marked as verified.
+        # Possible values are:
+        #  - `import`: mark the email address as verified if the upstream provider
+        #     has marked it as verified, using the `email_verified` claim.
+        #     This is the default.
+        #   - `always`: mark the email address as verified
+        #   - `never`: mark the email address as not verified
+        #set_email_verification: import
+```
+</details>
+
+💡 Refer to the [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers) for the most up-to-date schema and example for providers. The value shown above here may be out of date.
+
+⚠️ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2.
+
+⚠️ When [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) which contains OIDC-sourced users, you will need to:
+
+- [Configure upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas)
+- go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process
+- remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-authentication-service/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-authentication-service/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_authentication_service_configuration_extension_yaml` variable
+
+## Installing
+
+Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can 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
+```
+
+**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. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+- If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) guide.
+
+💡 After installation, you should [verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly).
+
+## Migrating an existing Synapse homeserver to Matrix Authentication Service
+
+Our migration guide is loosely based on the upstream [Migrating an existing homeserver](https://element-hq.github.io/matrix-authentication-service/setup/migration.html) guide.
+
+Migration is done via a tool called `syn2mas`, which the playbook could run for you (in a container).
+
+The installation + migration steps are like this:
+
+1. [Adjust your configuration](#adjusting-the-playbook-configuration) to **disable the integration between the homeserver and MAS**. This is done by **uncommenting** the `matrix_authentication_service_migration_in_progress: true` line.
+
+2. Perform the initial [installation](#installing). At this point:
+
+    - Matrix Authentication Service will be installed. Its database will be empty, so it cannot validate existing access tokens or authentication users yet.
+
+    - The homeserver will still continue to use its local database for validating existing access tokens.
+
+    - Various [compatibility layer URLs](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) are not yet installed. New login sessions will still be forwarded to the homeserver, which is capable of completing them.
+
+    - The `matrix-user-creator` role would be suppressed, so that it doesn't automatically attempt to create users (for bots, etc.) in the MAS database. These user accounts likely already exist in Synapse's user database and could be migrated over (via syn2mas, as per the steps below), so creating them in the MAS database would have been unnecessary and potentially problematic (conflicts during the syn2mas migration).
+
+3. Consider taking a full [backup of your Postgres database](./maintenance-postgres.md#backing-up-postgresql). This is done just in case. The **syn2mas migration tool does not delete any data**, so it should be possible to revert to your previous setup by merely disabling MAS and re-running the playbook (no need to restore a Postgres backup). However, do note that as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
+
+4. [Migrate your data from Synapse to Matrix Authentication Service using syn2mas](#migrate-your-data-from-synapse-to-matrix-authentication-service-using-syn2mas)
+
+5. [Adjust your configuration](#adjusting-the-playbook-configuration) again, to:
+
+  - remove the `matrix_authentication_service_migration_in_progress: false` line
+
+  - if you had been using [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration
+
+5. Perform the [installation](#installing) again. At this point:
+
+    - The homeserver will start delegating authentication to MAS.
+
+    - The compatibility layer URLs will be installed. New login sessions will be completed by MAS.
+
+6. [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)
+
+### Migrate your data from Synapse to Matrix Authentication Service using syn2mas
+
+We **don't** ask you to [run the `syn2mas` migration advisor command](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#run-the-migration-advisor), because it only gives you the green light if your Synapse configuration (`homeserver.yaml`) is configured in a way that's compatible with MAS (delegating authentication to MAS; disabling Synapse's password config; etc.). Until we migrate your data with the `syn2mas` tool, we intentionally avoid doing these changes to allow existing user sessions to work.
+
+You can invoke the `syn2mas` tool via the playbook by running the playbook's `matrix-authentication-service-syn2mas` tag. We recommend first doing a [dry-run](#performing-a-syn2mas-dry-run) and then a [real migration](#performing-a-real-syn2mas-migration).
+
+#### Configuring syn2mas
+
+If you're using [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to [Configuring upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas).
+
+If you only have local (non-OIDC) users in your Synapse database, you can likely run `syn2mas` as-is (without doing additional configuration changes).
+
+When you're done with potentially configuring `syn2mas`, proceed to doing a [dry-run](#performing-a-syn2mas-dry-run) and then a [real migration](#performing-a-real-syn2mas-migration).
+
+##### Configuring upstream OIDC provider mapping for syn2mas
+
+If you have existing OIDC users in your Synapse user database (which will be the case if when using [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)), you may need to pass an additional `--upstreamProviderMapping` argument to the `syn2mas` tool to tell it which provider (on the Synapse side) maps to which other provider on the MAS side.
+
+If you don't do this, `syn2mas` would report errors like this one:
+
+> [FATAL] migrate - [Failed to import external id 4264b0f0-4f11-4ddd-aedb-b500e4d07c25 with oidc-keycloak for user @alice:example.com: Error: Unknown upstream provider oidc-keycloak]
+
+Below is an example situation and a guide for how to solve it.
+
+If in `matrix_synapse_oidc_providers` your provider `idp_id` is (was) named `keycloak`, in the Synapse database users would be associated with the `oidc-keycloak` provider (note the `oidc-` prefix that was added automatically by Synapse to your `idp_id` value).
+
+The same OIDC provider may have an `id` of `01HFVBY12TMNTYTBV8W921M5FA` on the MAS side, as defined in `matrix_authentication_service_config_upstream_oauth2_providers` (see the [Upstream OAuth2 configuration](#upstream-oauth2-configuration) section above).
+
+To tell `syn2mas` how the Synapse-configured OIDC provider maps to the new MAS-configured OIDC provider, add this additional configuration to your `vars.yml` file:
+
+```yaml
+# Adjust the mapping below to match your provider IDs on the Synapse side and the MAS side.
+# Don't forget that Synapse automatically adds an `oidc-` prefix to provider ids defined in its configuration.
+matrix_authentication_service_syn2mas_process_extra_arguments:
+  - "--upstreamProviderMapping oidc-keycloak:01HFVBY12TMNTYTBV8W921M5FA"
+```
+
+#### Performing a syn2mas dry-run
+
+Having [configured syn2mas](#configuring-syn2mas), we recommend doing a [dry-run](https://en.wikipedia.org/wiki/Dry_run_(testing)) first to verify that everything will work out as expected.
+
+A dry-run would not cause downtime, because it avoids stopping Synapse.
+
+To perform a dry-run, run:
+
+```sh
+just run-tags matrix-authentication-service-syn2mas -e matrix_authentication_service_syn2mas_dry_run=true
+```
+
+Observe the command output (especially the last line of the the syn2mas output). If you are confident that the migration will work out as expected, you can proceed with a [real migration](#performing-a-real-syn2mas-migration).
+
+#### Performing a real syn2mas migration
+
+Before performing a real migration make sure:
+
+- you've familiarized yourself with the [expectations](#expectations)
+
+- you've performed a Postgres backup, just in case
+
+- you're aware of the irreversibility of the migration process without disruption after users have created new login sessions via the new MAS setup
+
+- you've [configured syn2mas](#configuring-syn2mas), especially if you've used [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)
+
+- you've performed a [syn2mas dry-run](#performing-a-syn2mas-dry-run) and don't see any issues in its output
+
+To perform a real migration, run the `matrix-authentication-service-syn2mas` tag **without** the `matrix_authentication_service_syn2mas_dry_run` variable:
+
+```sh
+just run-tags matrix-authentication-service-syn2mas
+```
+
+Having performed a `syn2mas` migration once, trying to do it again will report errors for users that were already migrated (e.g. "Error: Unknown upstream provider oauth-delegated").
+
+## Verify that Matrix Authentication Service is installed correctly
+
+After [installation](#installing), run the `doctor` subcommand of the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) to verify that MAS is installed correctly.
+
+You can do it:
+
+- either via the Ansible playbook's `matrix-authentication-service-mas-cli-doctor` tag: `just run-tags matrix-authentication-service-mas-cli-doctor`
+
+- or by running the `mas-cli` script on the server (which invokes the `mas-cli` tool inside a container): `/matrix/matrix-authentication-service/bin/mas-cli doctor`
+
+If successful, you should see some output that looks like this:
+
+```
+💡 Running diagnostics, make sure that both MAS and Synapse are running, and that MAS is using the same configuration files as this tool.
+✅ Matrix client well-known at "https://example.com/.well-known/matrix/client" is valid
+✅ Homeserver is reachable at "http://matrix-synapse:8008/_matrix/client/versions"
+✅ Homeserver at "http://matrix-synapse:8008/_matrix/client/v3/account/whoami" is reachable, and it correctly rejected an invalid token.
+✅ The Synapse admin API is reachable at "http://matrix-synapse:8008/_synapse/admin/v1/server_version".
+✅ The Synapse admin API is reachable with authentication at "http://matrix-synapse:8008/_synapse/admin/v1/background_updates/status".
+✅ The legacy login API at "https://matrix.example.com/_matrix/client/v3/login" is reachable and is handled by MAS.
+```
+
+## Usage
+
+### Management
+
+You can use the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) (exposed via the `/matrix/matrix-authentication-service/bin/mas-cli` script) to perform administrative tasks against MAS.
+
+This documentation page already mentions:
+
+- the `mas-cli doctor` sub-command in the [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly) section, which you can run via the CLI and via the Ansible playbook's `matrix-authentication-service-mas-cli-doctor` tag
+
+- the `mas-cli manage register-user` sub-command in the [Registering users](./registering-users.md) documentation
+
+There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview.
+
+### User registration
+
+After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)).
+
+You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag).
+
+### Working around email deliverability issues
+
+Matrix Authentication Service only sends emails when:
+
+- it verifies email addresses for users who are self-registering with a password
+
+- a user tries to add an email to their account
+
+If Matrix Authentication Service tries to send an email and it fails because [your email-sending configuration](./configuring-playbook-email.md) is not working, you may need to work around email deliverability.
+
+If email delivery is not working, **you can retrieve the email verification code from the Matrix Authentication Service's logs** (`journalctl -fu matrix-authentication-service`).
+
+Alternatively, you can use the [`mas-cli` management tool](#management) to manually verify email addresses for users. Example: `/matrix/matrix-authentication-service/bin/mas-cli manage verify-email some.username email@example.com`
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-authentication-service`.

docs/configuring-playbook-matrix-corporal.md

@@ -1,24 +1,21 @@
 # Setting up Matrix Corporal (optional, advanced)
 
--------------------------------------
-
-**WARNING**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't.
-
--------------------------------------
+> [!WARNING]
+> This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't.
 
 The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you.
 
 In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment.
-See that project's documentation to learn what it does and why it might be useful to you.
+
+See the project's [documentation](https://github.com/devture/matrix-corporal/blob/main/README.md) to learn what it does and why it might be useful to you.
 
 If you decide that you'd like to let this playbook install it for you, you'd need to also:
 - (required) [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md)
 - (optional, but encouraged) [set up the REST authentication password provider module](configuring-playbook-rest-auth.md)
 
+## Adjusting the playbook configuration
 
-## Playbook configuration
-
-You would then need some configuration like this:
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
 # The Shared Secret Auth password provider module is required for Corporal to work.
@@ -48,11 +45,11 @@ matrix_corporal_policy_provider_config: |
     "TimeoutMilliseconds": 300
   }
 
-# If you also want to enable Matrix Corporal's HTTP API..
+# If you also want to enable Matrix Corporal's HTTP API…
 matrix_corporal_http_api_enabled: true
 matrix_corporal_http_api_auth_token: "AUTH_TOKEN_HERE"
 
-# If you need to change matrix-corporal's user id from the default (matrix-corporal).
+# If you need to change matrix-corporal's user ID from the default (matrix-corporal).
 # In any case, you need to make sure this Matrix user is created on your server.
 matrix_corporal_corporal_user_id_local_part: "matrix-corporal"
 
@@ -71,9 +68,9 @@ matrix_synapse_rc_login:
     burst_count: 3
 ```
 
-Matrix Corporal operates with a specific Matrix user on your server.
-By default, it's `matrix-corporal` (controllable by the `matrix_corporal_reconciliation_user_id_local_part` setting, see above).
-No matter what Matrix user id you configure to run it with, make sure that:
+Matrix Corporal operates with a specific Matrix user on your server. By default, it's `matrix-corporal` (controllable by the `matrix_corporal_reconciliation_user_id_local_part` setting, see above).
+
+No matter what Matrix user ID you configure to run it with, make sure that:
 
 - the Matrix Corporal user is created by [registering it](registering-users.md) **with administrator privileges**. Use a password you remember, as you'll need to log in from time to time to create or join rooms
 
@@ -91,7 +88,7 @@ matrix_corporal_policy_provider_config: |
   }
 
 # Modify the policy below as you see fit
-matrix_aux_file_definitions:
+aux_file_definitions:
   - dest: "{{ matrix_corporal_config_dir_path }}/policy.json"
     content: |
       {
@@ -115,8 +112,27 @@ matrix_aux_file_definitions:
 
 To learn more about what the policy configuration, see the matrix-corporal documentation on [policy](https://github.com/devture/matrix-corporal/blob/master/docs/policy.md).
 
-Each time you update the policy in your `vars.yml` file, you'd need to re-run the playbook and restart matrix-corporal (`--tags=setup-all,start` or `--tags=setup-aux-files,setup-corporal,start`).
+### Extending the configuration
 
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-corporal/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-corporal/templates/config.json.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_corporal_configuration_extension_json` 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 run-tags setup-aux-files,setup-corporal,start` or `just setup-all`
+
+`just run-tags setup-aux-files,setup-corporal,start` 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.
 
 ## Matrix Corporal files
 
@@ -128,4 +144,16 @@ The following local filesystem paths are mounted in the `matrix-corporal` contai
 
 - `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write)
 
-As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths - `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write).
+As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths — `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write).
+
+## 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-corporal`.
+
+### 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_corporal_debug: true
+```

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

@@ -0,0 +1,61 @@
+# Setting up matrix-ldap-registration-proxy (optional)
+
+The playbook can install and configure [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) for you.
+
+This proxy handles Matrix registration requests and forwards them to LDAP.
+
+See the project's [documentation](https://gitlab.com/activism.international/matrix_ldap_registration_proxy/-/blob/main/README.md) to learn what it does and why it might be useful to you.
+
+**Note**: This does support the full Matrix specification for registrations. It only provide a very coarse implementation of a basic password registration.
+
+## Adjusting the playbook configuration
+
+To enable the component, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+
+```yaml
+matrix_ldap_registration_proxy_enabled: true
+
+# LDAP credentials
+matrix_ldap_registration_proxy_ldap_uri: YOUR_URI_HERE
+matrix_ldap_registration_proxy_ldap_base_dn: YOUR_DN_HERE
+matrix_ldap_registration_proxy_ldap_user: YOUR_USER_HERE
+matrix_ldap_registration_proxy_ldap_password: YOUR_PASSWORD_HERE
+```
+
+If you already use the [synapse external password provider via LDAP](configuring-playbook-ldap-auth.md) (that is, you have `matrix_synapse_ext_password_provider_ldap_enabled: true` and other options in your configuration) you can use the following values as configuration:
+
+```yaml
+# Use the LDAP values specified for the synapse role to setup LDAP proxy
+matrix_ldap_registration_proxy_ldap_uri: "{{ matrix_synapse_ext_password_provider_ldap_uri }}"
+matrix_ldap_registration_proxy_ldap_base_dn: "{{ matrix_synapse_ext_password_provider_ldap_base }}"
+matrix_ldap_registration_proxy_ldap_user: "{{ matrix_synapse_ext_password_provider_ldap_bind_dn }}"
+matrix_ldap_registration_proxy_ldap_password: "{{ matrix_synapse_ext_password_provider_ldap_bind_password }}"
+
+matrix_ldap_registration_proxy_systemd_wanted_services_list_custom:
+  - matrix-synapse.service
+```
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-ldap-registration-proxy/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-ldap-registration-proxy`.

docs/configuring-playbook-matrix-media-repo.md

@@ -0,0 +1,205 @@
+# Storing Matrix media files using matrix-media-repo (optional)
+
+The playbook can install and configure [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/) (often abbreviated "MMR") for you.
+
+MMR is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
+
+**Notes**:
+- If MMR is enabled, other media store roles should be disabled (if using Synapse with other media store roles).
+- Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
+- For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
+
+## Adjusting the playbook configuration
+
+To enable matrix-media-repo, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_media_repo_enabled: true
+```
+
+By default, the media-repo will use the local filesystem for data storage. You can alternatively use a `s3` cloud backend as well. Access token caching is also enabled by default since the logout endpoints are proxied through the media repo.
+
+### 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_media_repo_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/matrix-media-repo` by adding the following configuration to your `vars.yml` file:
+
+```yaml
+matrix_media_repo_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_media_repo_container_labels_traefik_metrics_middleware_basic_auth_enabled: true
+matrix_media_repo_container_labels_traefik_metrics_middleware_basic_auth_users: ''
+```
+
+To `matrix_media_repo_container_labels_traefik_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 metics.
+
+To enable Grafana, see [this section](configuring-playbook-prometheus-grafana.md#adjusting-the-playbook-configuration-grafana) for instructions.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-media-repo/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+Here is a list of additional common configuration options:
+
+```yaml
+# The postgres database pooling options
+
+# The maximum number of connects to hold open. More of these allow for more concurrent
+# processes to happen.
+matrix_media_repo_database_max_connections: 25
+
+# The maximum number of connects to leave idle. More of these reduces the time it takes
+# to serve requests in low-traffic scenarios.
+matrix_media_repo_database_max_idle_connections: 5
+
+# These users have full access to the administrative functions of the media repository.
+# See docs/admin.md for information on what these people can do. They must belong to one of the
+# configured homeservers above.
+# matrix_media_repo_admins: [
+#   "@alice:example.org"
+# ]
+
+matrix_media_repo_admins: []
+
+# Datastores can be split into many areas when handling uploads. Media is still de-duplicated
+# across all datastores (local content which duplicates remote content will re-use the remote
+# content's location). This option is useful if your datastore is becoming very large, or if
+# you want faster storage for a particular kind of media.
+#
+# To disable this datastore, making it readonly, specify `forKinds: []`.
+#
+# The kinds available are:
+#   thumbnails    — Used to store thumbnails of media (local and remote).
+#   remote_media  — Original copies of remote media (servers not configured by this repo).
+#   local_media   — Original uploads for local media.
+#   archives      — Archives of content (GDPR and similar requests).
+matrix_media_repo_datastore_file_for_kinds: ["thumbnails", "remote_media", "local_media", "archives"]
+matrix_media_repo_datastore_s3_for_kinds: []
+
+# The s3 uploader needs a temporary location to buffer files to reduce memory usage on
+# small file uploads. If the file size is unknown, the file is written to this location
+# before being uploaded to s3 (then the file is deleted). If you aren't concerned about
+# memory usage, set this to an empty string.
+matrix_media_repo_datastore_s3_opts_temp_path: ""
+matrix_media_repo_datastore_s3_opts_endpoint: "sfo2.digitaloceanspaces.com"
+matrix_media_repo_datastore_s3_opts_access_key_id: ""
+matrix_media_repo_datastore_s3_opts_access_secret: ""
+matrix_media_repo_datastore_s3_opts_ssl: true
+matrix_media_repo_datastore_s3_opts_bucket_name: "your-media-bucket"
+
+# An optional region for where this S3 endpoint is located. Typically not needed, though
+# some providers will need this (like Scaleway). Uncomment to use.
+# matrix_media_repo_datastore_s3_opts_region: "sfo2"
+
+# An optional storage class for tuning how the media is stored at s3.
+# See https://aws.amazon.com/s3/storage-classes/ for details; uncomment to use.
+# matrix_media_repo_datastore_s3_opts_storage_class: "STANDARD"
+```
+
+## Signing Keys
+
+Authenticated media endpoints ([MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916)) requires MMR to have a configured signing key to authorize outbound federation requests. Additionally, the signing key must be merged with your homeserver's signing key file.
+
+The playbook default is to generate a MMR signing key when invoking the setup role and merge it with your homeserver if you are using Synapse or Dendrite. This can be disabled if desired by setting the option in your inventory:
+
+```yaml
+matrix_media_repo_generate_signing_key: false
+```
+
+If you wish to manually generate the signing key and merge it with your homeserver's signing key file, see https://docs.t2bot.io/matrix-media-repo/v1.3.5/installation/signing-key/ for more details.
+
+**Note that if you uninstall MMR from the playbook, it will not remove the old MMR signing key from your homeserver's signing key file. You will have to remove it manually.**
+
+### Key backup and revoking
+
+Since your homeserver signing key file is modified by the playbook, a backup will be created in `HOMESERVER_DIR/config/example.com.signing.key.backup`. If you need to remove/revoke old keys, you can restore from this backup or remove the MMR key ID from your `example.com.signing.key` file.
+
+Additionally, its recommended after revoking a signing key to update your homeserver config file (`old_signing_keys` field for Synapse and `old_private_keys` for Dendrite). See your homeserver config file for further documentation on how to populate the field.
+
+## Importing data from an existing media store
+
+If you want to add this repo to an existing homeserver managed by the playbook, you will need to import existing media into MMR's database or you will lose access to older media while it is active. MMR versions up to `v1.3.3` only support importing from Synapse, but newer versions (at time of writing: only `latest`) also support importing from Dendrite.
+
+**Before importing**: ensure you have an initial matrix-media-repo deployment by following the [quickstart](#quickstart) guide above
+
+Depending on the homeserver implementation yu're using (Synapse, Dendrite), you'll need to use a different import tool (part of matrix-media-repo) and point it to the homeserver's database.
+
+### Importing data from the Synapse media store
+
+To import the Synapse media store, you're supposed to invoke the `import_synapse` tool which is part of the matrix-media-repo container image. Your Synapse database is called `synapse` by default, unless you've changed it by modifying `matrix_synapse_database_database`.
+
+This guide here is adapted from the [upstream documentation about the import_synapse script](https://github.com/turt2live/matrix-media-repo#importing-media-from-synapse).
+
+Run the following command on the server (after replacing `postgres_connection_password` in it with the value found in your `vars.yml` file):
+
+```sh
+docker exec -it matrix-media-repo \
+    /usr/local/bin/import_synapse \
+        -dbName synapse \
+        -dbHost matrix-postgres \
+        -dbPort 5432 \
+        -dbUsername matrix \
+        -dbPassword postgres_connection_password
+```
+
+Enter `1` for the Machine ID when prompted (you are not doing any horizontal scaling) unless you know what you're doing.
+
+This should output a `msg="Import completed"` when finished successfully!
+
+### Importing data from the Dendrite media store
+
+If you're using the [Dendrite](configuring-playbook-dendrite.md) homeserver instead of the default for this playbook (Synapse), follow this importing guide here.
+
+To import the Dendrite media store, you're supposed to invoke the `import_dendrite` tool which is part of the matrix-media-repo container image. Your Dendrite database is called `dendrite_mediaapi` by default, unless you've changed it by modifying `matrix_dendrite_media_api_database`.
+
+Run the following command on the server (after replacing `postgres_connection_password` in it with the value found in your `vars.yml` file):
+
+```sh
+docker exec -it matrix-media-repo \
+    /usr/local/bin/import_dendrite \
+        -dbName dendrite_mediaapi \
+        -dbHost matrix-postgres \
+        -dbPort 5432 \
+        -dbUsername matrix \
+        -dbPassword postgres_connection_password
+```
+
+Enter `1` for the Machine ID when prompted (you are not doing any horizontal scaling) unless you know what you're doing.
+
+This should output a `msg="Import completed"` when finished successfully!
+
+## 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-media-repo`.
+
+### Increase logging verbosity
+
+If you want to turn on sentry's built-in debugging, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_media_repo_sentry_debug: true
+```

docs/configuring-playbook-matrix-registration.md

@@ -1,66 +1,107 @@
 # Setting up matrix-registration (optional)
 
-The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you.
+> [!WARNING]
+> - This is a poorly maintained and buggy project. It's better to avoid using it.
+> - This is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md)
 
-> matrix-registration is a simple python application to have a token based matrix registration.
+The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you. It is a simple python application to have a token based Matrix registration.
 
-Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows you to **keep your server's registration closed (private)**, but still allow certain people (these having a special link) to register a user account.
+Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows certain people (these having a special link) to register a user account, **keeping your server's registration closed (private)**.
 
 **matrix-registration** provides 2 things:
 
 - **an API for creating registration tokens** (unique registration links). This API can be used via `curl` or via the playbook (see [Usage](#usage) below)
 
-- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.DOMAIN/matrix-registration`
+- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.example.com/matrix-registration`
 
+## Adjusting DNS records (optional)
 
-## Installing
+By default, this playbook installs the matrix-registration on the `matrix.` subdomain, at the `/matrix-registration` path (https://matrix.example.com/matrix-registration). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
 
-Adjust your playbook configuration (your `inventory/host_vars/matrix.DOMAIN/vars.yml` file):
+If you wish to adjust it, see the section [below](#adjusting-the-matrix-registration-url-optional) for details about DNS configuration.
+
+## Adjusting the playbook configuration
+
+To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_registration_enabled: true
 
-# Generate a strong secret using: `pwgen -s 64 1`.
+# Generate a strong secret here. You can create one with a command like `pwgen -s 64 1`.
 matrix_registration_admin_secret: "ENTER_SOME_SECRET_HERE"
 ```
 
-Then, run the [installation](installing.md) command again:
+### Adjusting the matrix-registration URL (optional)
 
+By tweaking the `matrix_registration_hostname` and `matrix_registration_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_registration_hostname: registration.example.com
+matrix_registration_path_prefix: /
 ```
+
+If you've changed the default hostname, you may need to create a CNAME record for the matrix-registration domain (`registration.example.com`), which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-registration/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-registration/templates/config.yaml.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_registration_configuration_extension_yaml` variable
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 
-**matrix-registration** gets exposed at `https://matrix.DOMAIN/matrix-registration`
+**matrix-registration** gets exposed at `https://matrix.example.com/matrix-registration`
 
-It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) - for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`.
+It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) — for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`.
 
 We make the most common APIs easy to use via the playbook (see below).
 
-
 ### Creating registration tokens
 
 To **create a new user registration token (link)**, use this command:
 
-```bash
+```sh
 ansible-playbook -i inventory/hosts setup.yml \
 --tags=generate-matrix-registration-token \
 --extra-vars="one_time=yes ex_date=2021-12-31"
 ```
 
-The above command creates and returns a **one-time use** token, which **expires** on the 31st of December 2021.
-Adjust the `one_time` and `ex_date` variables as you see fit.
+The above command creates and returns a **one-time use** token, which **expires** on the 31st of December 2021. Adjust the `one_time` and `ex_date` variables as you see fit.
 
 Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
 
-
 ### Listing registration tokens
 
 To **list the existing user registration tokens**, use this command:
 
-```bash
+```sh
 ansible-playbook -i inventory/hosts setup.yml \
 --tags=list-matrix-registration-tokens
 ```
+
+The shortcut command with `just` program is also available: `just run-tags list-matrix-registration-tokens`
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-registration`.