ลบ

преди 3 години · c78da42016
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,39 +0,0 @@
 # 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.

 - [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook

 - [Configuring your DNS server](configuring-dns.md)

 - [Getting this playbook's source code](getting-the-playbook.md)

 - [Configuring the playbook](configuring-playbook.md)

 - [Installing](installing.md)

 - **Importing data from another server installation**

  - [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)

  - [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)

  - [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)

 - [Registering users](registering-users.md)

 - [Updating users passwords](updating-users-passwords.md)

 - [Configuring service discovery via .well-known](configuring-well-known.md)

 - [Maintenance / checking if services work](maintenance-checking-services.md)

 - [Maintenance / upgrading services](maintenance-upgrading-services.md)

 - [Maintenance / Synapse](maintenance-synapse.md)

 - [Maintenance / PostgreSQL](maintenance-postgres.md)

 - [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)

 - [Uninstalling](uninstalling.md)
--- a/docs/alternative-architectures.md
+++ b/docs/alternative-architectures.md
@@ -1,26 +0,0 @@
 # 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.

 To that end add the following variable to your `vars.yml` file (see [Configuring playbook](configuring-playbook.md)):

 ```yaml
 matrix_architecture: <your-matrix-server-architecture>
 ```

 Currently supported architectures are the following:
 - `amd64` (the default)
 - `arm64`
 - `arm32`

 so for the Raspberry Pi, the following should be in your `vars.yml` file:

 ```yaml
 matrix_architecture: "arm32"
 ```

 ## 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.
--- a/docs/ansible.md
+++ b/docs/ansible.md
@@ -1,114 +0,0 @@

 # Running this playbook

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


 ## 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).


 ## Upgrading Ansible

 Depending on your distribution, you may be able to upgrade Ansible in a few different ways:

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


 ## Using Ansible via Docker

 Alternatively, you can run Ansible inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).

 This ensures that you're using a very recent Ansible version, which is less likely to be incompatible with the playbook.

 There are 2 ways to go about it:

 - [Running Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself)
 - [Running 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_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:

 ```bash
 docker run -it --rm \
 --privileged \
 --pid=host \
 -w /work \
 -v `pwd`:/work \
 --entrypoint=/bin/sh \
 docker.io/devture/ansible:2.13.0-r0
 ```

 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 ...` (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:

 ```bash
 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.13.0-r0
 ```

 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.

 You can 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
 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.

--- a/docs/assets/obtain_admin_access_token_element.png
+++ b/docs/assets/obtain_admin_access_token_element.png
--- a/docs/configuring-captcha.md
+++ b/docs/configuring-captcha.md
@@ -1,23 +0,0 @@
 (Adapted from the [upstream project](https://github.com/matrix-org/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

 Requires a site/secret key pair from:

 <http://www.google.com/recaptcha/admin>

 Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option

 ## Setting ReCaptcha Keys

 Once registered as above, set the following values:

 ```yaml
 matrix_synapse_enable_registration_captcha: true
 matrix_synapse_recaptcha_public_key: 'YOUR_SITE_KEY'
 matrix_synapse_recaptcha_private_key: 'YOUR_SECRET_KEY'
 ```
--- a/docs/configuring-dns.md
+++ b/docs/configuring-dns.md
@@ -1,92 +0,0 @@
 # Configuring your DNS server

 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>` |

 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.

 When you're done configuring DNS, proceed to [Configuring the playbook](configuring-playbook.md).

 ## DNS settings for optional services/features

 | Used by component                                                                                                       | Type  | Host                           | Priority | Weight | Port | Target                      |
 | ----------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | --------------------------- |
 | [ma1sd](configuring-playbook-ma1sd.md) identity server                                                                  | SRV   | `_matrix-identity._tcp`        | 10       | 0      | 443  | `matrix.<your-domain>`      |
 | [Dimension](configuring-playbook-dimension.md) integration server                                                       | CNAME | `dimension`                    | -        | -      | -    | `matrix.<your-domain>`      |
 | [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform                                                      | CNAME | `jitsi`                        | -        | -      | -    | `matrix.<your-domain>`      |
 | [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system                                      | CNAME | `stats`                        | -        | -      | -    | `matrix.<your-domain>`      |
 | [Go-NEB](configuring-playbook-bot-go-neb.md) bot                                                                        | CNAME | `goneb`                        | -        | -      | -    | `matrix.<your-domain>`      |
 | [Sygnal](configuring-playbook-sygnal.md) push notification gateway                                                      | CNAME | `sygnal`                       | -        | -      | -    | `matrix.<your-domain>`      |
 | [ntfy](configuring-playbook-ntfy.md) push notifications server                                                          | CNAME | `ntfy`                         | -        | -      | -    | `matrix.<your-domain>`      |
 | [Hydrogen](configuring-playbook-client-hydrogen.md) web client                                                          | CNAME | `hydrogen`                     | -        | -      | -    | `matrix.<your-domain>`      |
 | [Cinny](configuring-playbook-client-cinny.md) web client                                                                | CNAME | `cinny`                        | -        | -      | -    | `matrix.<your-domain>`      |
 | [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot                                                         | CNAME | `buscarron`                    | -        | -      | -    | `matrix.<your-domain>`      |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX    | `matrix`                       | 10       | 0      | -    | `matrix.<your-domain>`      |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge                                                       | TXT   | `matrix`                       | -        | -      | -    | `v=spf1 ip4:<your-ip> -all` |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge                                                       | TXT   | `_dmarc.matrix`                | -        | -      | -    | `v=DMARC1; p=quarantine;`   |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge                                                       | TXT   | `postmoogle._domainkey.matrix` | -        | -      | -    | get it from `!pm dkim`      |

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

 ## Subdomains setup

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

 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.

 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.

 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.

 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.

 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 `ntfy.<your-domain>` subdomain may be necessary, because this playbook could install the [ntfy](https://ntfy.sh/) UnifiedPush-compatible push notifications server. The installation of ntfy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring ntfy guide](configuring-playbook-ntfy.md). If you do not wish to set up ntfy, feel free to skip the `ntfy.<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://gitlab.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).

 ## `_dmarc`, `postmoogle._domainkey` TXT and `matrix` MX records setup

 To make the [postmoogle](configuring-playbook-bot-postmoogle.md) email bridge enable its email sending features, you need to configure
 SPF (TXT), DMARC (TXT), DKIM (TXT) and MX records
--- a/docs/configuring-playbook-backup-borg.md
+++ b/docs/configuring-playbook-backup-borg.md
@@ -1,81 +0,0 @@
 # Setting up borg backup (optional)

 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.

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

 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.


 ## Prerequisites

 1. Create a new SSH key:

 ```bash
 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.

 2. Add the **public** part of this SSH key (the `matrix-borg-backup.pub` file) to your borg provider/server:

 If you plan to use a hosted solution, follow their instructions. If you have your own server, copy the key over:

 ```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
 cat PUBKEY | ssh USER@HOST 'dd of=.ssh/authorized_keys oflag=append conv=notrunc'
 ```

 ## Adjusting the playbook configuration

 Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable borg backup:

 ```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: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
  xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
  bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
  RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
  ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
  -----END OPENSSH PRIVATE KEY-----
 ```

 where:

 * USER - SSH user of a provider/server
 * HOST - SSH host of a provider/server
 * REPO - borg repository name, it will be initialized on backup start, eg: `matrix`, regarding Syntax see [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls)
 * PASSPHRASE - passphrase used for encrypting backups, you may generate it with `pwgen -s 64 1` or use any password manager
 * PRIVATE KEY - the content of the **private** part of the SSH key you created before. The whole key (all of its belonging lines) under `matrix_backup_borg_ssh_key_private` needs to be indented with 2 spaces

 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.

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

 Check the `roles/matrix-backup-borg/defaults/main.yml` file for the full list of available options.

 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```

 ## Manually start a backup

 For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server
 and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly a long time.
 Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.
--- a/docs/configuring-playbook-base-domain-serving.md
+++ b/docs/configuring-playbook-base-domain-serving.md
@@ -1,52 +0,0 @@
 # Serving the base domain

 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.

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

 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`).

 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**:

 ```yaml
 matrix_nginx_proxy_base_domain_serving_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).


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

 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
 ```

 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.


 ## 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.
--- a/docs/configuring-playbook-bot-buscarron.md
+++ b/docs/configuring-playbook-bot-buscarron.md
@@ -1,75 +0,0 @@
 # Setting up Buscarron (optional)

 The playbook can install and configure [buscarron](https://gitlab.com/etke.cc/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

 ## Registering the bot user

 By default, the playbook will set up the bot with a username like this: `@bot.buscarron:DOMAIN`.

 (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`.


 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:

 ```yaml
 matrix_bot_buscarron_enabled: true

 # Adjust this to whatever password you chose when registering the bot user
 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
    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_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).

 If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):

 ```yaml
 matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"
 ```


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## 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:

 ```html
 <form method="POST" action="https://buscarron.DOMAIN/contact">
 <!--your fields-->
 </form>
 ```

 You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/buscarron).
--- a/docs/configuring-playbook-bot-go-neb.md
+++ b/docs/configuring-playbook-bot-go-neb.md
@@ -1,213 +0,0 @@
 # Setting up Go-NEB (optional)

 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.


 ## Registering the bot user

 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.

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

 You can use the playbook to [register a new user](registering-users.md):

 ```
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```

 Once the user is created you can [obtain an access token](obtaining-access-tokens.md).


 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):

 ```yaml
 matrix_bot_go_neb_enabled: true

 # You need at least 1 client.
 # Use the access token you obtained in the step above.
 matrix_bot_go_neb_clients:
  - UserID: "@goneb:{{ matrix_domain }}"
    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
    DeviceID: "DEVICE1"
    HomeserverURL: "{{ matrix_homeserver_container_url }}"
    Sync: true
    AutoJoinRooms: true
    DisplayName: "Go-NEB!"
    AcceptVerificationFromUsers: [":{{ matrix_domain }}"]

  - UserID: "@another_goneb:{{ matrix_domain }}"
    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
    DeviceID: "DEVICE2"
    HomeserverURL: "{{ matrix_homeserver_container_url }}"
    Sync: false
    AutoJoinRooms: false
    DisplayName: "Go-NEB!"
    AcceptVerificationFromUsers: ["^@admin:{{ matrix_domain }}"]

 # Optional, for use with the github_cmd, github_webhooks or jira services
 matrix_bot_go_neb_realms:
  - ID: "github_realm"
    Type: "github"
    Config: {} # No need for client ID or Secret as Go-NEB isn't generating OAuth URLs

 # Optional. The list of *authenticated* sessions which Go-NEB is aware of.
 matrix_bot_go_neb_sessions:
  - SessionID: "your_github_session"
    RealmID: "github_realm"
    UserID: "@YOUR_USER_ID:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
    Config:
      # Populate these fields by generating a "Personal Access Token" on github.com
      AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
      Scopes: "admin:org_hook,admin:repo_hook,repo,user"

 # The list of services which Go-NEB is aware of.
 # Delete or modify this list as appropriate.
 # See the docs for /configureService for the full list of options:
 # https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
 # You need at least 1 service.
 matrix_bot_go_neb_services:
  - ID: "echo_service"
    Type: "echo"
    UserID: "@goneb:{{ matrix_domain }}"
    Config: {}

 # Can be obtained from https://developers.giphy.com/dashboard/
  - ID: "giphy_service"
    Type: "giphy"
    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
    Config:
      api_key: "qwg4672vsuyfsfe"
      use_downsized: false

 # This service has been dead for over a year :/
  - ID: "guggy_service"
    Type: "guggy"
    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
    Config:
      api_key: "2356saaqfhgfe"

 # API Key via https://developers.google.com/custom-search/v1/introduction
 # CX via http://www.google.com/cse/manage/all
 # https://stackoverflow.com/questions/6562125/getting-a-cx-id-for-custom-search-google-api-python
 # 'Search the entire web' and 'Image search' enabled for best results
  - ID: "google_service"
    Type: "google"
    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
    Config:
      api_key: "AIzaSyA4FD39m9"
      cx: "AIASDFWSRRtrtr"

 # Get a key via https://api.imgur.com/oauth2/addclient
 # Select "oauth2 without callback url"
  - ID: "imgur_service"
    Type: "imgur"
    UserID: "@imgur:{{ matrix_domain }}" # requires a Syncing client
    Config:
      client_id: "AIzaSyA4FD39m9"
      client_secret: "somesecret"

  - ID: "wikipedia_service"
    Type: "wikipedia"
    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
    Config:

  - ID: "rss_service"
    Type: "rssbot"
    UserID: "@another_goneb:{{ matrix_domain }}"
    Config:
      feeds:
        "http://lorem-rss.herokuapp.com/feed?unit=second&interval=60":
          rooms: ["!qmElAGdFYCHoCJuaNt:{{ matrix_domain }}"]
          must_include:
            author:
              - author1
            description:
              - lorem
              - ipsum
          must_not_include:
            title:
              - Lorem
              - Ipsum

  - ID: "github_cmd_service"
    Type: "github"
    UserID: "@goneb:{{ matrix_domain }}" # requires a Syncing client
    Config:
      RealmID: "github_realm"

    # Make sure your BASE_URL can be accessed by Github!
  - ID: "github_webhook_service"
    Type: "github-webhook"
    UserID: "@another_goneb:{{ matrix_domain }}"
    Config:
      RealmID: "github_realm"
      ClientUserID: "@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.
      Rooms:
        "!someroom:id":
          Repos:
            "matrix-org/synapse":
              Events: ["push", "issues"]
            "matrix-org/dendron":
              Events: ["pull_request"]
        "!anotherroom:id":
          Repos:
            "matrix-org/synapse":
              Events: ["push", "issues"]
            "matrix-org/dendron":
              Events: ["pull_request"]

  - ID: "slackapi_service"
    Type: "slackapi"
    UserID: "@slackapi:{{ matrix_domain }}"
    Config:
      Hooks:
        "hook1":
          RoomID: "!someroom:id"
          MessageType: "m.text" # default is m.text

  - ID: "alertmanager_service"
    Type: "alertmanager"
    UserID: "@alertmanager:{{ matrix_domain }}"
    Config:
      # This is for information purposes only. It should point to Go-NEB path as follows:
      # `/services/hooks/<base64 encoded service ID>`
      # Where in this case "service ID" is "alertmanager_service"
      # Make sure your BASE_URL can be accessed by the Alertmanager instance!
      webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
      # Each room will get the notification with the alert rendered with the given template
      rooms:
        "!someroomid:domain.tld":
          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`
 ```


 ## 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, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## 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).

 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`

 You can also refer to the upstream [Documentation](https://github.com/matrix-org/go-neb).
--- a/docs/configuring-playbook-bot-honoroit.md
+++ b/docs/configuring-playbook-bot-honoroit.md
@@ -1,55 +0,0 @@
 # Setting up Honoroit (optional)

 The playbook can install and configure [Honoroit](https://gitlab.com/etke.cc/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.


 ## 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`.


 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:

 ```yaml
 matrix_bot_honoroit_enabled: true

 # Adjust this to whatever password you chose when registering the bot user
 matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT

 # Adjust this to your room ID
 matrix_bot_honoroit_roomid: "!yourRoomID:DOMAIN"
 ```


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


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

 Send `!ho help` to the room to see the bot's help menu for additional commands.

 You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/honoroit#features).
--- a/docs/configuring-playbook-bot-matrix-registration-bot.md
+++ b/docs/configuring-playbook-bot-matrix-registration-bot.md
@@ -1,65 +0,0 @@
 # Setting up matrix-registration-bot (optional)

 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.

 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. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).

 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/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"

 # Enables registration
 matrix_synapse_enable_registration: true

 # Restrict registration to users with a token
 matrix_synapse_registration_requires_token: true
 ```


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## Usage

 To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain).

 In this room send `help` and the bot will reply with all options.

 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).
--- a/docs/configuring-playbook-bot-matrix-reminder-bot.md
+++ b/docs/configuring-playbook-bot-matrix-reminder-bot.md
@@ -1,59 +0,0 @@
 # Setting up matrix-reminder-bot (optional)

 The playbook can install and configure [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for you.

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


 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:

 ```yaml
 matrix_bot_matrix_reminder_bot_enabled: true

 # Adjust this to whatever password you chose when registering the bot user
 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
 ```


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## 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).

 You can also add the bot to any existing Matrix room (`/invite @bot.matrix-reminder-bot:DOMAIN`).

 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).
--- a/docs/configuring-playbook-bot-maubot.md
+++ b/docs/configuring-playbook-bot-maubot.md
@@ -1,58 +0,0 @@
 # 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.<your-domain>/_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 the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:

 ```yaml
 matrix_bot_maubot_enabled: true
 matrix_bot_maubot_admins:
  - yourusername: securepassword
 ```

 You can add multiple admins. The admin accounts are not connected to any matrix ID and are only used to access the
 maubot administration interface.


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```

 ## Usage

 You can visit `matrix.<your-domain>/_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.
 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)

 To add a client you first need to create an account and obtain a valid access token.

 ## Registering the bot user

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

 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 need to open the bot docker container with `docker exec -it matrix-bot-maubot sh`
 Alternatively, use Element or curl to [obtain an access token](obtaining-access-tokens.md). However these two methods won't allow the bot to work in encrypted rooms.
--- a/docs/configuring-playbook-bot-mjolnir.md
+++ b/docs/configuring-playbook-bot-mjolnir.md
@@ -1,122 +0,0 @@
 # Setting up Mjolnir (optional)

 The playbook can install and configure the [Mjolnir](https://github.com/matrix-org/mjolnir) moderation bot for you.

 See the project's [documentation](https://github.com/matrix-org/mjolnir) to learn what it does and why it might be useful to you.


 ## 1. 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.

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

 You can use the playbook to [register a new user](registering-users.md):

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


 ## 2. Get an access token

 Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).


 ## 3. Make sure the account is free from rate limiting

 You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). This can also be manually done by editing the Synapse database. Manually editing the Synapse database is rarely a good idea. Please ask for help if you are uncomfortable with these steps.

 1. Copy the statement below into a text editor. 

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

 ```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"
 ```

 ## 6. Adding mjolnir synapse antispam module (optional)

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):


 ```yaml
 matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_invites: true
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_messages: false
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
 ```


 ## 7. Installing

 After configuring the playbook, run the [installation](installing.md) command:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


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

 ```yaml
 matrix_bot_mjolnir_configuration_extension_yaml: |
  # Your custom YAML configuration goes here.
  # This configuration extends the default starting configuration (`matrix_bot_mjolnir_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_mjolnir_configuration_yaml`.
  recordIgnoredInvites: true
 ```
--- a/docs/configuring-playbook-bot-postmoogle.md
+++ b/docs/configuring-playbook-bot-postmoogle.md
@@ -1,59 +0,0 @@
 # Setting up Postmoogle (optional)

 **Note**: email bridging can also happen via the [email2matrix](configuring-playbook-email2matrix.md) bridge supported by the playbook.

 The playbook can install and configure [Postmoogle](https://gitlab.com/etke.cc/postmoogle) for you.

 It's a bot/bridge you can use to forward emails to Matrix rooms

 See the project's [documentation](https://gitlab.com/etke.cc/postmoogle) 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: `@postmoogle:DOMAIN`.

 (to use a different username, adjust the `matrix_bot_postmoogle_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=postmoogle 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`.


 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:

 ```yaml
 matrix_bot_postmoogle_enabled: true

 # Adjust this to whatever password you chose when registering the bot user
 matrix_bot_postmoogle_password: PASSWORD_FOR_THE_BOT
 ```

 You will also need to add several DNS records so that postmoogle can send emails.
 See [Configuring DNS](configuring-dns.md).


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## Usage

 To use the bot, invite the `@postmoogle:DOMAIN` 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.domain`. Emails sent to that email address will be forwarded to the room.

 Send `!pm help` to the room to see the bot's help menu for additional commands.

 You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/postmoogle).
--- a/docs/configuring-playbook-bridge-appservice-discord.md
+++ b/docs/configuring-playbook-bridge-appservice-discord.md
@@ -1,79 +0,0 @@
 # Setting up Appservice Discord (optional)

 **Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.   
 - 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.

 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.


 ## Setup Instructions

 Instructions loosely based on [this](https://github.com/Half-Shot/matrix-appservice-discord#setting-up).

 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:

 ```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"
 ```

 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.

 Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.

 ## 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`:

 ```yaml
 matrix_appservice_discord_bridge_enableSelfServiceBridging: true
 ```

 _Note: If self-service bridging is not enabled, `!discord help` commands will return no results._

 Once self-service is enabled:

 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.

 _Note: Encrypted Matrix rooms are not supported as of writing._

 On the Discord side, you can say `!matrix help` to get a list of available commands to manage the bridge and Matrix users.

 ## 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>`).

 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`:

 ```yaml
 matrix_appservice_discord_bridge_disablePortalBridging: true
 ```

 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.

 ## Getting Administrator access in a portal bridged room

 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:

 ```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'
 ```
--- a/docs/configuring-playbook-bridge-appservice-irc.md
+++ b/docs/configuring-playbook-bridge-appservice-irc.md
@@ -1,61 +0,0 @@
 # Setting up Appservice IRC (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.

 The playbook can install and configure the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for you.

 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:

 ```yaml
 matrix_appservice_irc_enabled: true

 matrix_appservice_irc_ircService_servers:
  irc.example.com:
    name: "ExampleNet"
    port: 6697
    ssl: true
    sasl: false
    allowExpiredCerts: false
    sendConnectionMessages: true
    botConfig:
      enabled: true
      nick: "MatrixBot"
      joinChannelsIfNoUsers: true
    privateMessages:
      enabled: true
      federate: true
    dynamicChannels:
      enabled: true
      createAlias: true
      published: true
      joinRule: public
      groupId: +myircnetwork:localhost
      federate: true
      aliasTemplate: "#irc_$CHANNEL"
    membershipLists:
      enabled: false
      floodDelayMs: 10000
      global:
        ircToMatrix:
          initial: false
          incremental: false
        matrixToIrc:
          initial: false
          incremental: false
    matrixClients:
      userTemplate: "@irc_$NICK"
      displayName: "$NICK (IRC)"
      joinAttempts: -1
    ircClients:
      nickTemplate: "$DISPLAY[m]"
      allowNickChanges: true
      maxClients: 30
      idleTimeout: 10800
      reconnectIntervalMs: 5000
      concurrentReconnectLimit: 50
      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).
--- a/docs/configuring-playbook-bridge-appservice-kakaotalk.md
+++ b/docs/configuring-playbook-bridge-appservice-kakaotalk.md
@@ -1,64 +0,0 @@
 # Setting up Appservice Kakaotalk (optional)

 The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you. `matrix-appservice-kakaotalk` is a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.

 **NOTE**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.

 See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) to learn what it does and why it might be useful to you.


 ## Installing

 To enable the bridge, add this to your `vars.yml` file:

 ```yaml
 matrix_appservice_kakaotalk_enabled: true
 ```

 You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.

 After adjusting your `vars.yml` file, re-run the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`

 To make use of the Kakaotalk bridge, see [Usage](#usage) below.


 ### Additional configuration

 There are some additional things you may wish to configure about the bridge.

 Take a look at:

 - `roles/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 - `roles/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


 ### 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

 - make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature


 ## Usage

 Start a chat with `@kakaotalkbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

 Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.

 After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
--- a/docs/configuring-playbook-bridge-appservice-slack.md
+++ b/docs/configuring-playbook-bridge-appservice-slack.md
@@ -1,112 +0,0 @@
 # Setting up Appservice Slack (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.

 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:

 loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)

 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:

 ```yaml
 matrix_appservice_slack_enabled: true
 matrix_appservice_slack_control_room_id: "Your matrix admin room id"
 ```

 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:

 ```
    /invite @slackbot:MY.DOMAIN
 ```

 Note that the bot's domain is your server's domain **without the `matrix.` prefix.**

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

 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:

     Bot User Events:

    - team_domain_change
    - message.channels
    - message.groups (if you want to bridge private channels)
    - reaction_added
    - reaction_removed

 7. Click on OAuth & Permissions and add the following scopes:

    - chat:write:bot
    - users:read
    - reactions:write

    If you want to bridge files, also add the following:

    - files:write:user

    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
    ```

 Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.

 10. Unlinking

    Channels can be unlinked again like this:
    ```
       unlink --room !the-matrix:room.id
    ```

    Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.

 ## Troubleshooting

 * as always, check the logs:
 `journalctl -fu matrix-appservice-slack`

 * linking: "Room is now pending-name"
 This typically means that you haven't used the correct slack channel id. Unlink the room and recheck 'Determine the "channel ID"' from above.

 * Messages work from M to S, but not the other way around
 Check you logs, if they say something like

 `WARN SlackEventHandler Ignoring message from unrecognised slack channel id : %s (%s) <the channel id> <some other id>`

 then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link
 your room multiple times without unlinking it after each failed attempt.
--- a/docs/configuring-playbook-bridge-appservice-webhooks.md
+++ b/docs/configuring-playbook-bridge-appservice-webhooks.md
@@ -1,65 +0,0 @@
 # Setting up Appservice Webhooks (optional)

 The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you.

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

 This bridge provides support for Slack-compatible webhooks.

 Setup Instructions:

 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`:

 ```yaml
 matrix_appservice_webhooks_enabled: true
 matrix_appservice_webhooks_api_secret: '<your_secret>'
 ```

 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.

 *Note*: default value is: `info` and availabe log levels are : `info`, `verbose`

 ```yaml
 matrix_appservice_webhooks_log_level: '<log_level>'
 ```

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

 5. Invite the bridge bot user to your room:

    - either with `/invite @_webhook:<domain.name>` (*Note*: Make sure you have administration permissions in your room)

    - or simply add the bridge bot to a private channel (personal channels imply you being an administrator)

 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:
 ```json
 {
    "text": "Hello world!",
    "format": "plain",
    "displayName": "My Cool Webhook",
    "avatar_url": "http://i.imgur.com/IDOBtEJ.png"
 }
 ```

 You can test this via curl like so:

 ```
 curl --header "Content-Type: application/json" \
 --data '{
 "text": "Hello world!",
 "format": "plain",
 "displayName": "My Cool Webhook",
 "avatar_url": "http://i.imgur.com/IDOBtEJ.png"
 }' \
 <the link you've gotten in 5.>
 ```
--- a/docs/configuring-playbook-bridge-beeper-linkedin.md
+++ b/docs/configuring-playbook-bridge-beeper-linkedin.md
@@ -1,59 +0,0 @@
 # Setting up Beeper Linkedin (optional)

 The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges

 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.

 ```yaml
 matrix_beeper_linkedin_enabled: true
 ```

 There are some additional things you may wish to configure about the bridge before you continue.

 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
 ```

 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
 ```

 You may wish to look at `roles/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things 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.


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


 ## Troubleshooting

 ### 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.
--- a/docs/configuring-playbook-bridge-go-skype-bridge.md
+++ b/docs/configuring-playbook-bridge-go-skype-bridge.md
@@ -1,23 +0,0 @@
 # Setting up Go Skype Bridge (optional)

 The playbook can install and configure
 [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.

 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_go_skype_bridge_enabled: true
 ```


 ## Usage

 Once the bot is enabled, you need to start a chat with `Skype bridge bot`
 with the handle `@skypebridgebot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base
 domain, not the `matrix.` domain).

 Send `help` to the bot to see the commands available.
--- a/docs/configuring-playbook-bridge-heisenbridge.md
+++ b/docs/configuring-playbook-bridge-heisenbridge.md
@@ -1,38 +0,0 @@
 # Setting up Heisenbridge (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.

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

 ## Configuration

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

 At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.DOMAIN/vars.yml`):

 ```yaml
 matrix_heisenbridge_enabled: true

 # set owner (optional)
 matrix_heisenbridge_owner: "@you:your-homeserver"

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

 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.

 ## Usage

 After the bridge is successfully running just DM `@heisenbridge:your-homeserver` to start setting it up.
 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.
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -1,93 +0,0 @@
 # Setting up 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.

 See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) to learn what it does in detail 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.


 ## Setup Instructions

 Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.

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

 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.


 ## Usage

 Create a room and invite the Hookshot bot (`@hookshot:DOMAIN`) to it.

 Make sure the bot is able to send state events (usually the Moderator power level in clients).

 Send a `!hookshot help` message to see a list of help commands.

 Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) for more details about using the brige's various features.

 **Important:** Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](#urls-for-bridges-setup) below.


 ## 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 |
 |---|---|---|---|
 | webhooks | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | generics, GitHub "Webhook URL", GitLab "URL", etc. |
 | github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
 | jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | JIRA OAuth |
 | figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
 | provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
 | appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
 | widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
 | metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and `matrix_hookshot_metrics_proxying_enabled`. Requires `/metrics/*` endpoints to also be enabled via `matrix_nginx_proxy_proxy_matrix_metrics_enabled` (see the `matrix-nginx-proxy` role). Read more in the [Metrics section](#metrics) below. | Prometheus |

 See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml).

 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.

 ### Manage GitHub Private Key with matrix-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:
 ```yaml
 matrix_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).

 ### Provisioning API

 The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.

 ### Metrics

 Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.

 To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This only exposes metrics over the container network, however.

 **To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to:

 - enable the `https://matrix.DOMAIN/metrics/*` endpoints on `matrix.DOMAIN` using `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true` (see the `matrix-nginx-role` or [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for enabling this feature)
 - expose the Hookshot metrics under `https://matrix.DOMAIN/metrics/hookshot` by setting `matrix_hookshot_metrics_proxying_enabled: true`

 ### 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_'`).
--- a/docs/configuring-playbook-bridge-matrix-bridge-sms.md
+++ b/docs/configuring-playbook-bridge-matrix-bridge-sms.md
@@ -1,37 +0,0 @@
 # Setting up matrix-sms-bridge (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.

 **The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.**

 To enable the bridge just use the following
 playbook configuration:


 ```yaml
 matrix_sms_bridge_enabled: true

 # (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
 matrix_sms_bridge_default_timezone: Europe/Berlin

 # Settings to connect to android-sms-gateway-server
 matrix_sms_bridge_provider_android_baseurl: https://192.168.24.24:9090
 matrix_sms_bridge_provider_android_username: admin
 matrix_sms_bridge_provider_android_password: supeSecretPassword

 # (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

 ```


 ## Usage

 Read the [user guide](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md#user-guide) to see how this bridge works.
--- a/docs/configuring-playbook-bridge-mautrix-discord.md
+++ b/docs/configuring-playbook-bridge-mautrix-discord.md
@@ -1,81 +0,0 @@
 # Setting up Mautrix Discord (optional)

 **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 `mautrix-discord` bridge (the one being discussed here) is the most fully-featured and stable of the 3 Discord bridges supported by the playbook, so it's the one we recommend.

 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

 For using this bridge, you would need to authenticate by **scanning a QR code** with the Discord app on your phone **or** by using **discord account token**.

 You can delete the Discord app after the authentication process.

 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.


 ## Installing

 To enable the bridge, add this to your `vars.yml` file:

 ```yaml
 matrix_mautrix_discord_enabled: true
 ```

 You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.

 After adjusting your `vars.yml` file, re-run the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`

 To make use of the bridge, see [Usage](#usage) below.


 ### Additional configuration

 There are some additional things you may wish to configure about the bridge.

 Take a look at:

 - `roles/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 - `roles/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable


 ### 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

 - make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature


 ## Usage

 1. Start a chat with `@discordbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
 2. If you would like to login to Discord using a token, send `login-token` command, otherwise, send `login-qr` command.
 3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
 4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as ..."
 5. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to
 6. Some Direct Messages from Discord should start syncing automatically
 7. If you'd like to bridge guilds:
 - send `guilds status` to see the list of guilds
 - for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire`
 8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function.
--- a/docs/configuring-playbook-bridge-mautrix-facebook.md
+++ b/docs/configuring-playbook-bridge-mautrix-facebook.md
@@ -1,101 +0,0 @@
 # Setting up Mautrix Facebook (optional)

 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.

 ```yaml
 matrix_mautrix_facebook_enabled: true
 ```

 There are some additional things you may wish to configure about the bridge before you continue.

 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
 ```

 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:{{ matrix_domain }}': admin
 ```

 Using both would look like

 ```yaml
 matrix_mautrix_facebook_configuration_extension_yaml: |
  bridge:
    permissions:
      '@YOUR_USERNAME:{{ matrix_domain }}': admin
    encryption:
      allow: true
      default: true
 ```

 You may wish to look at `roles/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

 - make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature


 ## Usage

 You then need to start a chat with `@facebookbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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).

 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

 ### Facebook rejecting login attempts and forcing you to change password

 If your Matrix server is in a wildly different location than where you usually use your Facebook account from, the bridge's login attempts may be outright rejected by Facebook. Along with that, Facebook may even force you to change the account's password.

 If you happen to run into this problem while [setting up bridging](#usage), try to first get a successful session up by logging in to Facebook through the Matrix server's IP address.

 The easiest way to do this may be to use [sshuttle](https://sshuttle.readthedocs.io/) to proxy your traffic through the Matrix server.

 Example command for proxying your traffic through the Matrix server:

 ```
 sshuttle -r root@matrix.DOMAIN: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/).

 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 [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
--- a/docs/configuring-playbook-bridge-mautrix-googlechat.md
+++ b/docs/configuring-playbook-bridge-mautrix-googlechat.md
@@ -1,52 +0,0 @@
 # Setting up Mautrix Google Chat (optional)

 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:


 ```yaml
 matrix_mautrix_googlechat_enabled: true
 ```


 ## 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

 - make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature


 ## 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).

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

--- a/docs/configuring-playbook-bridge-mautrix-hangouts.md
+++ b/docs/configuring-playbook-bridge-mautrix-hangouts.md
@@ -1,54 +0,0 @@
 # 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 (optional)

 The playbook can install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts) for you.

 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.

 To enable the [Google Hangouts](https://hangouts.google.com/) bridge just use the following playbook configuration:


 ```yaml
 matrix_mautrix_hangouts_enabled: true
 ```


 ## 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

 - make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature


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

--- a/docs/configuring-playbook-bridge-mautrix-instagram.md
+++ b/docs/configuring-playbook-bridge-mautrix-instagram.md
@@ -1,43 +0,0 @@
 # Setting up Mautrix Instagram (optional)

 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.

 ```yaml
 matrix_mautrix_instagram_enabled: true
 ```
 There are some additional things you may wish to configure about the bridge before you continue.

 Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
 ```yaml
 matrix_mautrix_instagram_configuration_extension_yaml: |
  bridge:
    encryption:
      allow: true
      default: true
 ```

 If you would like to be able to administrate the bridge from your account it can be configured like this:
 ```yaml
 # The easy way. The specified Matrix user ID will be made an admin of all bridges
 matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"

 # OR:
 # The more verbose way. Applies to this bridge only. You may define multiple Matrix users as admins.
 matrix_mautrix_instagram_configuration_extension_yaml: |
  bridge:
    permissions:
      '@YOUR_USERNAME:YOUR_DOMAIN': admin
 ```

 You may wish to look at `roles/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.


 ## Usage

 You then need to start a chat with `@instagrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` 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 can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/instagram/authentication.html).
--- a/docs/configuring-playbook-bridge-mautrix-signal.md
+++ b/docs/configuring-playbook-bridge-mautrix-signal.md
@@ -1,85 +0,0 @@
 # Setting up Mautrix Signal (optional)

 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.

 **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_*`).

 Use the following playbook configuration:

 ```yaml
 matrix_mautrix_signal_enabled: true
 ```

 There are some additional things you may wish to configure about the bridge before you continue.

 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.

 Different levels of permission can be granted to users:

 * relay - Allowed to be relayed through the bridge, no access to commands;
 * user - Use the bridge with puppeting;
 * admin - Use and administer the bridge.

 The permissions are following the sequence: nothing < relay < user < admin.

 The default permissions are set as follows:
 ```yaml
 permissions:
  '*': relay
  YOUR_DOMAIN: user
 ```

 If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file:
 ```yaml
 matrix_mautrix_signal_configuration_extension_yaml: |
  bridge:
    permissions:
      '@YOUR_USERNAME:YOUR_DOMAIN': admin
 ```

 This will add the admin permission to the specific user, while keepting the default permissions.

 In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
 ```yaml
 matrix_mautrix_signal_bridge_permissions: |
  '@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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

 - make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature


 ## Usage

 You then need to start a chat with `@signalbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
--- a/docs/configuring-playbook-bridge-mautrix-telegram.md
+++ b/docs/configuring-playbook-bridge-mautrix-telegram.md
@@ -1,66 +0,0 @@
 # Setting up Mautrix Telegram (optional)

 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:

 ```yaml
 matrix_mautrix_telegram_enabled: true
 matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
 matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
 ```

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

 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:

 - retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send `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:

 ```yaml
 matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
 matrix_mautrix_telegram_configuration_extension_yaml: |
  bridge:
    permissions:
      '*': relaybot
 ```

 You might also want to give permissions to administrate the bot:
 ```yaml
 matrix_mautrix_telegram_configuration_extension_yaml: |
  bridge:
    permissions:
      '@user:DOMAIN': admin
 ```

 More details about permissions in this example:
 https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410

 If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration:
 ```yaml
 matrix_mautrix_telegram_filter_mode: whitelist
 ```
--- a/docs/configuring-playbook-bridge-mautrix-twitter.md
+++ b/docs/configuring-playbook-bridge-mautrix-twitter.md
@@ -1,35 +0,0 @@
 # Setting up Mautrix Twitter (optional)

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

 ```yaml
 matrix_mautrix_twitter_enabled: true
 ```


 ## 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

 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`

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

 You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/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.
--- a/docs/configuring-playbook-bridge-mautrix-whatsapp.md
+++ b/docs/configuring-playbook-bridge-mautrix-whatsapp.md
@@ -1,56 +0,0 @@
 # Setting up Mautrix Whatsapp (optional)

 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:

 ```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

 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. Refer to the documentation on [how to do that](obtaining-access-tokens.md).

 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

 - make sure you don't log out the `Mautrix-Whatsapp` device some time in the future, as that would break the Double Puppeting feature


 ## Usage

 You then need to start a chat with `@whatsappbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
--- a/docs/configuring-playbook-bridge-mx-puppet-discord.md
+++ b/docs/configuring-playbook-bridge-mx-puppet-discord.md
@@ -1,38 +0,0 @@
 # Setting up MX Puppet Discord (optional)

 **Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md)and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.   
 - 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.

 See the project page 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:


 ```yaml
 matrix_mx_puppet_discord_enabled: true
 ```


 ## 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).

 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.

 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.
--- a/docs/configuring-playbook-bridge-mx-puppet-groupme.md
+++ b/docs/configuring-playbook-bridge-mx-puppet-groupme.md
@@ -1,36 +0,0 @@
 # Setting up MX Puppet GroupMe (optional)

 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.

 To enable the [GroupMe](https://groupme.com/) bridge just use the following
 playbook configuration:


 ```yaml
 matrix_mx_puppet_groupme_enabled: true
 ```


 ## 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).

 One authentication method is available.

 To link your GroupMe account, go to [dev.groupme.com](https://dev.groupme.com/), sign in, and select "Access Token" from the top menu. Copy the token and message the bridge with:

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

 Also send `help` to the bot to see the commands available.
--- a/docs/configuring-playbook-bridge-mx-puppet-instagram.md
+++ b/docs/configuring-playbook-bridge-mx-puppet-instagram.md
@@ -1,36 +0,0 @@
 # Setting up mx-puppet-instagram (optional)

 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:


 ```yaml
 matrix_mx_puppet_instagram_enabled: true
 ```


 ## 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).

 Send `link <username> <password>` to the bridge bot to link your instagram account.

 The `list` commands shows which accounts are linked and which `puppetId` is associated.

 For double-puppeting, you probably want to issue these commands:

 - `settype $puppetId puppet` to enable puppeting for the link (instead of relaying)
 - `setautoinvite $puppetId 1` to automatically invite you to chats
 - `setmatrixtoken $accessToken` to set the access token to enable puppeting from the other side (the "double" in double puppeting)

 If you are linking only one Instagram account, your `$puppetId` is probably 1, but use the `list` command find out.

 The `help` command shows which commands are available, though at the time of writing, not every command is fully implemented.

--- a/docs/configuring-playbook-bridge-mx-puppet-skype.md
+++ b/docs/configuring-playbook-bridge-mx-puppet-skype.md
@@ -1,5 +0,0 @@
 # Setting up MX Puppet Skype (optional)

 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 unmaintaned for a long time.

 Bridging to [Skype](https://www.skype.com/) can also happen via the [go-skype-bridge](configuring-playbook-bridge-go-skype-bridge.md) bridge supported by the playbook.
--- a/docs/configuring-playbook-bridge-mx-puppet-slack.md
+++ b/docs/configuring-playbook-bridge-mx-puppet-slack.md
@@ -1,47 +0,0 @@
 # Setting up MX Puppet Slack (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.

 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.

 See the project page to learn what it does and why it might be useful to you.

 ## Setup

 To enable the [Slack](https://slack.com/) bridge:

 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
    ```

 ## 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).

 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.

 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.
--- a/docs/configuring-playbook-bridge-mx-puppet-steam.md
+++ b/docs/configuring-playbook-bridge-mx-puppet-steam.md
@@ -1,32 +0,0 @@
 # Setting up MX Puppet Steam (optional)

 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.

 To enable the [Steam](https://steampowered.com/) bridge just use the following
 playbook configuration:


 ```yaml
 matrix_mx_puppet_steam_enabled: true
 ```


 ## 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).

 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.

 Also send `help` to the bot to see the commands available.
--- a/docs/configuring-playbook-bridge-mx-puppet-twitter.md
+++ b/docs/configuring-playbook-bridge-mx-puppet-twitter.md
@@ -1,36 +0,0 @@
 # Setting up MX Puppet Twitter (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.

 See the project page 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.

 ```yaml
 matrix_mx_puppet_twitter_enabled: true
 matrix_mx_puppet_twitter_consumer_key: ''
 matrix_mx_puppet_twitter_consumer_secret: ''
 matrix_mx_puppet_twitter_access_token: ''
 matrix_mx_puppet_twitter_access_token_secret: ''
 matrix_mx_puppet_twitter_environment: ''
 ```


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

 Also send `help` to the bot to see the commands available.
--- a/docs/configuring-playbook-cactus-comments.md
+++ b/docs/configuring-playbook-cactus-comments.md
@@ -1,65 +0,0 @@
 # Setting up Cactus Comments (optional)

 The playbook can install and configure [Cactus Comments](https://cactus.chat) for you.

 Cactus Comments is a **federated comment system** built on Matrix. The role allows you to self-host the system.
 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.


 ## Configuration

 Add the following block to your `vars.yaml` and make sure to exchange the tokens to randomly generated values.

 ```yaml
 #################
 ## Cactus Chat ##
 #################

 matrix_cactus_comments_enabled: true

 # 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 dentrite as a homeserver)
 # If you don't know which one you use: The default is synapse ;)
 # matrix_synapse_allow_guest_access: true
 # matrix_dentrite_allow_guest_access
 ```

 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## Usage

 Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.

 To get started, send a `help` message to the `@bot.cactusbot:your-homeserver.com` bot to confirm it's working.
 Then, register a site by typing: `register <sitename>`. You will then be invited into a moderation room.
 Now you are good to go and can include the comment section on your website!

 **Careful:** To really make use of self-hosting you need change a few things in comparison to the official docs!

 Insert the following snippet into you page and make sure to replace `example.com` with your base domain!


 ```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">
 <div id="comment-section"></div>
 <script>
 initComments({
  node: document.getElementById("comment-section"),
  defaultHomeserverUrl: "https://matrix.example.com:8448",
  serverName: "example.com",
  siteName: "YourSiteName",
  commentSectionId: "1"
 })
 </script>
 ```
--- a/docs/configuring-playbook-client-cinny.md
+++ b/docs/configuring-playbook-client-cinny.md
@@ -1,21 +0,0 @@
 # Configuring 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.

 If you'd like cinny to be installed, add the following to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):

 ```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).

 If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):

 ```yaml
 matrix_server_fqn_cinny: "app.{{ matrix_domain }}"
 ```
--- a/docs/configuring-playbook-client-element.md
+++ b/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.
--- a/docs/configuring-playbook-client-hydrogen.md
+++ b/docs/configuring-playbook-client-hydrogen.md
@@ -1,21 +0,0 @@
 # Configuring 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.

 If you'd like Hydrogen to be installed, add the following to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):

 ```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).

 If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):

 ```yaml
 matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}"
 ```
--- a/docs/configuring-playbook-conduit.md
+++ b/docs/configuring-playbook-conduit.md
@@ -1,58 +0,0 @@
 # Configuring Conduit (optional)

 By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).

 **NOTES**:

 - **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


 ## Installation

 To use Conduit, you **generally** need the following additional `vars.yml` configuration:

 ```yaml
 matrix_homeserver_implementation: conduit
 ```

 However, since Conduit is difficult (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) when it comes to creating the first user account and 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 flow:

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

 Automatic appservice setup is currently unsupported when using conduit. After setting up the service as usual you may notice that it is unable to start.

 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:your.server.name: 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
    ```

--- a/docs/configuring-playbook-dimension.md
+++ b/docs/configuring-playbook-dimension.md
@@ -1,78 +0,0 @@
 # Setting up Dimension (optional)

 **[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.

 **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).


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


 ## Enable

 [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`):

 ```yaml
 matrix_dimension_enabled: true
 ```


 ## 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`):

 ```yaml
 matrix_dimension_admins:
  - "@user1:{{ matrix_domain }}"
  - "@user2:{{ 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.

 ## Access token

 We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username).
 Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.

 You are required to specify an access token (belonging to this new user) for Dimension to work.
 To get an access token for the Dimension user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).

 **Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**

 Add access token to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):

 ```yaml
 matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"
 ```

 For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens).


 ## Installation

 After these variables have been set, please run the following command to re-run setup and to restart Dimension:

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


 ## Jitsi domain

 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.

 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.


 ## Additional features

 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.

 You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).
--- a/docs/configuring-playbook-dynamic-dns.md
+++ b/docs/configuring-playbook-dynamic-dns.md
@@ -1,27 +0,0 @@
 # Dynamic DNS

 ## Setup

 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`:

 ```yaml
 matrix_dynamic_dns_enabled: true

 matrix_dynamic_dns_domain_configurations:
  - provider: domains.google.com
    protocol: dyndn2
    username: XXXXXXXXXXXXXXXX
    password: XXXXXXXXXXXXXXXX
    domain: "{{ matrix_domain }}"
 ```


 ## Additional Reading

 Additional resources:

 - https://matrix.org/docs/guides/free-small-matrix-server
--- a/docs/configuring-playbook-email.md
+++ b/docs/configuring-playbook-email.md
@@ -1,55 +0,0 @@
 # Adjusting email-sending settings (optional)

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

 By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `matrix_mailer_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.   


 ## 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).


 ## 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:

 ```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"
 ```

 **Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.


 ### 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`.

 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.

 ```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>" 
 ```

 ## 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`.
--- a/docs/configuring-playbook-email2matrix.md
+++ b/docs/configuring-playbook-email2matrix.md
@@ -1,76 +0,0 @@
 # Setting up Email2Matrix (optional)

 **Note**: email bridging can also happen via the [Postmoogle](configuring-playbook-bot-postmoogle.md) bot supported by the playbook.
 Postmoogle is much more powerful and easier to use, so we recommend that you use it, instead of Email2Matrix.

 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

 ### DNS configuration

 It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.DOMAIN`, as described in the [Configuring DNS](configuring-dns.md) documentation page.

 ### 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

 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.

 ### Creating a shared room

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

 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. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).

 ## Configuration

 After doing the preparation steps above, adjust your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration like this:

 ```yaml
 matrix_email2matrix_enabled: true

 matrix_email2matrix_matrix_mappings:
  - MailboxName: "my-mailbox"
    MatrixRoomId: "!someRoom:DOMAIN"
    MatrixHomeserverUrl: "https://matrix.DOMAIN"
    MatrixUserId: "@email2matrix:DOMAIN"
    MatrixAccessToken: "ACCESS_TOKEN_GOES_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"
    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.

 Re-run the playbook (`--tags=setup-email2matrix,start`) and try sending an email to `my-mailbox@matrix.DOMAIN`.
--- a/docs/configuring-playbook-etherpad.md
+++ b/docs/configuring-playbook-etherpad.md
@@ -1,48 +0,0 @@
 # 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)

 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

 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)

 ## 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`):

 ```yaml
 matrix_etherpad_enabled: true
 ```

 ## Set Dimension default to the self-hosted Etherpad

 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.

 ### Removing the integrated Etherpad chat

 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`

 ### Etherpad Admin access (optional)

 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`):

 ```yaml
 matrix_etherpad_admin_username: admin
 matrix_etherpad_admin_password: some-password
 ```

 The admin web-UI should then be available on: `https://dimension.<your-domain>/etherpad/admin`

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

 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.

 ## Known issues

 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`.
--- a/docs/configuring-playbook-external-postgres.md
+++ b/docs/configuring-playbook-external-postgres.md
@@ -1,31 +0,0 @@
 # 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.

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

 If you'd like to use an external Postgres server, use a custom `vars.yml` configuration like this:

 ```yaml
 matrix_postgres_enabled: false

 # Rewire Synapse to use your external Postgres server
 matrix_synapse_database_host: "your-postgres-server-hostname"
 matrix_synapse_database_user: "your-postgres-server-username"
 matrix_synapse_database_password: "your-postgres-server-password"
 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.
 ```

 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.

 The connection to your external Postgres server **will not be SSL encrypted**, as [we don't support that yet](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/89).
--- a/docs/configuring-playbook-federation.md
+++ b/docs/configuring-playbook-federation.md
@@ -1,66 +0,0 @@
 # 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.


 ## 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`):

 ```yaml
 matrix_synapse_federation_domain_whitelist:
 - example.com
 - another.com
 ```

 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`):

 ```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`):

 ```yaml
 matrix_synapse_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.

 **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
 # 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
 ```

 ## 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:

 ```
 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
 matrix_synapse_federation_port_enabled: false
 # Note that the following change might not be "required per se" but probably will be due to the proxying of the traffic through the CDN proxy servers (CloudFlare for instance). The security impact of doing this should be minimal as your CDN itself will encrypt the traffic no matter what on their proxy servers. You could however first try and see if federation works while setting the following to true.
 matrix_synapse_tls_federation_listener_enabled: false
 ```

 **Use this at you own risk as all the possible side-effects of doing this are not fully known. However, it has been tested and works fine and passes all the tests on <https://federationtester.matrix.org/> without issues.**
--- a/docs/configuring-playbook-jitsi.md
+++ b/docs/configuring-playbook-jitsi.md
@@ -1,164 +0,0 @@
 # Jitsi

 The playbook can install the [Jitsi](https://jitsi.org/) video-conferencing platform and integrate it with [Element](configuring-playbook-client-element.md).

 Jitsi installation is **not enabled by default**, because it's not a core component of Matrix services.

 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.


 ## Prerequisites

 Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record. See [Configuring DNS](configuring-dns.md).

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


 ## Installation

 Add this to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:

 ```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: ""
 ```


 ## (Optional) Configure Jitsi authentication and guests mode

 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:

 ```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"
 ```

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

 **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).


 ### (Optional) LDAP authentication

 The default authentication mode of Jitsi is `internal`, however LDAP is also supported. An example LDAP configuration could be:

 ```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
 ```

 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.


 ## (Optional) Making your Jitsi server work on a LAN

 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.

 The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `JVB_ADVERTISE_IPS` in enviornment variable to make it work.

 Here is how to do it in the playbook.

 Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:

 ```yaml
 matrix_jitsi_jvb_container_extra_arguments:
  - '--env "JVB_ADVERTISE_IPS=<Local IP address of the host>"'
 ```

 ## (Optional) Fine tune Jitsi

 Sample **additional** `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration to save up resources (explained below):

 ```yaml
 matrix_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:

 You may wish to **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.

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

 You may want to **limit the maximum video resolution**, to save up resources on both server and clients.


 ## Apply changes

 Then re-run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`


 ## 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 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.DOMAIN`

 **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).


 ## Troubleshooting

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

 We normally don't require such manual intervention for other services, but Jitsi services generate a lot of configuration files on their own.

 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:

 - 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`)
--- a/docs/configuring-playbook-ldap-auth.md
+++ b/docs/configuring-playbook-ldap-auth.md
@@ -1,39 +0,0 @@
 # Setting up the LDAP authentication password provider module (optional, advanced)

 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.

 If you decide that you'd like to let this playbook install it for you, you need some configuration like this:

 ```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_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"
 matrix_synapse_ext_password_provider_ldap_attributes_mail: "mail"
 matrix_synapse_ext_password_provider_ldap_attributes_name: "cn"
 matrix_synapse_ext_password_provider_ldap_bind_dn: ""
 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:

 ```yaml
 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).


 ## 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).
--- a/docs/configuring-playbook-ma1sd.md
+++ b/docs/configuring-playbook-ma1sd.md
@@ -1,133 +0,0 @@
 # Adjusting ma1sd Identity Server configuration (optional)

 The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you.

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

 This server 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.*

 **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).

 To enable ma1sd, use the following additional configuration in your `vars.yml` file:

 ```yaml
 matrix_ma1sd_enabled: true
 ```


 ## 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:

 ```yaml
 matrix_ma1sd_matrixorg_forwarding_enabled: true
 ```


 ## 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/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_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

 - 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

 - `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).


 ## 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. The following configuration can be used to authenticate against an LDAP server:

 ```yaml
 matrix_synapse_ext_password_provider_rest_auth_enabled: true

 # matrix-ma1sd is the hostname of the ma1sd Docker container
 matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-ma1sd:8090"

 matrix_ma1sd_configuration_extension_yaml: |
  ldap:
    enabled: true
    connection:
      host: ldapHostnameOrIp
      tls: false
      port: 389
      baseDNs: ['OU=Users,DC=example,DC=org']
      bindDn: CN=My ma1sd User,OU=Users,DC=example,DC=org
      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

 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:

 ```yaml
 matrix_ma1sd_configuration_extension_yaml: |
  threepid:
    medium:
      msisdn:
        connectors:
          twilio:
            account_sid: '<secret-SID>'
            auth_token: '<secret-token>'
            number: '+<msisdn-number>'
 ```

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

 ```yaml
 matrix_ma1sd_configuration_extension_yaml: |
  register:
    policy:
      allowed: true
      threepid:
        email:
          domain:
            blacklist: ~
            whitelist: ~
 ```

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

 Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`):

 ```yaml
 matrix_ma1sd_verbose_logging: true
 ```
--- a/docs/configuring-playbook-matrix-corporal.md
+++ b/docs/configuring-playbook-matrix-corporal.md
@@ -1,131 +0,0 @@
 # 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.

 -------------------------------------

 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.

 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)


 ## Playbook configuration

 You would then need some configuration like this:

 ```yaml
 # The Shared Secret Auth password provider module is required for Corporal to work.
 # See configuring-playbook-shared-secret-auth.md
 matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
 matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE

 # When matrix-corporal is acting as the primary authentication provider,
 # you need to set up the REST authentication password provider module
 # to make Interactive User Authentication work.
 # This is necessary for certain user actions (like E2EE, device management, etc).
 #
 # See configuring-playbook-rest-auth.md
 matrix_synapse_ext_password_provider_rest_auth_enabled: true
 matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-corporal:41080/_matrix/corporal"

 matrix_corporal_enabled: true

 # See below for an example of how to use a locally-stored static policy
 matrix_corporal_policy_provider_config: |
  {
    "Type": "http",
    "Uri": "https://intranet.example.com/matrix/policy",
    "AuthorizationBearerToken": "SOME_SECRET",
    "CachePath": "/var/cache/matrix-corporal/last-policy.json",
    "ReloadIntervalSeconds": 1800,
    "TimeoutMilliseconds": 300
  }

 # 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).
 # 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"

 # Because Corporal peridoically performs lots of user logins from the same IP,
 # you may need raise Synapse's ratelimits.
 # The values below are just an example. Tweak to your use-case (number of users, etc.)
 matrix_synapse_rc_login:
  address:
    per_second: 50
    burst_count: 300
  account:
    per_second: 0.17
    burst_count: 3
  failed_attempts:
    per_second: 0.17
    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:

 - 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

 - the Matrix Corporal user is joined and has Admin/Moderator-level access to any rooms you want it to manage

 ### Using a locally-stored static policy

 If you'd like to use a [static policy file](https://github.com/devture/matrix-corporal/blob/master/docs/policy-providers.md#static-file-pull-style-policy-provider), you can use a configuration like this:

 ```yaml
 matrix_corporal_policy_provider_config: |
  {
    "Type": "static_file",
    "Path": "/etc/matrix-corporal/policy.json"
  }

 # Modify the policy below as you see fit
 matrix_aux_file_definitions:
  - dest: "{{ matrix_corporal_config_dir_path }}/policy.json"
    content: |
      {
        "schemaVersion": 1,
        "identificationStamp": "stamp-1",
        "flags": {
          "allowCustomUserDisplayNames": false,
          "allowCustomUserAvatars": false,
          "forbidRoomCreation": false,
          "forbidEncryptedRoomCreation": true,
          "forbidUnencryptedRoomCreation": false,
          "allowCustomPassthroughUserPasswords": true,
          "allowUnauthenticatedPasswordResets": false,
          "allow3pidLogin": false
        },
        "managedCommunityIds": [],
        "managedRoomIds": [],
        "users": []
      }
 ```

 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`).


 ## Matrix Corporal files

 The following local filesystem paths are mounted in the `matrix-corporal` container and can be used in your configuration (or policy):

 - `/matrix/corporal/config` is mounted at `/etc/matrix-corporal` (read-only)

 - `/matrix/corporal/var` is mounted at `/var/matrix-corporal` (read and write)

 - `/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).
--- a/docs/configuring-playbook-matrix-ldap-registration-proxy.md
+++ b/docs/configuring-playbook-matrix-ldap-registration-proxy.md
@@ -1,33 +0,0 @@
 # 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.

 **Please note:** This does support the full Matrix specification for registrations. It only provide a very coarse
 implementation of a basic password registration.

 ## Quickstart

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:

 ```yaml
 matrix_ldap_registration_proxy_enabled: true
 # LDAP credentials
 matrix_ldap_registration_proxy_ldap_uri: <URI>
 matrix_ldap_registration_proxy_ldap_base_dn: <DN>
 matrix_ldap_registration_proxy_ldap_user: <USER>
 matrix_ldap_registration_proxy_ldap_password: <password>
 ```

 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 }}"
 ```

--- a/docs/configuring-playbook-matrix-registration.md
+++ b/docs/configuring-playbook-matrix-registration.md
@@ -1,68 +0,0 @@
 # 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.

 > matrix-registration 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.

 **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`


 ## Installing

 Adjust your playbook configuration (your `inventory/host_vars/matrix.DOMAIN/vars.yml` file):

 ```yaml
 matrix_registration_enabled: true

 # Generate a strong secret using: `pwgen -s 64 1`.
 matrix_registration_admin_secret: "ENTER_SOME_SECRET_HERE"
 ```

 Then, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## Usage

 **matrix-registration** gets exposed at `https://matrix.DOMAIN/matrix-registration`

 It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) - for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using `curl`.

 We make the most common APIs easy to use via the playbook (see below).


 ### Creating registration tokens

 To **create a new user registration token (link)**, use this command:

 ```bash
 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.

 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
 ansible-playbook -i inventory/hosts setup.yml \
 --tags=list-matrix-registration-tokens
 ```
--- a/docs/configuring-playbook-mautrix-bridges.md
+++ b/docs/configuring-playbook-mautrix-bridges.md
@@ -1,111 +0,0 @@
 # Setting up a Generic Mautrix Bridge (optional)

 The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, facebook, instagram, signal, hangouts, googlechat, etc.), as well as many other (non-mautrix) bridges.
 This is a common guide for configuring mautrix bridges.

 You can see each bridge's features at in the `ROADMAP.md` file in its corresponding [mautrix](https://github.com/mautrix) repository.

 To enable a bridge add:


 ```yaml
 # Replace SERVICENAME with one of: twitter, facebook, instagram, ..
 matrix_mautrix_SERVICENAME_enabled: true
 ```

 to your `vars.yml`

 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.

 You can add

 ```yaml
 matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
 ```
 to `vars.yml` to **configure a user as an administrator for all bridges**.
 **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:
      '@YOUR_USERNAME:{{ matrix_domain }}': admin
 ```

 Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
 ```yaml
 matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
  bridge:
    encryption:
      allow: true
      default: 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:
    permissions:
      '@YOUR_USERNAME:{{ matrix_domain }}': admin
    encryption:
      allow: true
      default: true
 ```

 ## Setting the bot's username

 ```yaml
 matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
 ```

 Can be used to set the username for the bridge.

 ## Discovering additional configuration options

 You may wish to look at `roles/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure.


 ## Set up Double Puppeting

 To set up  [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html)

 please do so 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 by adding

 ```yaml
 matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
 matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE
 ```

 You should generate a strong shared secret with a command like this: pwgen -s 64 1

 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.

 ## Controlling the logging level

 ```yaml
 matrix_mautrix_SERVICENAME_logging_level: WARN
 ```

 to `vars.yml` to control the logging level, where you may 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 will generally be more helpful.


 ## Usage

 You then need to start a chat with `@SERVICENAMEbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain). 

 Send `login ` to the bridge bot to get started You can learn more here about authentication from the bridge's official documentation on Authentication https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html  .

 If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.



 ## 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.
 Reporting bridge bugs should happen upstream, in the corresponding mautrix repository, not to us.
--- a/docs/configuring-playbook-nginx.md
+++ b/docs/configuring-playbook-nginx.md
@@ -1,84 +0,0 @@
 # Configure Nginx (optional, advanced)

 By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
 If that's alright, you can skip this.


 ## Using Nginx status

 This will serve a statuspage to the hosting machine only. Useful for monitoring software like [longview](https://www.linode.com/docs/platform/longview/longview-app-for-nginx/)

 ```yaml
 matrix_nginx_proxy_proxy_matrix_nginx_status_enabled: true
 ```

 This will serve the status page under the following addresses:
 - `http://matrix.DOMAIN/nginx_status` (using HTTP)
 - `https://matrix.DOMAIN/nginx_status` (using HTTPS)

 By default, if ```matrix_nginx_proxy_nginx_status_enabled``` is enabled, access to the status page would be allowed from the local IP address of the server. If you wish to allow access from other IP addresses, you can provide them as a list:

 ```yaml
 matrix_nginx_proxy_proxy_matrix_nginx_status_allowed_addresses:
 - 8.8.8.8
 - 1.1.1.1
 ```

 ## Adjusting SSL in your server

 You can adjust how the SSL is served by the nginx server using the `matrix_nginx_proxy_ssl_preset` variable. We support a few presets, based on the Mozilla Server Side TLS
 Recommended configurations. These presets influence the TLS Protocol, the SSL Cipher Suites and the `ssl_prefer_server_ciphers` variable of nginx.
 Possible values are:

 - `"modern"` - For Modern clients that support TLS 1.3, with no need for backwards compatibility
 - `"intermediate"` (**default**) - Recommended configuration for a general-purpose server
 - `"old"` - Services accessed by very old clients or libraries, such as Internet Explorer 8 (Windows XP), Java 6, or OpenSSL 0.9.8

 **Be really carefull when setting it to `"modern"`**. This could break comunication with other Matrix servers, limiting your federation posibilities.

 Besides changing the preset (`matrix_nginx_proxy_ssl_preset`), you can also directly override these 3 variables:

 - `matrix_nginx_proxy_ssl_protocols`: for specifying the supported TLS protocols.
 - `matrix_nginx_proxy_ssl_prefer_server_ciphers`: for specifying if the server or the client choice when negotiating the cipher. It can set to `on` or `off`.
 - `matrix_nginx_proxy_ssl_ciphers`: for specifying the SSL Cipher suites used by nginx.

 For more information about these variables, check the `roles/matrix-nginx-proxy/defaults/main.yml` file.

 ## Synapse + OpenID Connect for Single-Sign-On

 If you want to use OpenID Connect as an SSO provider (as per the [Synapse OpenID docs](https://github.com/matrix-org/synapse/blob/develop/docs/openid.md)), you need to use the following configuration (in your `vars.yml` file) to instruct nginx to forward `/_synapse/oidc` to Synapse:

 ```yaml
 matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_oidc_api_enabled: true
 ```

 ## Disable Nginx access logs

 This will disable the access logging for nginx.

 ```yaml
 matrix_nginx_proxy_access_log_enabled: false
 ```

 ## Additional configuration

 This playbook also allows for additional configuration to be applied to the nginx server.

 If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable (as mentioned in the [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) documentation as well). Make sure that you have set the DNS configuration for the domains you want to include to point at your server.

 ```yaml
 matrix_ssl_additional_domains_to_obtain_certificates_for:
  - domain.one.example
  - domain.two.example
 ```

 You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable.

 ```yaml
 matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks:
  - |
    # These lines will be included in the nginx configuration.
    # This is at the top level of the file, so you will need to define all of the `server { ... }` blocks.
  - |
    # For advanced use, have a look at the template files in `roles/matrix-nginx-proxy/templates/nginx/conf.d`
 ```
--- a/docs/configuring-playbook-ntfy.md
+++ b/docs/configuring-playbook-ntfy.md
@@ -1,94 +0,0 @@
 # Setting up ntfy (optional)

 The playbook can install and configure the [ntfy](https://ntfy.sh/) push notifications server for you.

 Using the [UnifiedPush](https://unifiedpush.org) standard, ntfy enables self-hosted (Google-free) push notifications from Matrix (and other) servers to UnifiedPush-compatible matrix compatible client apps running on Android and other devices.

 This role is intended to support UnifiedPush notifications for use with the Matrix and Matrix-related services that this playbook installs. This role is not intended to support all of ntfy's other features.

 **Note**: In contrast to push notifications using Google's FCM or Apple's APNs, the use of UnifiedPush allows each end-user to choose the push notification server that they prefer.  As a consequence, deploying this ntfy server does not by itself ensure any particular user or device or client app will use it.


 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):

 ```yaml
 # Enabling it is the only required setting
 matrix_ntfy_enabled: true

 # Some other options
 matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
 matrix_ntfy_configuration_extension_yaml: |
  log_level: DEBUG
 ```

 For a more complete list of variables that you could override, see `roles/matrix-ntfy/defaults/main.yml`.

 For a complete list of ntfy config options that you could put in `matrix_ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).


 ## Installing

 Don't forget to add `ntfy.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## Usage

 To make use of your ntfy installation, on Android for example, you need two things:

 * the `ntfy` app
 * a UnifiedPush-compatible matrix app

 You need to install the `ntfy` app on each device on which you want to receive push notifications through your ntfy server. The `ntfy` app will provide UnifiedPush notifications to any number of UnifiedPush-compatible messaging apps installed on the same device.

 ### Setting up the `ntfy` Android app

 1. Install the [ntfy Android app](https://ntfy.sh/docs/subscribe/phone/) from F-droid or Google Play.
 2. In its Settings -> `General: Default server`, enter your ntfy server URL, such as `https://ntfy.DOMAIN`.
 3. In its Settings -> `Advanced: Connection protocol`, choose `WebSockets`.

 That is all you need to do in the ntfy app. It has many other features, but for our purposes you can ignore them. In particular you do not need to follow any instructions about subscribing to a notification topic as UnifiedPush will do that automatically.

 ### Setting up a UnifiedPush-compatible matrix app

 Install any UnifiedPush-enabled matrix app on that same device. The matrix app will learn from the `ntfy` app that you have configured UnifiedPush on this device, and then it will tell your matrix server to use it.

 Steps needed for specific matrix apps:

 * FluffyChat-android:
  - Should auto-detect and use it. No manual settings.

 * SchildiChat-android:
  1. enable `Settings` -> `Notifications` -> `UnifiedPush: Force custom push gateway`.
  2. choose `Settings` -> `Notifications` -> `UnifiedPush: Re-register push distributor`. *(For info, a more complex alternative to achieve the same is: delete the relevant unifiedpush registration in `ntfy` app, force-close SchildiChat, re-open it.)*
  3. verify `Settings` -> `Notifications` -> `UnifiedPush: Notification targets` as described below in the "Troubleshooting" section.

 * Element-android v1.4.26+:
  1. choose `Settings` -> `Notifications` -> `Notification method` -> `ntfy`
  2. verify `Settings` -> `Troubleshoot` -> `Troubleshoot notification settings`

 If the matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy".

 If the matrix app doesn't seem to pick it up, try restarting it and try the Troubleshooting section below.


 ## Troubleshooting

 First check that the matrix client app you are using supports UnifiedPush. There may well be different variants of the app.

 Set the ntfy server's log level to 'DEBUG', as shown in the example settings above, and watch the server's logs with `sudo journalctl -fu matrix-ntfy`.

 To check if UnifiedPush is correctly configured on the client device, look at "Settings -> Notifications -> Notification Targets" in Element-Android or SchildiChat, or "Settings -> Notifications -> Devices" in FluffyChat. There should be one entry for each matrix client app that has enabled push notifications, and when that client is using UnifiedPush you should see a URL that begins with your ntfy server's URL.

 In the "Notification Targets" screen in Element-Android or SchildiChat, two relevant URLs are shown, "push\_key" and "Url", and both should begin with your ntfy server's URL. If "push\_key" shows your server but "Url" shows an external server such as `up.schildi.chat` then push notifications will still work but are being routed through that external server before they reach your ntfy server. To rectify that, in SchildiChat (at least around version 1.4.20.sc55) you must enable the `Force custom push gateway` setting as described in the "Usage" section above.

 If it is not working, useful tools are "Settings -> Notifications -> Re-register push distributor" and "Settings -> Notifications -> Troubleshoot Notifications" in SchildiChat (possibly also Element-Android). In particular the "Endpoint/FCM" step of that troubleshooter should display your ntfy server's URL that it has discovered from the ntfy client app.

 The simple [UnifiedPush troubleshooting](https://unifiedpush.org/users/troubleshooting/) app [UP-Example](https://f-droid.org/en/packages/org.unifiedpush.example/) can be used to manually test UnifiedPush registration and operation on an Android device.
--- a/docs/configuring-playbook-own-webserver.md
+++ b/docs/configuring-playbook-own-webserver.md
@@ -1,257 +0,0 @@
 # Using your own webserver, instead of this playbook's nginx proxy (optional, advanced)

 By default, this playbook installs its own nginx webserver (called `matrix-nginx-proxy`, in a Docker container) which listens on ports 80 and 443.
 If that's alright, you can skip this.

 If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
 and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.

 You should note, however, that the playbook's services work best when you keep using the integrated `matrix-nginx-proxy` webserver.
 For example, disabling `matrix-nginx-proxy` when running a [Synapse worker setup for load-balancing](configuring-playbook-synapse.md#load-balancing-with-workers) (a more advanced, non-default configuration) is likely to cause various troubles (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090)). If you need a such more scalable setup, disabling `matrix-nginx-proxy` will be a bad idea. If yours will be a simple (default, non-worker-load-balancing) deployment, disabling `matrix-nginx-proxy` may be fine.

 There are **2 ways you can go about it**, if you'd like to use your own webserver:

 - [Method 1: Disabling the integrated nginx reverse-proxy webserver](#method-1-disabling-the-integrated-nginx-reverse-proxy-webserver)

 - [Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy](#method-2-fronting-the-integrated-nginx-reverse-proxy-webserver-with-another-reverse-proxy)


 ## Method 1: Disabling the integrated nginx reverse-proxy webserver

 This method is about completely disabling the integrated nginx reverse-proxy webserver and replicating its behavior using another webserver.
 For an alternative, make sure to check Method #2 as well.

 ### Preparation

 No matter which external webserver you decide to go with, you'll need to:

 1) Make sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group. When using an external nginx webserver, this allows it to read configuration files from `/matrix/nginx-proxy/conf.d`. When using another server, it would make other files, such as `/matrix/static-files/.well-known`, accessible to it.

 2) Edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`)
   - to disable the integrated nginx server:

        ```yaml
        matrix_nginx_proxy_enabled: false
        ```
    - if using an external server on another host, add the `<service>_http_host_bind_port` or `<service>_http_bind_port` variables for the services that will be exposed by the external server on the other host. The actual name of the variable is listed in the `roles/<service>/defaults/vars.yml` file for each service. Most variables follow the `<service>_http_host_bind_port` format.
       
      These variables will make Docker expose the ports on all network interfaces instead of localhost only.
      [Keep in mind that there are some security concerns if you simply proxy everything.](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints)

      Here are the variables required for the default configuration (Synapse and Element)
       ```
        matrix_synapse_container_client_api_host_bind_port: '0.0.0.0:8008'
        matrix_synapse_container_federation_api_plain_host_bind_port: '0.0.0.0:8048'
        matrix_client_element_container_http_host_bind_port: "0.0.0.0:8765"
       ```

 3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable SSL certificate retrieval:

 ```yaml
 matrix_ssl_retrieval_method: none
 ```

 **Note**: During [installation](installing.md), unless you've disabled SSL certificate management (`matrix_ssl_retrieval_method: none`), the playbook would need 80 to be available, in order to retrieve SSL certificates. **Please manually stop your other webserver while installing**. You can start it back up afterwards.

 ### Using your own external nginx webserver

 Once you've followed the [Preparation](#preparation) guide above, it's time to set up your external nginx server.

 Even with `matrix_nginx_proxy_enabled: false`, the playbook still generates some helpful files for you in `/matrix/nginx-proxy/conf.d`.
 Those configuration files are adapted for use with an external web server (one not running in the container network).

 You can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your own `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`

 Note that if your nginx version is old, it might not like our default choice of SSL protocols (particularly the fact that the brand new `TLSv1.3` protocol is enabled). You can override the protocol list by redefining the `matrix_nginx_proxy_ssl_protocols` variable. Example:

 ```yaml
 # Custom protocol list (removing `TLSv1.3`) to suit your nginx version.
 matrix_nginx_proxy_ssl_protocols: "TLSv1.2"
 ```

 If you are experiencing issues, try updating to a newer version of Nginx. As a data point in May 2021 a user reported that Nginx 1.14.2 was not working for them. They were getting errors about socket leaks. Updating to Nginx 1.19 fixed their issue.

 ### Using your own external Apache webserver

 Once you've followed the [Preparation](#preparation) guide above, you can take a look at the [examples/apache](../examples/apache) directory for a sample configuration.

 ### Using your own external caddy webserver

 After following  the [Preparation](#preparation) guide above, you can take a look at the [examples/caddy](../examples/caddy) directory and [examples/caddy2](../examples/caddy2) directory for a sample configuration for Caddy v1 and v2, respectively.

 ### Using your own HAproxy reverse proxy
 After following  the [Preparation](#preparation) guide above, you can take a look at the [examples/haproxy](../examples/haproxy) directory for a sample configuration. In this case HAproxy is used as a reverse proxy and a simple Nginx container is used to serve statically `.well-known` files.

 ### Using another external webserver

 Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/matrix-nginx-proxy/templates/nginx/conf.d/).


 ## Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy

 This method is about leaving the integrated nginx reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).

 If you wish to use another webserver, the integrated nginx reverse-proxy webserver usually gets in the way because it attempts to fetch SSL certificates and binds to ports 80, 443 and 8448 (if Matrix Federation is enabled).

 You can disable such behavior and make the integrated nginx reverse-proxy webserver only serve traffic locally (or over a local network).

 You would need some configuration like this:

 ```yaml
 # Do not retrieve SSL certificates. This shall be managed by another webserver or other means.
 matrix_ssl_retrieval_method: none

 # Do not try to serve HTTPS, since we have no SSL certificates.
 # Disabling this also means services will be served on the HTTP port
 # (`matrix_nginx_proxy_container_http_host_bind_port`).
 matrix_nginx_proxy_https_enabled: false

 # Do not listen for HTTP on port 80 globally (default), listen on the loopback interface.
 # If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
 matrix_nginx_proxy_container_http_host_bind_port: '127.0.0.1:81'

 # Likewise, expose the Matrix Federation port on the loopback interface.
 # Since `matrix_nginx_proxy_https_enabled` is set to `false`, this federation port will serve HTTP traffic.
 # If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
 #
 # You'd most likely need to expose it publicly on port 8448 (8449 was chosen for the local port to prevent overlap).
 matrix_nginx_proxy_container_federation_host_bind_port: '127.0.0.1:8449'

 # Coturn relies on SSL certificates that have already been obtained.
 # Since we don't obtain any certificates (`matrix_ssl_retrieval_method: none` above), it won't work by default.
 # An alternative is to tweak some of: `matrix_coturn_tls_enabled`, `matrix_coturn_tls_cert_path` and `matrix_coturn_tls_key_path`.
 matrix_coturn_enabled: false

 # Trust the reverse proxy to send the correct `X-Forwarded-Proto` header as it is handling the SSL connection.
 matrix_nginx_proxy_trust_forwarded_proto: true

 # Trust and use the other reverse proxy's `X-Forwarded-For` header.
 matrix_nginx_proxy_x_forwarded_for: '$proxy_add_x_forwarded_for'
 ```

 With this, nginx would still be in use, but it would not bother with anything SSL related or with taking up public ports.

 All services would be served locally on `127.0.0.1:81` and `127.0.0.1:8449` (as per the example configuration above).

 You can then set up another reverse-proxy server on ports 80/443/8448 for all of the expected domains and make traffic go to these local ports.
 The expected domains vary depending on the services you have enabled (`matrix.DOMAIN` for sure; `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN` are optional).

 ### Sample configuration for running behind Traefik 2.0

 Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.

 ```yaml
 # Disable generation and retrieval of SSL certs
 matrix_ssl_retrieval_method: none

 # Configure Nginx to only use plain HTTP
 matrix_nginx_proxy_https_enabled: false

 # Don't bind any HTTP or federation port to the host
 # (Traefik will proxy directly into the containers)
 matrix_nginx_proxy_container_http_host_bind_port: ''
 matrix_nginx_proxy_container_federation_host_bind_port: ''

 # Trust the reverse proxy to send the correct `X-Forwarded-Proto` header as it is handling the SSL connection.
 matrix_nginx_proxy_trust_forwarded_proto: true

 # Trust and use the other reverse proxy's `X-Forwarded-For` header.
 matrix_nginx_proxy_x_forwarded_for: '$proxy_add_x_forwarded_for'

 # Disable Coturn because it needs SSL certs
 # (Clients can, though exposing IP address, use Matrix.org TURN)
 matrix_coturn_enabled: false

 # All containers need to be on the same Docker network as Traefik
 # (This network should already exist and Traefik should be using this network)
 matrix_docker_network: 'traefik'

 matrix_nginx_proxy_container_extra_arguments:
  # May be unnecessary depending on Traefik config, but can't hurt
  - '--label "traefik.enable=true"'

  # The Nginx proxy container will receive traffic from these subdomains
  - '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`{{ matrix_server_fqn_matrix }}`,`{{ matrix_server_fqn_element }}`,`{{ matrix_server_fqn_dimension }}`,`{{ matrix_server_fqn_jitsi }}`)"'

  # (The 'web-secure' entrypoint must bind to port 443 in Traefik config)
  - '--label "traefik.http.routers.matrix-nginx-proxy.entrypoints=web-secure"'

  # (The 'default' certificate resolver must be defined in Traefik config)
  - '--label "traefik.http.routers.matrix-nginx-proxy.tls.certResolver=default"'

  # The Nginx proxy container uses port 8080 internally
  - '--label "traefik.http.services.matrix-nginx-proxy.loadbalancer.server.port=8080"'

 matrix_synapse_container_extra_arguments:
  # May be unnecessary depending on Traefik config, but can't hurt
  - '--label "traefik.enable=true"'

  # The Synapse container will receive traffic from this subdomain
  - '--label "traefik.http.routers.matrix-synapse.rule=Host(`{{ matrix_server_fqn_matrix }}`)"'

  # (The 'synapse' entrypoint must bind to port 8448 in Traefik config)
  - '--label "traefik.http.routers.matrix-synapse.entrypoints=synapse"'

  # (The 'default' certificate resolver must be defined in Traefik config)
  - '--label "traefik.http.routers.matrix-synapse.tls.certResolver=default"'

  # The Synapse container uses port 8048 internally
  - '--label "traefik.http.services.matrix-synapse.loadbalancer.server.port=8048"'
 ```

 This method uses labels attached to the Nginx and Synapse containers to provide the Traefik Docker provider with the information it needs to proxy `matrix.DOMAIN`, `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN`. Some [static configuration](https://docs.traefik.io/v2.0/reference/static-configuration/file/) is required in Traefik; namely, having endpoints on ports 443 and 8448 and having a certificate resolver.

 Note that this configuration on its own does **not** redirect traffic on port 80 (plain HTTP) to port 443 for HTTPS, which may cause some issues, since the built-in Nginx proxy usually does this. If you are not already doing this in Traefik, it can be added to Traefik in a [file provider](https://docs.traefik.io/v2.0/providers/file/) as follows:

 ```toml
 [http]
  [http.routers]
    [http.routers.redirect-http]
      entrypoints = ["web"] # The 'web' entrypoint must bind to port 80
      rule = "HostRegexp(`{host:.+}`)" # Change if you don't want to redirect all hosts to HTTPS
      service = "dummy" # Unused, but all routers need services (for now)
      middlewares = ["https"]
  [http.services]
    [http.services.dummy.loadbalancer]
      [[http.services.dummy.loadbalancer.servers]]
        url = "localhost"
  [http.middlewares]
    [http.middlewares.https.redirectscheme]
      scheme = "https"
      permanent = true
 ```

 You can use the following `docker-compose.yml` as example to launch Traefik.

 ```yaml
 version: "3.3"

 services:

  traefik:
    image: "traefik:v2.3"
    restart: always
    container_name: "traefik"
    networks:
      - traefik
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.network=traefik"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web-secure.address=:443"
      - "--entrypoints.synapse.address=:8448"
      - "--certificatesresolvers.default.acme.tlschallenge=true"
      - "--certificatesresolvers.default.acme.email=YOUR EMAIL"
      - "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
    ports:
      - "443:443"
      - "8448:8448"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"

 networks:
  traefik:
    external: true
 ```
--- a/docs/configuring-playbook-postgres-backup.md
+++ b/docs/configuring-playbook-postgres-backup.md
@@ -1,35 +0,0 @@
 # Setting up postgres backup (optional)

 The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you.

 For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [borg backup](configuring-playbook-backup-borg.md) instead.


 ## Adjusting the playbook configuration

 Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:

 ```yaml
 matrix_postgres_backup_enabled: true
 ```

 Refer to the table below for additional configuration variables and their default values.


 | Name                              | Default value                | Description                                                      |
 | :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
 |`matrix_postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
 |`matrix_postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
 |`matrix_postgres_backup_keep_days`|`7`|Number of daily backups to keep|
 |`matrix_postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
 |`matrix_postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
 |`matrix_postgres_backup_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Storagepath for the database backups|


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
--- a/docs/configuring-playbook-prometheus-grafana.md
+++ b/docs/configuring-playbook-prometheus-grafana.md
@@ -1,133 +0,0 @@
 # Enabling metrics and graphs for your Matrix server (optional)

 It can be useful to have some (visual) insight into the performance of your homeserver.

 You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):

 Remember to add `stats.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.

 ```yaml
 matrix_prometheus_enabled: true

 # You can remove this, if unnecessary.
 matrix_prometheus_node_exporter_enabled: true

 # You can remove this, if unnecessary.
 matrix_prometheus_postgres_exporter_enabled: true

 matrix_grafana_enabled: true

 matrix_grafana_anonymous_access: false

 # This has no relation to your Matrix user id. It can be any username you'd like.
 # Changing the username subsequently won't work.
 matrix_grafana_default_admin_user: "some_username_chosen_by_you"

 # Changing the password subsequently won't work.
 matrix_grafana_default_admin_password: "some_strong_password_chosen_by_you"
 ```

 By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.<your-domain>`.

 The retention policy of Prometheus metrics is [15 days by default](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects). Older data gets deleted automatically.


 ## What does it do?

 Name | Description
 -----|----------
 `matrix_prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
 `matrix_prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
 `matrix_prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
 `matrix_grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
 `matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
 `matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here


 ## Security and privacy

 Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.

 Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `matrix_prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.


 ## Collecting metrics to an external Prometheus server

 **If the integrated Prometheus server is enabled** (`matrix_prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".

 When you'd like **to collect metrics from an external Prometheus server**, you need to expose service metrics outside of the container network.

 The playbook provides a single endpoint (`https://matrix.DOMAIN/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/hookshot`, etc). To enable this `/metrics/*` feature, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled` below.

 The following variables may be of interest:

 Name | Description
 -----|----------
 `matrix_nginx_proxy_proxy_matrix_metrics_enabled`|Set this to `true` to enable metrics exposure for various services on `https://matrix.DOMAIN/metrics/*`. Refer to the individual `matrix_SERVICE_metrics_proxying_enabled` variables below for exposing metrics for each individual service.
 `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.DOMAIN/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials). When enabled, all endpoints beneath `/metrics` will be protected with the same credentials
 `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_username`|Set this to the Basic Authentication username you'd like to protect `/metrics/*` with. You also need to set `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password`. If one username/password pair is not enough, you can leave the `username` and `password` variables unset and use `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_raw_content` instead
 `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password`|Set this to the Basic Authentication password you'd like to protect `/metrics/*` with
 `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_raw_content`|Set this to the Basic Authentication credentials (raw `htpasswd` file content) used to protect `/metrics/*`. This htpasswd-file needs to be generated with the `htpasswd` tool and can include multiple username/password pairs. If you only need one credential, use `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_username` and `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password` instead.
 `matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
 `matrix_synapse_metrics_proxying_enabled`|Set this to `true` to expose Synapse's metrics on `https://matrix.DOMAIN/metrics/synapse/main-process` and `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`). Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`).
 `matrix_prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network)
 `matrix_prometheus_node_exporter_metrics_proxying_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
 `matrix_prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
 `matrix_prometheus_postgres_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
 `matrix_bridge_hookshot_metrics_enabled`|Set this to `true` to make [Hookshot](configuring-playbook-bridge-hookshot.md) expose metrics (locally, on the container network)
 `matrix_bridge_hookshot_metrics_proxying_enabled`|Set this to `true` to expose the [Hookshot](configuring-playbook-bridge-hookshot.md) metrics on `https://matrix.DOMAIN/metrics/hookshot` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
 `matrix_SERVICE_metrics_proxying_enabled`|Various other services/roles may provide similar `_metrics_enabled` and `_metrics_proxying_enabled` variables for exposing their metrics. Refer to each role for details. Only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`
 `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks`|Add nginx `location` blocks to this list if you'd like to expose additional exporters manually (see below)

 Example for how to make use of `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks` for exposing additional metrics locations:
 ```nginx
 matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks:
  - 'location /metrics/another-service {
  resolver 127.0.0.11 valid=5s;
  proxy_pass http://matrix-another-service:9100/metrics;
  }'
 ```

 Using `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks` only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true` (see above).

 Note : The playbook will hash the basic_auth password for you on setup. Thus, you need to give the plain-text version of the password as a variable.

 ### Collecting Synapse worker metrics to an external Prometheus server

 If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.DOMAIN/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`.

 The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`.
 It will look a bit like this:
 ```yaml
 scrape_configs:
  - job_name: 'synapse'
    metrics_path: /metrics/synapse/main-process
    scheme: https
    basic_auth:
      username: prometheus
      password_file: /etc/prometheus/password.pwd
    static_configs:
      - targets: ['matrix.DOMAIN:443']
        labels:
          job: "master"
          index: 1
  - job_name: 'matrix-synapse-synapse-worker-generic-worker-0'
    metrics_path: /metrics/synapse/worker/generic-worker-0
    scheme: https
    basic_auth:
      username: prometheus
      password_file: /etc/prometheus/password.pwd
    static_configs:
      - targets: ['matrix.DOMAIN:443']
        labels:
          job: "generic_worker"
          index: 18111
 ```


 ## More information

 - [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
 - [The Prometheus scraping rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus) (we use v2)
 - [The Synapse Grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana)
 - [The Node Exporter dashboard](https://github.com/rfrail3/grafana-dashboards) (for generic non-synapse performance graphs)
--- a/docs/configuring-playbook-prometheus-postgres.md
+++ b/docs/configuring-playbook-prometheus-postgres.md
@@ -1,25 +0,0 @@
 # Enabling metrics and graphs for Postgres (optional)

 Expanding on the metrics exposed by the [synapse exporter and the node exporter](configuring-playbook-prometheus-grafana.md), the playbook enables the [postgres exporter](https://github.com/prometheus-community/postgres_exporter) that exposes more detailed information about what's happening on your postgres database.

 You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):


 ```yaml
 matrix_prometheus_postgres_exporter_enabled: true
 ```

 ## What does it do?

 Name | Description
 -----|----------
 `matrix_prometheus_postgres_exporter_enabled`|Enable the postgres prometheus exporter. This sets up the docker container, connects it to the database and adds a 'job' to the prometheus config which tells prometheus about this new exporter. The default is 'false'
 `matrix_prometheus_postgres_exporter_database_username`| The 'username' for the user that the exporter uses to connect to the database. The default is 'matrix_prometheus_postgres_exporter'
 `matrix_prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
 `matrix_prometheus_postgres_exporter_metrics_proxying_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)


 ## More information

 - [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)

--- a/docs/configuring-playbook-rest-auth.md
+++ b/docs/configuring-playbook-rest-auth.md
@@ -1,24 +0,0 @@
 # Setting up the REST authentication password provider module (optional, advanced)

 The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) for you.

 See that project's documentation 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:

 ```yaml
 matrix_synapse_ext_password_provider_rest_auth_enabled: true
 matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-ma1sd:8090"
 matrix_synapse_ext_password_provider_rest_auth_registration_enforce_lowercase: false
 matrix_synapse_ext_password_provider_rest_auth_registration_profile_name_autofill: true
 matrix_synapse_ext_password_provider_rest_auth_login_profile_name_autofill: false
 ```


 ## 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:

 ```yaml
 matrix_synapse_password_config_localdb_enabled: false
 ```
--- a/docs/configuring-playbook-riot-web.md
+++ b/docs/configuring-playbook-riot-web.md
@@ -1,39 +0,0 @@
 # Configuring Riot-web (optional)

 By default, this playbook **used to install** the [Riot-web](https://github.com/vector-im/riot-web) Matrix client web application.

 Riot has since been [renamed to Element](https://element.io/blog/welcome-to-element/).

 - to learn more about Element and its configuration, see our dedicated [Configuring Element](configuring-playbook-client-element.md) documentation page
 - to learn how to migrate from Riot to Element, see [Migrating to Element](#migrating-to-element) below


 ## Migrating to Element

 ### Migrating your custom settings

 If you have custom `matrix_riot_web_` variables in your `inventory/host_vars/matrix.DOMAIN/vars.yml` file, you'll need to rename them (`matrix_riot_web_` -> `matrix_client_element_`).

 Some other playbook variables (but not all) with `riot` in their name are also renamed. The playbook checks and warns if you are using the old name for some commonly used ones.


 ### Domain migration

 We used to set up Riot at the `riot.DOMAIN` domain. The playbook now sets up Element at `element.DOMAIN` by default.

 There are a few options for handling this:

 - (**avoiding changes** - using the old `riot.DOMAIN` domain and avoiding DNS changes) -- to keep using `riot.DOMAIN` instead of `element.DOMAIN`, override the domain at which the playbook serves Element: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"`

 - (**embracing changes** - using only `element.DOMAIN`) - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.DOMAIN` in this case. If so, you may also wish to remove old SSL certificates (`rm -rf /matrix/ssl/config/live/riot.DOMAIN`) and renewal configuration (`rm -f /matrix/ssl/config/renewal/riot.DOMAIN.conf`), so that `certbot` would stop trying to renew them.

 - (**embracing changes and transitioning smoothly** - using both `element.DOMAIN` and `riot.DOMAIN`) - to serve Element at the new domain (`element.DOMAIN`) and to also have `riot.DOMAIN` redirect there - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)) and enable Riot to Element redirection (`matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`).


 ### Re-running the playbook

 As always, after making the necessary DNS and configuration adjustments, re-run the playbook to apply the changes:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
--- a/docs/configuring-playbook-s3-goofys.md
+++ b/docs/configuring-playbook-s3-goofys.md
@@ -1,137 +0,0 @@
 # Storing Matrix media files on Amazon S3 with Goofys (optional)

 If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
 you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.

 Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md).

 Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.

 If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.


 ## Usage

 After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure Goofys in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):

 ```yaml
 matrix_s3_media_store_enabled: true
 matrix_s3_media_store_bucket_name: "your-bucket-name"
 matrix_s3_media_store_aws_access_key: "access-key-goes-here"
 matrix_s3_media_store_aws_secret_key: "secret-key-goes-here"
 matrix_s3_media_store_region: "eu-central-1"
 ```

 You can use any S3-compatible object store by **additionally** configuring these variables:

 ```yaml
 matrix_s3_media_store_custom_endpoint_enabled: true
 matrix_s3_media_store_custom_endpoint: "https://your-custom-endpoint"
 ```

 If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.


 ## Migrating from local filesystem storage to S3

 It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before migrating your local media store to an S3-backed one.

 Follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:

 - [Storing Matrix media files on Amazon S3 with Goofys (optional)](#storing-matrix-media-files-on-amazon-s3-with-goofys-optional)
 	- [Usage](#usage)
 	- [Migrating from local filesystem storage to S3](#migrating-from-local-filesystem-storage-to-s3)
 		- [Migrating to any S3-compatible storage (universal, but likely slow)](#migrating-to-any-s3-compatible-storage-universal-but-likely-slow)
 		- [Migrating to Backblaze B2](#migrating-to-backblaze-b2)

 ### Migrating to any S3-compatible storage (universal, but likely slow)

 It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.

 1. Proceed with the steps below without stopping Matrix services

 2. Start by adding the base S3 configuration in your `vars.yml` file (seen above, may be different depending on the S3 provider of your choice)

 3. In addition to the base configuration you see above, add this to your `vars.yml` file:

 ```yaml
 matrix_s3_media_store_path: /matrix/s3-media-store
 ```

 This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.

 5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`

 6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):

 ```sh
 sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
 ```

 You may need to install `rsync` manually.

 7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)

 8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`

 9. Sync the files again by re-running the `rsync` command you see in step #6

 10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`

 11. Get the old media store out of the way by running this command on the server:

 ```sh
 mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
 ```

 12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)

 13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`

 14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.

 15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`


 ### Migrating to Backblaze B2

 It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.

 1. While all Matrix services are running, run the following command on the server:

 (you need to adjust the 3 `--env` line below with your own data)

 ```sh
 docker run -it --rm -w /work \
 --env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
 --env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
 --env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
 --mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
 --entrypoint=/bin/sh \
 docker.io/tianon/backblaze-b2:3.6.0 \
 -c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET && b2 sync /work b2://$B2_BUCKET_NAME --skipNewer'
 ```

 This is some initial file sync, which may take a very long time.

 2. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)

 3. Run the command from step #1 again.

 Doing this will sync any new files that may have been created locally in the meantime.

 Now that Matrix services aren't running, we're sure to get Backblaze B2 and your local media store fully in sync.

 4. Get the old media store out of the way by running this command on the server:

 ```sh
 mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
 ```

 5. Put the [Backblaze B2 settings seen above](#backblaze-b2) in your `vars.yml` file

 6. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`

 7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.

 8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
--- a/docs/configuring-playbook-s3.md
+++ b/docs/configuring-playbook-s3.md
@@ -1,107 +0,0 @@
 # Storing Synapse media files on Amazon S3 or another compatible Object Storage (optional)

 By default, this playbook configures your server to store Synapse's content repository (`media_store`) files on the local filesystem.
 If that's alright, you can skip this.

 As an alternative to storing media files on the local filesystem, you can store them on [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object store.

 First, [choose an Object Storage provider](#choosing-an-object-storage-provider).

 Then, [create the S3 bucket](#bucket-creation-and-security-configuration).

 Finally, [set up S3 storage for Synapse](#setting-up) (with [Goofys](configuring-playbook-s3-goofys.md) or [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md)).


 ## Choosing an Object Storage provider

 You can create [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object store like [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html), [Wasabi](https://wasabi.com), [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces), etc.

 Amazon S3 and Backblaze S3 are pay-as-you with no minimum charges for storing too little data.

 All these providers have different prices, with Backblaze B2 appearing to be the cheapest.

 Wasabi has a minimum charge of 1TB if you're storing less than 1TB, which becomes expensive if you need to store less data than that.

 Digital Ocean Spaces has a minimum charge of 250GB ($5/month as of 2022-10), which is also expensive if you're storing less data than that.

 Important aspects of choosing the right provider are:

 - a provider by a company you like and trust (or dislike less than the others)
 - a provider which has a data region close to your Matrix server (if it's farther away, high latency may cause slowdowns)
 - a provider which is OK pricewise
 - a provider with free or cheap egress (if you need to get the data out often, for some reason) - likely not too important for the common use-case


 ## Bucket creation and Security Configuration

 Now that you've [chosen an Object Storage provider](#choosing-an-object-storage-provider), you need to create a storage bucket.

 How you do this varies from provider to provider, with Amazon S3 being the most complicated due to its vast number of services and complicated security policies.

 Below, we provider some guides for common providers. If you don't see yours, look at the others for inspiration or read some guides online about how to create a bucket. Feel free to contribute to this documentation with an update!

 ## Amazon S3

 You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example IAM security policy:

 ```json
 {
 	"Version": "2012-10-17",
 	"Statement": [
 		{
 			"Sid": "Stmt1400105486000",
 			"Effect": "Allow",
 			"Action": [
 				"s3:*"
 			],
 			"Resource": [
 				"arn:aws:s3:::your-bucket-name",
 				"arn:aws:s3:::your-bucket-name/*"
 			]
 		}
 	]
 }
 ```

 **NOTE**: This policy needs to be attached to an IAM user created from the **Security Credentials** menu. This is not a **Bucket Policy**.


 ## Backblaze B2

 To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) you first need to sign up.

 You [can't easily change which region (US, Europe) your Backblaze account stores files in](https://old.reddit.com/r/backblaze/comments/hi1v90/make_the_choice_for_the_b2_data_center_region/), so make sure to carefully choose the region when signing up (hint: it's a hard to see dropdown below the username/password fields in the signup form).

 After logging in to Backblaze:

 - create a new **private** bucket through its user interface (you can call it something like `matrix-DOMAIN-media-store`)
 - note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`).
 - adjust its Lifecycle Rules to: Keep only the last version of the file
 - go to [App Keys](https://secure.backblaze.com/app_keys.htm) and use the **Add a New Application Key** to create a new one
  - restrict it to the previously created bucket (e.g. `matrix-DOMAIN-media-store`)
  - give it *Read & Write* access

 The `keyID` value is your **Access Key** and `applicationKey` is your **Secret Key**.

 For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) you will need:

 - **Endpoint URL** - this is the  **Endpoint** value you saw above, but prefixed with `https://`

 - **Region** - use the value you see in the Endpoint (e.g. `us-west-002`)

 - **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.


 ## Other providers

 For other S3-compatible providers, you may not need to configure security policies, etc. (just like for [Backblaze B2](#backblaze-b2)).

 You most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner.


 ## Setting up

 To set up Synapse to store files in S3, follow the instructions for the method of your choice:

 - using [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) (recommended)
 - using [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md)
--- a/docs/configuring-playbook-shared-secret-auth.md
+++ b/docs/configuring-playbook-shared-secret-auth.md
@@ -1,23 +0,0 @@
 # Setting up the Shared Secret Auth password provider module (optional, advanced)

 The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you.

 See that project's documentation 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 (`inventory/host_vars/matrix.<your-domain>/vars.yml`) like this:

 ```yaml
 matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
 matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE
 ```

 You can generate a strong shared secret with a command like this: `pwgen -s 64 1`


 ## 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:

 ```yaml
 matrix_synapse_password_config_localdb_enabled: false
 ```
--- a/docs/configuring-playbook-ssl-certificates.md
+++ b/docs/configuring-playbook-ssl-certificates.md
@@ -1,112 +0,0 @@
 # Adjusting SSL certificate retrieval (optional, advanced)

 By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (`matrix.<your-domain>` and possibly `element.<your-domain>`)

 Those certificates are used when configuring the nginx reverse proxy installed by this playbook.
 They can also be used for configuring [your own webserver](configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook.

 If you need to retrieve certificates for other domains (e.g. your base domain) or more control over certificate retrieval, read below.

 Things discussed in this document:

 - [Using self-signed SSL certificates](#using-self-signed-ssl-certificates), if you can't use Let's Encrypt or just need a test setup

 - [Using your own SSL certificates](#using-your-own-ssl-certificates), if you don't want to or can't use Let's Encrypt certificates, but are still interested in using the integrated nginx reverse proxy server

 - [Not bothering with SSL certificates](#not-bothering-with-ssl-certificates), if you're using [your own webserver](configuring-playbook-own-webserver.md) and would rather this playbook leaves SSL certificate management to you

 - [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains), if you'd like to host additional domains on the Matrix server and would like the playbook to help you obtain and renew certificates for those domains automatically


 ## Using self-signed SSL certificates

 For private deployments (not publicly accessible from the internet), you may not be able to use Let's Encrypt certificates.

 If self-signed certificates are alright with you, you can ask the playbook to generate such for you with the following configuration:

 ```yaml
 matrix_ssl_retrieval_method: self-signed
 ```

 If you get a `Cannot reach homeserver` error in Element, you will have to visit `https://matrix.<your-domain>` in your browser and agree to the certificate exception before you can login.


 ## Using your own SSL certificates

 If you'd like to manage SSL certificates by yourself and have the playbook use your certificate files, you can use the following configuration:

 ```yaml
 matrix_ssl_retrieval_method: manually-managed
 ```

 With such a configuration, the playbook would expect you to drop the SSL certificate files in the directory specified by `matrix_ssl_config_dir_path` (`/matrix/ssl/config` by default) obeying the following hierarchy:

 - `<matrix_ssl_config_dir_path>/live/<domain>/fullchain.pem`
 - `<matrix_ssl_config_dir_path>/live/<domain>/privkey.pem`
 - `<matrix_ssl_config_dir_path>/live/<domain>/chain.pem`

 where `<domain>` refers to the domains that you need (usually `matrix.<your-domain>` and `element.<your-domain>`).


 ## Not bothering with SSL certificates

 If you're [using an external web server](configuring-playbook-own-webserver.md) which is not nginx, or you would otherwise want to manage its certificates without this playbook getting in the way, you can completely disable SSL certificate management with the following configuration:

 ```yaml
 matrix_ssl_retrieval_method: none
 ```

 With such a configuration, no certificates will be retrieved at all. You're free to manage them however you want.


 ## Obtaining SSL certificates for additional domains

 The playbook tries to be smart about the certificates it will obtain for you.

 By default, it obtains certificates for:
 - `matrix.<your-domain>` (`matrix_server_fqn_matrix`)
 - possibly for `element.<your-domain>`, unless you have disabled the [Element client component](configuring-playbook-client-element.md) using `matrix_client_element_enabled: false`
 - possibly for `riot.<your-domain>`, if you have explicitly enabled Riot to Element redirection (for background compatibility) using `matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`
 - possibly for `hydrogen.<your-domain>`, if you have explicitly [set up Hydrogen client](configuring-playbook-client-hydrogen.md).
 - possibly for `cinny.<your-domain>`, if you have explicitly [set up Cinny client](configuring-playbook-client-cinny.md).
 - possibly for `dimension.<your-domain>`, if you have explicitly [set up Dimension](configuring-playbook-dimension.md).
 - possibly for `goneb.<your-domain>`, if you have explicitly [set up Go-NEB bot](configuring-playbook-bot-go-neb.md).
 - possibly for `jitsi.<your-domain>`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md).
 - possibly for `stats.<your-domain>`, if you have explicitly [set up Grafana](configuring-playbook-prometheus-grafana.md).
 - possibly for `sygnal.<your-domain>`, if you have explicitly [set up Sygnal](configuring-playbook-sygnal.md).
 - possibly for `ntfy.<your-domain>`, if you have explicitly [set up ntfy](configuring-playbook-ntfy.md).
 - possibly for your base domain (`<your-domain>`), if you have explicitly configured [Serving the base domain](configuring-playbook-base-domain-serving.md)

 If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.
 To do that, simply define your own custom configuration like this:

 ```yaml
 # In this example, we retrieve 2 extra certificates,
 # one for the base domain (in the `matrix_domain` variable) and one for a hardcoded domain.
 # Adding any other additional domains (hosted on the same machine) is possible.
 matrix_ssl_additional_domains_to_obtain_certificates_for:
  - '{{ matrix_domain }}'
  - 'another.domain.example.com'
 ```

 After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should:

 - make sure the web server occupying port 80 is stopped. If you are using matrix-nginx-proxy server (which is the default for this playbook), you need to stop it temporarily by running `systemctl stop matrix-nginx-proxy` on the server.

 - re-run the SSL part of the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-ssl,start`

 The certificate files would be made available in `/matrix/ssl/config/live/<your-other-domain>/...`.

 For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal.

 See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-domain.conf`
 Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.


 ## Specify the SSL private key algorithm

 If you'd like to [specify the private key type](https://eff-certbot.readthedocs.io/en/stable/using.html#using-ecdsa-keys) used with Let's Encrypt, define your own custom configuration like this:

 ```yaml
 matrix_ssl_lets_encrypt_key_type: ecdsa
 ```
--- a/docs/configuring-playbook-sygnal.md
+++ b/docs/configuring-playbook-sygnal.md
@@ -1,71 +0,0 @@
 # Setting up Sygnal (optional)

 The playbook can install and configure the [Sygnal](https://github.com/matrix-org/sygnal) push gateway for you.

 See the project's [documentation](https://github.com/matrix-org/sygnal) to learn what it does and why it might be useful to you.

 **Note**: most people don't need to install their own gateway. As Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) documentation says:

 > It is not feasible to allow end-users to configure their own Sygnal instance, because the Sygnal instance needs the appropriate FCM or APNs secrets that belong to the application.

 This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves.


 ## Adjusting the playbook configuration

 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):

 ```yaml
 matrix_sygnal_enabled: true

 # You need at least 1 app defined.
 # The configuration below is incomplete. Read more below.
 matrix_sygnal_apps:
  com.example.myapp.ios:
    type: apns
    keyfile: /data/my_key.p8
    # .. more configuration ..
  com.example.myapp.android:
    type: gcm
    api_key: your_api_key_for_gcm
    # .. more configuration ..

 matrix_aux_file_definitions:
  - dest: "{{ matrix_sygnal_data_path }}/my_key.p8"
    content: |
      some
      content
      here
    mode: '0600'
    owner: "{{ matrix_user_username }}"
    group: "{{ matrix_user_groupname }}"
 ```

 For a more complete example of available fields and values they can take, see `roles/matrix-sygnal/templates/sygnal.yaml.j2` (or the [upstream `sygnal.yaml.sample` configuration file](https://github.com/matrix-org/sygnal/blob/master/sygnal.yaml.sample)).

 Configuring [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/) is easier, as it only requires that you provide some config values.

 To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Notification Service), you'd need to provide one or more certificate files.
 To do that, the above example configuration:

 - makes use of the `matrix-aux` role (and its `matrix_aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See `roles/matrix-aux/defaults/main.yml` for usage examples. It also makes sure the files are owned by `matrix:matrix`, so that Sygnal can read them. Of course, you can also install these files manually yourself, if you'd rather not use `matrix-aux`.

 - references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container)


 ## Installing

 Don't forget to add `sygnal.<your-domain>` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## Usage

 To make use of your Sygnal installation, you'd need to build your own Matrix client application, which uses the same API keys (for [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/)) and certificates (for [APNS](https://developer.apple.com/notifications/)) and is also pointed to `https://sygnal.DOMAIN` as the configured push server.

 Refer to Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) document.
--- a/docs/configuring-playbook-synapse-admin.md
+++ b/docs/configuring-playbook-synapse-admin.md
@@ -1,76 +0,0 @@
 # Setting up Synapse Admin (optional)

 The playbook can install and configure [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) for you.

 It's a web UI tool you can use to **administrate users and rooms on your Matrix server**.

 See the project's [documentation](https://github.com/Awesome-Technologies/synapse-admin) 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:

 ```yaml
 matrix_synapse_admin_enabled: true
 ```

 **Note**: Synapse Admin requires Synapse's [Admin APIs](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, we **automatically** exposes them publicly for you (equivalent to `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true`).


 ## Installing

 After configuring the playbook, run the [installation](installing.md) command again:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```


 ## Usage

 After installation, Synapse Admin will be accessible at: `https://matrix.DOMAIN/synapse-admin/`

 To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server.

 The Homeserver URL to use on Synapse Admin's login page is: `https://matrix.DOMAIN`

 ### Sample configuration for running behind Traefik 2.0

 Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.

 This an extension to Traefik config sample in [own-webserver-documentation](./configuring-playbook-own-webserver.md).

 ```yaml
 # Don't bind any HTTP or federation port to the host
 # (Traefik will proxy directly into the containers)
 matrix_synapse_admin_container_http_host_bind_port: ""

 matrix_synapse_admin_container_extra_arguments:
    # May be unnecessary depending on Traefik config, but can't hurt
    - '--label "traefik.enable=true"'

    # The Synapse Admin container will only receive traffic from this subdomain and path
    - '--label "traefik.http.routers.matrix-synapse-admin.rule=(Host(`{{ matrix_server_fqn_matrix }}`) && Path(`{{matrix_synapse_admin_public_endpoint}}`))"'

    # (Define your entrypoint)
    - '--label "traefik.http.routers.matrix-synapse-admin.entrypoints=web-secure"'

    # (The 'default' certificate resolver must be defined in Traefik config)
    - '--label "traefik.http.routers.matrix-synapse-admin.tls.certResolver=default"'

    # The Synapse Admin container uses port 80 by default
    - '--label "traefik.http.services.matrix-synapse-admin.loadbalancer.server.port=80"'
 ```

 ### Sample configuration for running behind Caddy v2

 Below is a sample configuration for using this playbook with a [Caddy](https://caddyserver.com/v2) 2.0 reverse proxy (non-default configuration where `matrix-nginx-proxy` is disabled - `matrix_nginx_proxy_enabled: false`).

 ```caddy
 # This is a basic configuration that will function the same as the default nginx proxy - exposing the synapse-admin panel to matrix.YOURSERVER.com/synapse-admin/
  handle_path /synapse-admin* {
        reverse_proxy localhost:8766  {
        }
  }
 ```
--- a/docs/configuring-playbook-synapse-s3-storage-provider.md
+++ b/docs/configuring-playbook-synapse-s3-storage-provider.md
@@ -1,126 +0,0 @@
 # Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider (optional)

 If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
 you can use the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) media provider module for Synapse.

 **`synapse-s3-storage-provider` support is very new and still relatively untested. Using it may cause data loss.**

 An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).


 ## How it works?

 Summarized writings here are inspired by [this article](https://quentin.dufour.io/blog/2021-09-14/matrix-synapse-s3-storage/).

 The way media storage providers in Synapse work has some caveats:

 - Synapse still continues to use locally-stored files (for creating thumbnails, serving files, etc)
 - the media storage provider is just an extra storage mechanism (in addition to the local filesystem)
 - all files are stored locally at first, and then copied to the media storage provider (either synchronously or asynchronously)
 - if a file is not available on the local filesystem, it's pulled from a media storage provider

 You may be thinking **if all files are stored locally as well, what's the point**?

 You can run some scripts to delete the local files once in a while (which we do automatically by default - see [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem)), thus freeing up local disk space. If these files are needed in the future (for serving them to users, etc.), Synapse will pull them from the media storage provider on demand.

 While you will need some local disk space around, it's only to accommodate usage, etc., and won't grow as large as your S3 store.


 ## Installing

 After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure Goofys in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):

 ```yaml
 matrix_synapse_ext_synapse_s3_storage_provider_enabled: true
 matrix_synapse_ext_synapse_s3_storage_provider_config_bucket: your-bucket-name
 matrix_synapse_ext_synapse_s3_storage_provider_config_region_name: some-region-name # e.g. eu-central-1
 matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url: https://.. # delete this whole line for Amazon S3
 matrix_synapse_ext_synapse_s3_storage_provider_config_access_key_id: access-key-goes-here
 matrix_synapse_ext_synapse_s3_storage_provider_config_secret_access_key: secret-key-goes-here
 matrix_synapse_ext_synapse_s3_storage_provider_config_storage_class: STANDARD # or STANDARD_IA, etc.

 # For additional advanced settings, take a look at `roles/matrix-synapse/defaults/main.yml`
 ```

 If you have existing files in Synapse's media repository (`/matrix/synapse/media-store/..`):

 - new files will start being stored both locally and on the S3 store
 - the existing files will remain on the local filesystem only until [migrating them to the S3 store](#migrating-your-existing-media-files-to-the-s3-store)
 - at some point (and periodically in the future), you can delete local files which have been uploaded to the S3 store already

 Regardless of whether you need to [Migrate your existing files to the S3 store](#migrating-your-existing-media-files-to-the-s3-store) or not, make sure you've familiarized yourself with [How it works?](#how-it-works) above and [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem) below.


 ## Migrating your existing media files to the S3 store

 Migrating your existing data can happen in multiple ways:

 - [using the `s3_media_upload` script from `synapse-s3-storage-provider`](#using-the-s3_media_upload-script-from-synapse-s3-storage-provider) (very slow when dealing with lots of data)
 - [using another tool in combination with `s3_media_upload`](#using-another-tool-in-combination-with-s3_media_upload) (quicker when dealing with lots of data)

 ### Using the `s3_media_upload` script from `synapse-s3-storage-provider`

 Instead of using `s3_media_upload` directly, which is very slow and painful for an initial data migration, we recommend [using another tool in combination with `s3_media_upload`](#using-another-tool-in-combination-with-s3_media_upload).

 To copy your existing files, SSH into the server and run `/usr/local/bin/matrix-synapse-s3-storage-provider-shell`.

 This launches a Synapse container, which has access to the local media store, Postgres database, S3 store and has some convenient environment variables configured for you to use (`MEDIA_PATH`, `BUCKET`, `ENDPOINT`, `UPDATE_DB_DAYS`, etc).

 Then use the following commands (`$` values come from environment variables - they're **not placeholders** that you need to substitute):

 - `s3_media_upload update-db $UPDATE_DB_DURATION` - create a local SQLite database (`cache.db`) with a list of media repository files (from the `synapse` Postgres database) eligible for operating on
  - `$UPDATE_DB_DURATION` is influenced by the `matrix_synapse_ext_synapse_s3_storage_provider_update_db_day_count` variable (defaults to `0`)
  - `$UPDATE_DB_DURATION` defaults to `0d` (0 days), which means **include files which haven't been accessed for more than 0 days** (that is, **all files will be included**).
 - `s3_media_upload check-deleted $MEDIA_PATH` - check whether files in the local cache still exist in the local media repository directory
 - `s3_media_upload upload $MEDIA_PATH $BUCKET --delete --storage-class $STORAGE_CLASS --endpoint-url $ENDPOINT` - uploads locally-stored files to S3 and deletes them from the local media repository directory

 The `s3_media_upload upload` command may take a lot of time to complete.

 Instead of running the above commands manually in the shell, you can also run the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` script which will run the same commands automatically. We demonstrate how to do it manually, because:

 - it's what the upstream project demonstrates and it teaches you how to use the `s3_media_upload` tool
 - allows you to check and verify the output of each command, to catch mistakes
 - includes progress bars and detailed output for each command
 - allows you to easily interrupt slow-running commands, etc. (the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` starts a container without interactive TTY support, so `Ctrl+C` may not work and you and require killing via `docker kill ..`)

 ### Using another tool in combination with `s3_media_upload`

 To migrate your existing local data to S3, we recommend to:

 - **first** use another tool ([`aws s3`](#copying-data-to-amazon-s3) or [`b2 sync`](#copying-data-to-backblaze-b2), etc.) to copy the local files to the S3 bucket

 - **only then** [use the `s3_media_upload` tool to finish the migration](#using-the-s3_media_upload-script-from-synapse-s3-storage-provider) (this checks to ensure all files are uploaded and then deletes the local files)

 #### Copying data to Amazon S3

 Generally, you need to use the `aws s3` tool.

 This documentation section could use an improvement. Ideally, we'd come up with a guide like the one used in [Copying data to Backblaze B2](#copying-data-to-backblaze-b2) - running `aws s3` in a container, etc.

 #### Copying data to Backblaze B2

 To copy to Backblaze B2, start a container like this:

 ```sh
 docker run -it --rm \
 -w /work \
 --env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
 --env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
 --env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
 --mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
 --entrypoint=/bin/sh \
 tianon/backblaze-b2:3.6.0 \
 -c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET && b2 sync /work b2://$B2_BUCKET_NAME --skipNewer'
 ```

 ## Periodically cleaning up the local filesystem

 As described in [How it works?](#how-it-works) above, when new media is uploaded to the Synapse homeserver, it's first stored locally and then also stored on the remote S3 storage.

 By default, we periodically ensure that all local files are uploaded to S3 and are then removed from the local filesystem. This is done automatically using:

 - the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` script
 - .. invoked via the `matrix-synapse-s3-storage-provider-migrate.service` service
 - .. triggered by the `matrix-synapse-s3-storage-provider-migrate.timer` timer, every day at 05:00

 So.. you don't need to perform any maintenance yourself.
--- a/docs/configuring-playbook-synapse-simple-antispam.md
+++ b/docs/configuring-playbook-synapse-simple-antispam.md
@@ -1,16 +0,0 @@
 # Setting up Synapse Simple Antispam (optional, advanced)

 The playbook can install and configure [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) for you.

 See that project's documentation to learn what it does and why it might be useful to you.
 In short, it lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).

 If you decide that you'd like to let this playbook install it for you, you need some configuration like this:

 ```yaml
 matrix_synapse_ext_spam_checker_synapse_simple_antispam_enabled: true

 matrix_synapse_ext_spam_checker_synapse_simple_antispam_config_blocked_homeservers:
 - example.com
 - another.com
 ```
--- a/docs/configuring-playbook-synapse.md
+++ b/docs/configuring-playbook-synapse.md
@@ -1,76 +0,0 @@
 # Configuring Synapse (optional)

 By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, so that it works for the general case.
 If that's enough for you, you can skip this document.

 The playbook provides lots of customization variables you could use to change Synapse's settings.

 Their defaults are defined in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml) and they ultimately end up in the generated `/matrix/synapse/config/homeserver.yaml` file (on the server). This file is generated from the [`roles/matrix-synapse/templates/synapse/homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.yaml.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 a Synapse 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 Synapse's various settings that rarely get used.

 - or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).

 - or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).


 ## Load balancing with workers

 To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/matrix-org/synapse/blob/master/docs/workers.md).

 To enable Synapse worker support, update your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:

 ```yaml
 matrix_synapse_workers_enabled: true
 ```

 We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration):
 - `little-federation-helper` - a very minimal worker configuration to improve federation performance
 - `one-of-each` - one worker of each supported type

 If you'd like more customization power, you can start with one of the presets and tweak various `matrix_synapse_workers_*_count` variables manually.

 If you increase worker counts too much, you may need to increase the maximum number of Postgres connections too (example):

 ```yaml
 matrix_postgres_process_extra_arguments: [
  "-c 'max_connections=200'"
 ]
 ```

 **NOTE**: Disabling `matrix-nginx-proxy` (`matrix_nginx_proxy_enabled: false`) (that is, [using your own other webserver](configuring-playbook-own-webserver.md) when running a Synapse worker setup is likely to cause various troubles (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090)).

 In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/matrix-org/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.


 ## Synapse Admin

 Certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace, if you install [Synapse Admin](configuring-playbook-synapse-admin.md).


 ## Synapse + OpenID Connect for Single-Sign-On

 If you'd like to use OpenID Connect authentication with Synapse, you'll need some additional reverse-proxy configuration (see [our nginx reverse-proxy doc page](configuring-playbook-nginx.md#synapse-openid-connect-for-single-sign-on)).

 In case you encounter errors regarding the parsing of the variables, you can try to add `{% raw %}` and `{% endraw %}` blocks around them. For example ;

 ```
 - idp_id: keycloak
        idp_name: "Keycloak"
        issuer: "https://url.ix/auth/realms/x"
        client_id: "matrix"
        client_secret: "{{ vault_synapse_keycloak }}"
        scopes: ["openid", "profile"]
        authorization_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/auth"
        token_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/token"
        userinfo_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/userinfo"
        user_mapping_provider:
          config:
            display_name_template: "{% raw %}{{ user.given_name }}{% endraw %} {% raw %}{{ user.family_name }}{% endraw %}"
            email_template: "{% raw %}{{ user.email }}{% endraw %}"
 ```

--- a/docs/configuring-playbook-telemetry.md
+++ b/docs/configuring-playbook-telemetry.md
@@ -1,26 +0,0 @@
 # Enabling Telemetry for your Matrix server (optional)

 By default, this playbook configures your Matrix homeserver to not send any telemetry data anywhere.

 The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting
 usage statistics from your homeserver. Enabling usage statistics helps track the
 growth of the Matrix community, and helps to make Matrix a success.


 ## Enabling Telemetry

 If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):

 ```yaml
 matrix_synapse_report_stats: true
 ```


 ## Usage statistics being submitted

 When enabled, Synapse will regularly upload a few dozen statistics about your server.
 This data includes your homeserver's domain, the total number of users, the number of active
 users, the total number of rooms, and the number of messages sent per day on your homeserver.

 See [Synapse's documentation](https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics)
 for the full list of statistics that are reported.
--- a/docs/configuring-playbook-turn.md
+++ b/docs/configuring-playbook-turn.md
@@ -1,42 +0,0 @@
 # TURN server

 The playbook installs a [Coturn](https://github.com/coturn/coturn) TURN server by default, so that clients can make audio/video calls even from [NAT](https://en.wikipedia.org/wiki/Network_address_translation)-ed networks.

 By default, the Synapse chat server is configured, so that it points to the Coturn TURN server installed by the playbook.


 ## Disabling Coturn

 If, for some reason, you'd like to prevent the playbook from installing Coturn, you can use the following configuration:

 ```yaml
 matrix_coturn_enabled: false
 ```

 In that case, Synapse would not point to any Coturn servers and audio/video call functionality may fail.


 ## Using your own external Coturn server

 If you'd like to use another TURN server (be it Coturn or some other one), you can configure the playbook like this:

 ```yaml
 # Disable integrated Coturn server
 matrix_coturn_enabled: false

 # Point Synapse to your other Coturn server
 matrix_synapse_turn_uris:
 - turns:HOSTNAME_OR_IP?transport=udp
 - turns:HOSTNAME_OR_IP?transport=tcp
 - turn:HOSTNAME_OR_IP?transport=udp
 - turn:HOSTNAME_OR_IP?transport=tcp
 ```

 If you have or want to enable [Jitsi](configuring-playbook-jitsi.md), you might want to enable the TURN server there too.
 If you do not do it, Jitsi will fall back to an upstream service.

 ```yaml
 matrix_jitsi_web_stun_servers:
 - stun:HOSTNAME_OR_IP:PORT
 ```
 You can put multiple host/port combinations if you like.
--- a/docs/configuring-playbook.md
+++ b/docs/configuring-playbook.md
@@ -1,190 +0,0 @@
 # Configuring the Ansible playbook

 To configure the playbook, you need to have done the following things:

 - have a server where Matrix services will run
 - [configured your DNS records](configuring-dns.md)
 - [retrieved the playbook's source code](getting-the-playbook.md) to your computer

 You can then follow these steps inside the playbook directory:

 1. create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)

 1. copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)

 1. edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at the various `roles/ROLE_NAME_HERE/defaults/main.yml` files and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.

 1. copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)

 1. edit the inventory hosts file (`inventory/hosts`) to your liking

 1. (optional, advanced) to run Ansible against multiple servers with different `sudo` credentials, you can copy the sample inventory hosts yaml file for each of your hosts: (`cp examples/host.yml inventory/my_host1.yml` …) and use the [`ansible-all-hosts.sh`](../inventory/scripts/ansible-all-hosts.sh) script [in the installation step](installing.md).

 For a basic Matrix installation, that's all you need.
 For a more custom setup, see the [Other configuration options](#other-configuration-options) below.

 When you're done with all the configuration you'd like to do, continue with [Installing](installing.md).


 ## Other configuration options

 ### Additional useful services

 - [Setting up the Dimension Integration Manager](configuring-playbook-dimension.md) (optional, but recommended; after [installing](installing.md))

 - [Setting up the Jitsi video-conferencing platform](configuring-playbook-jitsi.md) (optional)

 - [Setting up Etherpad](configuring-playbook-etherpad.md) (optional)

 - [Setting up Dynamic DNS](configuring-playbook-dynamic-dns.md) (optional)

 - [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md) (optional)

 ### Core service adjustments

 - Homeserver configuration:
  - [Configuring Synapse](configuring-playbook-synapse.md), if you're going with the default/recommended homeserver implementation (optional)

  - [Configuring Conduit](configuring-playbook-conduit.md), if you've switched to the [Conduit](https://conduit.rs) homeserver implementation (optional)

 - [Configuring Element](configuring-playbook-client-element.md) (optional)

 - [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional)

 - [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) (optional)

 - [Adjusting SSL certificate retrieval](configuring-playbook-ssl-certificates.md) (optional, advanced)

 - [Serving your base domain using this playbook's nginx server](configuring-playbook-base-domain-serving.md) (optional)

 - [Configure Nginx](configuring-playbook-nginx.md) (optional, advanced)

 - [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced)

 - [Adjusting TURN server configuration](configuring-playbook-turn.md) (optional, advanced)


 ### Server connectivity

 - [Enabling Telemetry for your Matrix server](configuring-playbook-telemetry.md) (optional)

 - [Controlling Matrix federation](configuring-playbook-federation.md) (optional)

 - [Adjusting email-sending settings](configuring-playbook-email.md) (optional)

 - [Setting up Hydrogen](configuring-playbook-client-hydrogen.md) - a new lightweight matrix client with legacy and mobile browser support (optional)

 - [Setting up Cinny](configuring-playbook-client-cinny.md) - a web client focusing primarily on simple, elegant and secure interface (optional)


 ### Authentication and user-related

 - [Setting up an ma1sd Identity Server](configuring-playbook-ma1sd.md) (optional)

 - [Setting up Synapse Admin](configuring-playbook-synapse-admin.md) (optional)

 - [Setting up matrix-registration](configuring-playbook-matrix-registration.md) (optional)

 - [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional, advanced)

 - [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional, advanced)

 - [Setting up the LDAP password provider module](configuring-playbook-ldap-auth.md) (optional, advanced)

 - [Setting up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md) (optional, advanced)

 - [Setting up Synapse Simple Antispam](configuring-playbook-synapse-simple-antispam.md) (optional, advanced)

 - [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced)


 ### Bridging other networks

 - [Setting up Mautrix Discord bridging](configuring-playbook-bridge-mautrix-discord.md) (optional)

 - [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional)

 - [Setting up Mautrix Whatsapp bridging](configuring-playbook-bridge-mautrix-whatsapp.md) (optional)

 - [Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md) (optional)

 - [Setting up Mautrix Hangouts bridging](configuring-playbook-bridge-mautrix-hangouts.md) (optional)

 - [Setting up Mautrix Google Chat bridging](configuring-playbook-bridge-mautrix-googlechat.md) (optional)

 - [Setting up Mautrix Instagram bridging](configuring-playbook-bridge-mautrix-instagram.md) (optional)

 - [Setting up Mautrix Twitter bridging](configuring-playbook-bridge-mautrix-twitter.md) (optional)

 - [Setting up Mautrix Signal bridging](configuring-playbook-bridge-mautrix-signal.md) (optional)

 - [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional)

 - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional)

 - [Setting up Appservice Slack bridging](configuring-playbook-bridge-appservice-slack.md) (optional)

 - [Setting up Appservice Webhooks bridging](configuring-playbook-bridge-appservice-webhooks.md) (optional)

 - [Setting up Appservice Kakaotalk bridging](configuring-playbook-bridge-appservice-kakaotalk.md) (optional)

 - [Setting up Beeper LinkedIn bridging](configuring-playbook-bridge-beeper-linkedin.md) (optional)

 - [Setting up matrix-hookshot](configuring-playbook-bridge-hookshot.md) - a bridge between Matrix and multiple project management services, such as [GitHub](https://github.com), [GitLab](https://about.gitlab.com) and [JIRA](https://www.atlassian.com/software/jira). (optional)

 - ~~[Setting up MX Puppet Skype bridging](configuring-playbook-bridge-mx-puppet-skype.md)~~ (optional) - this component has been broken for a long time, so it has been removed from the playbook. Consider [Setting up Go Skype Bridge bridging](configuring-playbook-bridge-go-skype-bridge.md)

 - [Setting up MX Puppet Slack bridging](configuring-playbook-bridge-mx-puppet-slack.md) (optional)

 - [Setting up MX Puppet Instagram bridging](configuring-playbook-bridge-mx-puppet-instagram.md) (optional)

 - [Setting up MX Puppet Twitter bridging](configuring-playbook-bridge-mx-puppet-twitter.md) (optional)

 - [Setting up MX Puppet Discord bridging](configuring-playbook-bridge-mx-puppet-discord.md) (optional)

 - [Setting up MX Puppet GroupMe bridging](configuring-playbook-bridge-mx-puppet-groupme.md) (optional)

 - [Setting up MX Puppet Steam bridging](configuring-playbook-bridge-mx-puppet-steam.md) (optional)

 - [Setting up Go Skype Bridge bridging](configuring-playbook-bridge-go-skype-bridge.md) (optional)

 - [Setting up Email2Matrix](configuring-playbook-email2matrix.md) (optional)

 - [Setting up Postmoogle email bridging](configuring-playbook-bot-postmoogle.md) (optional)

 - [Setting up Matrix SMS bridging](configuring-playbook-bridge-matrix-bridge-sms.md) (optional)

 - [Setting up Heisenbridge bouncer-style IRC bridging](configuring-playbook-bridge-heisenbridge.md) (optional)


 ### Bots

 - [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) - a bot to remind you about stuff (optional)

 - [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) - a bot to create and manage registration tokens to invite users (optional)

 - [Setting up maubot](configuring-playbook-bot-maubot.md) - a plugin-based Matrix bot system (optional)

 - [Setting up honoroit](configuring-playbook-bot-honoroit.md) - a helpdesk bot (optional)

 - [Setting up Go-NEB](configuring-playbook-bot-go-neb.md) - an extensible multifunctional bot (optional)

 - [Setting up Mjolnir](configuring-playbook-bot-mjolnir.md) - a moderation tool/bot (optional)

 - [Setting up Buscarron](configuring-playbook-bot-buscarron.md) - a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room (optional)


 ### Backups

 - [Setting up borg backup](configuring-playbook-backup-borg.md) - a full Matrix server backup solution, including the Postgres database (optional)

 - [Setting up postgres backup](configuring-playbook-postgres-backup.md) - a Postgres-database backup solution (note: does not include other files) (optional)


 ### Other specialized services

 - [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional)

 - [Setting up the ntfy push notifications server](configuring-playbook-ntfy.md) (optional)

 - [Setting up a Cactus Comments server](configuring-playbook-cactus-comments.md) - a federated comment system built on Matrix (optional)
--- a/docs/configuring-well-known.md
+++ b/docs/configuring-well-known.md
@@ -1,201 +0,0 @@
 # Configuring Service Discovery via .well-known

 Service discovery is a way for the Matrix network to discover where a Matrix server is.

 There are 2 types of well-known service discovery that Matrix makes use of:

 - (important) **Federation Server discovery** (`/.well-known/matrix/server`) -- assists other servers in the Matrix network with finding your server. Without a proper configuration, your server will effectively not be part of the Matrix network. Learn more in [Introduction to Federation Server Discovery](#introduction-to-federation-server-discovery)

 - (not that important) **Client Server discovery** (`/.well-known/matrix/client`) -- assists programs that you use to connect to your server (e.g. Element), so that they can make it more convenient for you by automatically configuring the "Homeserver URL" and "Identity Server URL" addresses. Learn more in [Introduction to Client Server Discovery](#introduction-to-client-server-discovery)


 ## Introduction to Federation Server Discovery

 All services created by this playbook are meant to be installed on their own server (such as `matrix.<your-domain>`).

 As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), to use a Matrix user identifier like `@<username>:<your-domain>` while hosting services on a subdomain like `matrix.<your-domain>`, the Matrix network needs to be instructed of such delegation/redirection.

 Server delegation can be configured using DNS SRV records or by setting up a `/.well-known/matrix/server` file on the base domain (`<your-domain>`).

 Both methods have their place and will continue to do so. You only need to use just one of these delegation methods.
 For simplicity reasons, our setup advocates for the `/.well-known/matrix/server` method and guides you into using that.

 To learn how to set up `/.well-known/matrix/server`, read the Installing section below.


 ## Introduction to Client Server Discovery

 Client Server Service discovery lets various client programs which support it, to receive a full user id (e.g. `@username:example.com`) and determine where the Matrix server is automatically (e.g. `https://matrix.example.com`).

 This lets you (and your users) easily connect to your Matrix server without having to customize connection URLs. When using client programs that support it, you won't need to point them to `https://matrix.example.com` in Custom Server options manually anymore. The connection URL would be discovered automatically from your full username.

 As [per the Client-Server specification](https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery) Matrix does Client Server service discovery using a `/.well-known/matrix/client` file hosted on the base domain (e.g. `example.com`).

 However, this playbook installs your Matrix server on another domain (e.g. `matrix.example.com`) and not on the base domain (e.g. `example.com`), so it takes a little extra manual effort to set up the file.

 To learn how to set it up, read the Installing section below.


 ## (Optional) Introduction to Homeserver Admin Contact and Support page

 [MSC 1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929) specifies a way to add contact details of admins, as well as a link to a support page for users who are having issues with the service.

 This MSC did not get accepted yet, but we think it might already be useful to Homeserver admins who wish to provide this information to end-users.

 The two playbook variables that you could look for, if you're interested in being an early adopter, are: `matrix_homeserver_admin_contacts` and `matrix_homeserver_support_url`.

 Example snippet for `vars.yml`:
 ```
 # Enable generation of `/.well-known/matrix/support`.
 # This needs to be enabled explicitly for now, because MSC 1929 is not yet accepted.
 matrix_well_known_matrix_support_enabled: true

 # Homeserver admin contacts as per MSC 1929 https://github.com/matrix-org/matrix-spec-proposals/pull/1929
 matrix_homeserver_admin_contacts:
  - matrix_id: "@admin1:{{ matrix_domain }}"
    email_address: admin@domain.tld
    role: admin
  - matrix_id: "@admin2:{{ matrix_domain }}"
    email_address: admin2@domain.tld
    role: admin
  - email_address: security@domain.tld
    role: security

 matrix_homeserver_support_url: "https://example.domain.tld/support"
 ```

 To learn how to set up `/.well-known/matrix/support` for the base domain, read the Installing section below.


 ## Installing well-known files on the base domain's server

 To implement the two service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to run an HTTPS-capable webserver.

 If you don't have a server for your base domain at all, you can use the Matrix server for this.
 See [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up.
 If you decide to go this route, you don't need to read ahead in this document. When **Serving the base domain**, the playbook takes care to serve the appropriate well-known files automatically.

 If you're managing the base domain by yourself somehow, you'll need to set up serving of some `/.well-known/matrix/*` files from it via HTTPS.

 To make things easy for you to set up, this playbook generates and hosts 2 well-known files on the Matrix domain's server. The files are generated at `/matrix/static-files/.well-known/matrix/` and hosted at `https://matrix.example.com/.well-known/matrix/server` and `https://matrix.example.com/.well-known/matrix/client`, even though this is the wrong place to host them.

 You have 3 options when it comes to installing the files on the base domain's server:


 ### (Option 1): **Copying the files manually** to your base domain's server

 **Hint**: Option 2 and 3 (below) are generally a better way to do this. Make sure to go with them, if possible.

 All you need to do is:

 - copy `/.well-known/matrix/server` and `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`). You can find these files in the `/matrix/static-files/.well-known/matrix` directory on the Matrix server. They are also accessible on URLs like this: `https://matrix.example.com/.well-known/matrix/server` (same for `client`).

 - set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Element) may fail to work. Setting up headers for the `/.well-known/matrix/server` file is not necessary, as this file is only consumed by non-browsers, which don't care about CORS.

 This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server.
 It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known files and you may need to notice that and copy them over again.


 ### (Option 2): **Serving the base domain** from the Matrix server via the playbook

 If you don't need the base domain (e.g. `example.com`) for anything else (hosting a website, etc.), you can point it to the Matrix server's IP address and tell the playbook to configure it.

 This is the easiest way to set up well-known serving -- letting the playbook handle the whole base domain for you (including SSL certificates, etc.). However, if you need to use the base domain for other things (such as hosting some website, etc.), going with Option 1 or Option 3 might be more suitable.

 See [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up.


 ### (Option 3): **Setting up reverse-proxying** of the well-known files from the base domain's server to the Matrix server

 This option is less fragile and generally better.

 On the base domain's server (e.g. `example.com`), you can set up reverse-proxying, so that any access for the `/.well-known/matrix` location prefix is forwarded to the Matrix domain's server (e.g. `matrix.example.com`).

 With this method, you **don't need** to add special HTTP headers for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) reasons (like `Access-Control-Allow-Origin`), because your Matrix server (where requests ultimately go) will be configured by this playbook correctly.

 **For nginx**, it would be something like this:

 ```nginx
 # This is your HTTPS-enabled server for example.com.
 server {
 	server_name example.com;

 	location /.well-known/matrix {
 		proxy_pass https://matrix.example.com/.well-known/matrix;
 		proxy_set_header X-Forwarded-For $remote_addr;
 	}

 	# other configuration
 }
 ```

 **For Apache2**, it would be something like this:

 ```apache
 <VirtualHost *:443>
 	ServerName example.com

 	SSLProxyEngine on
 	ProxyPass /.well-known/matrix https://matrix.example.com/.well-known/matrix nocanon
 	ProxyPassReverse /.well-known/matrix https://matrix.example.com/.well-known/matrix nocanon

 	# other configuration
 </VirtualHost>
 ```

 **For Caddy 2**, it would be something like this:

 ```caddy
 example.com {
 	reverse_proxy /.well-known/matrix/* https://matrix.example.com {
 		header_up Host {upstream_hostport}
 	}
 }
 ```

 **For HAProxy**, it would be something like this:

 ```haproxy
 frontend www-https
 	# Select a Challenge for Matrix federation redirect
 	acl matrix-acl path_beg /.well-known/matrix/
 	# Use the challenge backend if the challenge is set
 	use_backend matrix-backend if matrix-acl
 backend matrix-backend
 	# Redirects the .well-known matrix to the matrix server for federation.
 	http-request set-header Host matrix.example.com
 	server matrix matrix.example.com:80
 	# Map url path as ProxyPass does
 	reqirep ^(GET|POST|HEAD)\ /.well-known/matrix/(.*) \1\ /\2
 	# Rewrite redirects as ProxyPassReverse does
 	acl response-is-redirect res.hdr(Location) -m found
 	rsprep ^Location:\ (http|https)://matrix.example.com\/(.*) Location:\ \1://matrix.example.com/.well-known/matrix/\2 if response-is-redirect
 ```

 **For Netlify**, it would be something like this:

 ```
 # In the _redirects file in the website's root
 /.well-known/matrix/* https://matrix.example.com/.well-known/matrix/:splat 200!
 ```

 **For AWS CloudFront**

   1. Add a custom origin with matrix.<your-domain> to your distribution
   1. Add two behaviors, one for `.well-known/matrix/client` and one for `.well-known/matrix/server` and point them to your new origin.

 Make sure to:

 - **replace `example.com`** in the server configuration with your actual domain name
 - and: to **do this for the HTTPS-enabled server block**, as that's where Matrix expects the file to be


 ## Confirming it works

 No matter which method you've used to set up the well-known files, if you've done it correctly you should be able to see a JSON file at these URLs:

 - `https://<domain>/.well-known/matrix/server`
 - `https://<domain>/.well-known/matrix/client`
 - `https://<domain>/.well-known/matrix/support`

 You can also check if everything is configured correctly, by [checking if services work](maintenance-checking-services.md).
--- a/docs/container-images.md
+++ b/docs/container-images.md
@@ -1,121 +0,0 @@
 # Container Images used by the playbook

 This page summarizes the container ([Docker](https://www.docker.com/)) images used by the playbook when setting up your server.

 We try to stick to official images (provided by their respective projects) as much as possible.


 ## Container images used by default

 These services are enabled and used by default, but you can turn them off, if you wish.

 - [matrixdotorg/synapse](https://hub.docker.com/r/matrixdotorg/synapse/) - the official [Synapse](https://github.com/matrix-org/synapse) Matrix homeserver (optional)

 - [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) - the [Coturn](https://github.com/coturn/coturn) STUN/TURN server (optional)

 - [vectorim/element-web](https://hub.docker.com/r/vectorim/element-web/) - the [Element](https://element.io/) web client (optional)

 - [postgres](https://hub.docker.com/_/postgres/) - the [Postgres](https://www.postgresql.org/) database server (optional)

 - [devture/exim-relay](https://hub.docker.com/r/devture/exim-relay/) - the [Exim](https://www.exim.org/) email server (optional)

 - [nginx](https://hub.docker.com/_/nginx/) - the [nginx](http://nginx.org/) web server (optional)

 - [certbot/certbot](https://hub.docker.com/r/certbot/certbot/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) (optional)


 ## Optional other container images we may use

 These services are not part of our default installation, but can be enabled by [configuring the playbook](configuring-playbook.md) (either before the initial installation or any time later):

 - [ma1uta/ma1sd](https://hub.docker.com/r/ma1uta/ma1sd/) - the [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server (optional)

 - [matrixconduit/matrix-conduit](https://hub.docker.com/r/matrixconduit/matrix-conduit) - the [Conduit](https://conduit.rs) Matrix homeserver (optional)

 - [matrixdotorg/dendrite-monolith](https://hub.docker.com/r/matrixdotorg/dendrite-monolith/) - the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver (optional)

 - [ewoutp/goofys](https://hub.docker.com/r/ewoutp/goofys/) - the [Goofys](https://github.com/kahing/goofys) Amazon [S3](https://aws.amazon.com/s3/) file-system-mounting program (optional)

 - [etherpad/etherpad](https://hub.docker.com/r/etherpad/etherpad/) - the [Etherpad](https://etherpad.org) realtime collaborative text editor that can be used in a Jitsi audio/video call or integrated as a widget into Matrix chat rooms via the Dimension integration manager (optional)

 - [devture/email2matrix](https://hub.docker.com/r/devture/email2matrix/) - the [Email2Matrix](https://github.com/devture/email2matrix) email server, which can relay email messages to Matrix rooms (optional)

 - [devture/matrix-corporal](https://hub.docker.com/r/devture/matrix-corporal/) - [Matrix Corporal](https://github.com/devture/matrix-corporal): reconciliator and gateway for a managed Matrix server (optional)

 - [zeratax/matrix-registration](https://hub.docker.com/r/devture/zeratax-matrix-registration/) - [matrix-registration](https://github.com/ZerataX/matrix-registration): a simple python application to have a token based matrix registration (optional)

 - [mautrix/telegram](https://mau.dev/mautrix/telegram/container_registry) - the [mautrix-telegram](https://github.com/mautrix/telegram) bridge to [Telegram](https://telegram.org/) (optional)

 - [mautrix/whatsapp](https://mau.dev/mautrix/whatsapp/container_registry) - the [mautrix-whatsapp](https://github.com/mautrix/whatsapp) bridge to [Whatsapp](https://www.whatsapp.com/) (optional)

 - [mautrix/facebook](https://mau.dev/mautrix/facebook/container_registry) - the [mautrix-facebook](https://github.com/mautrix/facebook) bridge to [Facebook](https://facebook.com/) (optional)

 - [mautrix/twitter](https://mau.dev/mautrix/twitter/container_registry) - the [mautrix-twitter](https://github.com/mautrix/twitter) bridge to [Twitter](https://twitter.com/) (optional)

 - [mautrix/hangouts](https://mau.dev/mautrix/hangouts/container_registry) - the [mautrix-hangouts](https://github.com/mautrix/hangouts) bridge to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts) (optional)

 - [mautrix/googlechat](https://mau.dev/mautrix/googlechat/container_registry) - the [mautrix-googlechat](https://github.com/mautrix/googlechat) bridge to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) (optional)

 - [mautrix/instagram](https://mau.dev/mautrix/instagram/container_registry) - the [mautrix-instagram](https://github.com/mautrix/instagram) bridge to [Instagram](https://instagram.com/) (optional)

 - [mautrix/signal](https://mau.dev/mautrix/signal/container_registry) - the [mautrix-signal](https://github.com/mautrix/signal) bridge to [Signal](https://www.signal.org/) (optional)

 - [matrixdotorg/matrix-appservice-irc](https://hub.docker.com/r/matrixdotorg/matrix-appservice-irc) - the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) (optional)

 - [halfshot/matrix-appservice-discord](https://hub.docker.com/r/halfshot/matrix-appservice-discord) - the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge to [Discord](https://discordapp.com/) (optional)

 - [cadair/matrix-appservice-slack](https://hub.docker.com/r/cadair/matrix-appservice-slack) - the [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) bridge to [Slack](https://slack.com/) (optional)

 - [turt2live/matrix-appservice-webhooks](https://hub.docker.com/r/turt2live/matrix-appservice-webhooks) - the [Appservice Webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge (optional)

 - [folivonet/matrix-sms-bridge](https://hub.docker.com/repository/docker/folivonet/matrix-sms-bridge) - the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) (optional)

 - [sorunome/mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) - the [mx-puppet-slack](https://github.com/Sorunome/mx-puppet-slack) bridge to [Slack](https://slack.com) (optional)

 - [sorunome/mx-puppet-instagram](https://hub.docker.com/r/sorunome/mx-puppet-instagram) - the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge to [Instagram](https://www.instagram.com) (optional)

 - [sorunome/mx-puppet-twitter](https://hub.docker.com/r/sorunome/mx-puppet-twitter) - the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge to [Twitter](https://twitter.com) (optional)

 - [sorunome/mx-puppet-discord](https://hub.docker.com/r/sorunome/mx-puppet-discord) - the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge to [Discord](https://discordapp.com) (optional)

 - [xangelix/mx-puppet-groupme](https://hub.docker.com/r/xangelix/mx-puppet-groupme) - the [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) bridge to [GroupMe](https://groupme.com/) (optional)

 - [icewind1991/mx-puppet-steam](https://hub.docker.com/r/icewind1991/mx-puppet-steam) - the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge to [Steam](https://steampowered.com) (optional)

 - [turt2live/matrix-dimension](https://hub.docker.com/r/turt2live/matrix-dimension) - the [Dimension](https://dimension.t2bot.io/) integrations manager (optional)

 - [jitsi/web](https://hub.docker.com/r/jitsi/web) - the [Jitsi](https://jitsi.org/) web UI (optional)

 - [jitsi/jicofo](https://hub.docker.com/r/jitsi/jicofo) - the [Jitsi](https://jitsi.org/) Focus component (optional)

 - [jitsi/prosody](https://hub.docker.com/r/jitsi/prosody) - the [Jitsi](https://jitsi.org/) Prosody XMPP server component (optional)

 - [jitsi/jvb](https://hub.docker.com/r/jitsi/jvb) - the [Jitsi](https://jitsi.org/) Video Bridge component (optional)

 - [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) - the [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) bot for one-off & recurring reminders and alarms (optional)

 - [moanos/matrix-registration-bot/](https://hub.docker.com/r/moanos/matrix-registration-bot/) - the [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) bot (manage registration tokens for invitations to the server) (optional)

 - [dock.mau.dev/maubot/maubot](https://mau.dev/maubot/maubot/container_registry) - the [maubot](https://github.com/maubot/maubot) bot (a plugin-based Matrix bot system) (optional)

 - [etke.cc/honoroit](https://gitlab.com/etke.cc/honoroit/container_registry) - the [honoroit](https://gitlab.com/etke.cc/honoroit) helpdesk bot (optional)

 - [etke.cc/postmoogle](https://gitlab.com/etke.cc/postmoogle/container_registry) - the [Postmoogle](https://gitlab.com/etke.cc/postmoogle) email bridge bot (optional)

 - [matrixdotorg/go-neb](https://hub.docker.com/r/matrixdotorg/go-neb) - the [Go-NEB](https://github.com/matrix-org/go-neb) bot (optional)

 - [matrixdotorg/mjolnir](https://hub.docker.com/r/matrixdotorg/mjolnir) - the [mjolnir](https://github.com/matrix-org/mjolnir) moderation bot (optional)

 - [awesometechnologies/synapse-admin](https://hub.docker.com/r/awesometechnologies/synapse-admin) - the [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) web UI tool for administrating users and rooms on your Matrix server (optional)

 - [prom/prometheus](https://hub.docker.com/r/prom/prometheus/) - [Prometheus](https://github.com/prometheus/prometheus/) is a systems and service monitoring system

 - [prom/node-exporter](https://hub.docker.com/r/prom/node-exporter/) - [Prometheus Node Exporter](https://github.com/prometheus/node_exporter/) is an addon for Prometheus that gathers standard system metrics

 - [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) - [Grafana](https://github.com/grafana/grafana/) is a graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/matrix-org/synapse/tree/master/contrib/grafana) and  [Node Exporter](https://github.com/rfrail3/grafana-dashboards)

 - [matrixdotorg/sygnal](https://hub.docker.com/r/matrixdotorg/sygnal/) - [Sygnal](https://github.com/matrix-org/sygnal) is a reference Push Gateway for Matrix

 - [binwiederhier/ntfy](https://hub.docker.com/r/binwiederhier/ntfy/) - [ntfy](https://ntfy.sh/) is a self-hosted, UnifiedPush-compatible push notifications server

 - [cactuscomments/cactus-appservice](https://hub.docker.com/r/cactuscomments/cactus-appservice/) - [Cactus Comments](https://cactus.chat) a federated comment system built on Matrix
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,475 +0,0 @@
 # Frequently Asked Questions

 This documentation page tries to answer various Frequently Asked Questions about all things [Matrix](https://matrix.org/), with a focus on this [Ansible](https://www.ansible.com/) playbook ([What is Ansible? How does it work?](#what-is-ansible-how-does-it-work)).

 This FAQ page does not intend to replace the [matrix.org FAQ](https://matrix.org/faq/) (please see that one too).

 We've only started this FAQ recently, so it's still somewhat empty.

 Also, we encourage you to not dig yourself into a hole by reading way too much. When you've heard enough, proceed to [Prerequisites](prerequisites.md) to get guided into installing Matrix.


 ## Introductory

 ## Where do I find more questions and answers about Matrix?

 This is a Frequently Asked Questions page focused on this [Ansible](https://www.ansible.com/) playbook ([What is Ansible? How does it work?](#what-is-ansible-how-does-it-work)) for deploying a [Matrix](https://matrix.org/) server.

 For a lot more generic questions and answers, see the [matrix.org FAQ](https://matrix.org/faq/).

 ## What is Matrix? What is Element? What is Synapse? Why are you confusing me with so many terms?

 [Matrix](https://matrix.org/) is a new type of realtime communication (chat) network, the closest analogy to which is probably "email".

 You don't just use the "email" protocols (SMTP, POP3, IMAP) directly though. There's a *server* somewhere which stores your data (`@gmail.com`, `@yahoo.com`, `@hotmail.com`, `@your-company.com`) and you access it by using these "email" protocols via some *client* program (Outlook, Thunderbird, some website, etc).

 In the world of the Matrix chat protocol, there are various client programs. The first and currently most full-featured one is called [Element](https://element.io/) (used to be called Riot.im and Vector.im in the past). There are [many other clients](https://matrix.org/clients/). You can switch clients as much as you want until you find the one that is right for you on a given platform (you may use Element on your desktop, but Fluffychat on your phone, etc).

 Matrix is also like email due to the fact that there are many servers around the world which can all talk to each other (you can send email from `@gmail.com` addresses to `@yahoo.com` and `@hotmail.com` addresses). It's the same with Matrix (`@bob:his-domain.com` can talk to `@alice:her-domain.org`).

 If someone else is hosting your Matrix server (you being `@user:matrix.org` or some other public server like this), all you need is a Matrix client program, like Element.

 If you'd like to host your own server (you being `@user:your-own-domain.com`), you'd need to set up a Matrix server program, like Synapse.

 In short:

 - Matrix is the protocol - a set of rules about how the chat network operates
 - Element is a client program you can use to participate on the Matrix chat network via some server (yours or someone else's). There are also [many other client programs](https://matrix.org/clients/).
 - Synapse is a server program you can use to host your very own Matrix server.

 This FAQ here mostly focuses on installing various Matrix services using the Ansible automation tool. You can learn much more about Matrix in the [matrix.org FAQ](https://matrix.org/faq/).

 ## People I wish to talk to are not on Matrix. Can I talk to them?

 You most likely can. Besides Matrix-native chats, Matrix also supports the concept of "bridging", which allows you to plug other networks into it.

 This Ansible playbook can help you install [tens of bridges for various networks](configuring-playbook.md#bridging-other-networks).

 Besides setting up your own bridges (preferable), you can also use some [public bridges hosted by others](https://publiclist.anchel.nl/#bridges).

 ## How do I get started with Matrix?

 One of [Matrix](https://matrix.org/)'s distinguishing strengths (compared to other chat networks) is its decentralized nature. There's not just one entity (company, organization) controlling the servers. Rather there's thousands of servers operated by different people - one server being insecure, slow or disrespective toward its users does not affect the rest of the network. To participate in that decentralization in its fullest, consider hosting your own server or using some public server other than the largest/default one (`matrix.org`).

 There are 3 ways to get into Martix, depending on your technical ability and needs:

 - **using the existing default server** - the easiest way is to use an existing server. The largest public Matrix server is `matrix.org` and it's configured as a default server in clients such as [Element](https://element.io) and many others. Just use Element on the browser via that link (or download the Element app on a smartphone), create an account and start chatting.

 - **using some other server** - instead of using the largest public server (`matrix.org`), you can use another public one. Here's a [list of public Matrix servers](https://joinmatrix.org/servers/) to choose from. Again, you download [Element](https://element.io) or [some other client](https://matrix.org/clients/) of your choosing and adjust the homeserver URL during login.

 - **using your own server** - running your own server puts you in ultimate control of your data. It also lets you have your own user identifiers (e.g. `@bob:your-domain.com`). See [How do I set up my own Matrix server](#how-do-i-set-up-my-own-matrix-server).

 ### How do I set up my own Matrix server?

 Normally, you'd first choose the [Matrix](https://matrix.org/) server software you'd like to run. At the time of this writing (January/2021), there's only one fully-featured server program, so there's only one reasonable choice. That's [Synapse](https://github.com/matrix-org/synapse).

 There are [many guides about installing Synapse](https://matrix.org/docs/guides/#installing-synapse). Using this Ansible playbook is just one way of doing it.

 Naturally, we're biased, so our usual recommendation is to go with this [Ansible](https://www.ansible.com/) playbook, instead of installing Synapse (and many many other things around it) manually.
 To get started with the playbook, start at the [Prerequisites](prerequisites.md) page.

 ### What is Ansible? How does it work?

 [Ansible](https://www.ansible.com/) is an automation program. This "playbook" is a collection of tasks/scripts that will set up a [Matrix](https://matrix.org/) server for you, so you don't have to perform these tasks manually.

 We have written these automated tasks for you and all you need to do is execute them using the Ansible program.

 You can install Ansible and this playbook code repository on your own computer and tell it to install Matrix services at the server living at `matrix.DOMAIN`. We recommend installing Ansible on your own computer.

 Alternatively, you can download Ansible and the playbook itself directly on the `matrix.DOMAIN` server.

 To learn more, see our [dedicated Ansible documentation page](ansible.md).

 ### Why use this playbook and not install Synapse and other things manually?

 There are various guides telling you how easy it is to install [Synapse](https://github.com/matrix-org/synapse).

 Reading the documentation of this Ansible playbook, you may also be thinking:

 > I don't know what [Ansible](https://www.ansible.com/) is. I don't know what [Docker](https://www.docker.com/) is. This looks more complicated.

 .. so you may be leaning toward [installing Synapse manually](https://github.com/matrix-org/synapse/blob/master/INSTALL.md).

 The problem with a manual installation is:

 - Synapse is written in Python. If not packaged for your distribution, you'd need to install various Python modules, etc., and keep them updated.
 - Synapse requires a [Postgres](https://www.postgresql.org/) database (it can run on SQLite, but that's very much discouraged). So you'd need to install Postgres as well.
 - you may also need a reverse-proxy server in front of it (nginx, Apache), so you'd need to be familiar with that
 - SSL is required, so you'd need to obtain Let's Encrypt (or other free or non-free) certificates for one or more domain names. You'd need to be familiar with [certbot](https://certbot.eff.org/) (when using Let's Encrypt) or similar software.
 - for each additional component you'd like to add (client like [Element](https://element.io), bridge to some other chat network, Integration Manager (sitckers, other services), Identity Manager, etc.), you'll need to spend extra time installing and wiring it with the rest of the system in a way that works.
 - you'll likely get slower updates for all of these components, depending on your distro packaging or your own time and ability

 The playbook, on the other hand, installs a bunch of components for you by default, obtains SSL certificates for you, etc. If you'd like, you can enable various bridges and other services with very little effort. All the components are wired to work together.

 All services run in Docker containers (most being officially provided by each component's developers), so we're not at the mercy of distro packaging.

 ### Why use this playbook and not just use the Docker image directly?

 Reasons are similar to the reasons for not installing manually.

 Besides Synapse, you'd need other things - a Postgres database, likely the [Element](https://element.io) client, etc., etc.

 Using the playbook, you get all these components in a way that works well together out of the box.

 ### What's different about this Ansible playbook compared to [EMnify/matrix-synapse-auto-deploy](https://github.com/EMnify/matrix-synapse-auto-deploy)?

 This is similar to the [EMnify/matrix-synapse-auto-deploy](https://github.com/EMnify/matrix-synapse-auto-deploy) Ansible deployment, but:

 - this one is a complete Ansible playbook (instead of just a role), so it's **easier to run** - especially for folks not familiar with Ansible

 - this one installs and hooks together **a lot more Matrix-related services** for you (see above)

 - this one **can be executed more than once** without causing trouble

 - works on various distros: **CentOS** (7.0+), Debian-based distributions (**Debian** 10/Buster+, **Ubuntu** 18.04+), **Archlinux**

 - this one installs everything in a single directory (`/matrix` by default) and **doesn't "contaminate" your server** with files all over the place

 - this one **doesn't necessarily take over** ports 80 and 443. By default, it sets up nginx for you there, but you can also [use your own webserver](configuring-playbook-own-webserver.md)

 - this one **runs everything in Docker containers**, so it's likely more predictable and less fragile (see [Docker images used by this playbook](container-images.md))

 - this one retrieves and automatically renews free [Let's Encrypt](https://letsencrypt.org/) **SSL certificates** for you

 - this one optionally can store the `media_store` content repository files on [Amazon S3](https://aws.amazon.com/s3/) (but defaults to storing files on the server's filesystem)

 - this one optionally **allows you to use an external PostgreSQL server** for Synapse's database (but defaults to running one in a container)

 - helps you **import data from a previous installation** (so you can migrate your manual virtualenv/Docker setup to a more managed one)

 - this one is actually **maintained**

 ## Server-related

 ### What kind of server do I need to install Matrix using this Ansible playbook?

 We list our server requirements in [Prerequisites](prerequisites.md).

 ### Why not run Matrix on Kubernetes?

 There's no reason not to run Matrix on [Kubernetes](https://kubernetes.io/).

 However, that's overly complicated for thousands of us who just want to run a single small (and sometimes not so small) Matrix server, either using "cloud" servers or even a [Raspberry Pi](https://www.raspberrypi.org/) at home.

 For us, a Kubernetes-based setup which requires a cluster of multiple computers and is more technically-involved is a no-go.

 There are others working on automating a Matrix-on-Kubernetes setup, such as this [Helm](https://helm.sh/) chart: https://github.com/dacruz21/matrix-chart.

 ### Why don't you use Podman instead of Docker?

 We like the philosophy of a daemonless container runtime, but [Podman](https://podman.io) is just not ready for our use case yet.

 Learn more about our past experiences/attempts to give Podman a chance, by reading [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/520).

 In short, `alias podman=docker` is a lie (for us).

 ### Why use Docker?

 [Docker](https://www.docker.com/) is one of our 2 hard dependencies (the other one being [systemd](https://systemd.io/)).

 It lets us run services in an isolated manner and independently of the (usually old) packages available for distributions.

 It also lets us have a unified setup which runs the same across various supported distros (see them on [Prerequisites](prerequisites.md)).

 ### Is Docker a hard requirement?

 Yes. See [Why don't you use Podman instead of Docker?](#why-dont-you-use-podman-instead-of-docker) for why we're not using another container runtime.

 All of our services run in containers. It's how we achieve predictability and also how we support tens of different services across lots of distros.

 The only thing we need on the distro is systemd and Python (we install Docker ourselves, unless you ask us not to).

 ### Why don't you use docker-compose?

 Instead of using [docker-compose](https://docs.docker.com/compose/), we prefer installing systemd services and scheduling those independently.

 There are people who have worked on turning this setup into a docker-compose-based one. See these experiments [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/64#issuecomment-603164625).

 ### Can I run this on a distro without systemd?

 No. [systemd](https://systemd.io/) is one of our 2 hard dependencies (the other one being [Docker](https://www.docker.com/)).

 ### Can I install this on a Raspberry Pi?

 Yes, you can. See our [Alternative Architectures](alternative-architectures.md) documentation page.

 Whether a Raspberry Pi has enough power to give you a good experience is another question. It depends on your use case.

 Also see: [What kind of server specs do I need?](#what-kind-of-server-specs-do-i-need).

 ### What kind of server specs do I need?

 This largely depends on your use case. It's not so much the number of users that you plan to host, but rather the number of large rooms they will join.

 Federated rooms with lots of history and containing hundreds of other servers are very heavy CPU-wise and memory-wise.

 You can probably use a 1 CPU + 1GB memory server to host hundreds of local users just fine, but as soon as one of them joins a federated room like `#matrix:matrix.org` (Matrix HQ) or some IRC-bridged room (say `##linux`), your server will get the need for a lot more power (at least 2GB RAM, etc).

 Running Matrix on a server with 1GB of memory is possible (especially if you disable some not-so-important services). See [How do I optimize this setup for a low-power server?](#how-do-i-optimize-this-setup-for-a-low-power-server).

 **We recommend starting with a server having at least 2GB of memory** and even then using it sparingly. If you know for sure you'll be joining various large rooms, etc., then going for 4GB of memory or more is a good idea.

 Besides the regular Matrix stuff, we also support things like video-conferencing using [Jitsi](configuring-playbook-jitsi.md) and other additional services which (when installed) may use up a lot of memory. Things do add up. Besides the Synapse Matrix server, Jitsi is especially notorious for consuming a lot of resources. If you plan on running Jitsi, we recommend a server with at least 2GB of memory (preferrably more). See our [Jitsi documentation page](configuring-playbook-jitsi.md) to learn how to optimize its memory/CPU usage.

 ### Can I run this in an LXC container?

 If your distro runs within an [LXC container](https://linuxcontainers.org/), you may hit [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/703). It can be worked around, if absolutely necessary, but we suggest that you avoid running from within an LXC container.


 ## Configuration

 ### Why install my server at matrix.DOMAIN and not at the base DOMAIN?

 It's the same with email servers. Your email address is likely `name@company.com`, not `name@mail.company.com`, even though it's `mail.company.com` that is really handling your data for `@company.com` email to work.

 Using a separate domain name is easier to manage (although it's a little hard to get right at first) and keeps your Matrix server isolated from your website (if you have one), from your email server (if you have one), etc.

 We allow `matrix.DOMAIN` to be the Matrix server handling Matrix stuff for `DOMAIN` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method.

 If you'd really like to install Matrix services directly on the base domain, see [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain)

 ### I don't control anything on the base domain and can't set up delegation to matrix.DOMAIN. What do I do?

 If you're not in control of your base domain (or the server handling it) at all, you can take a look at [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain)

 ### I can't set up HTTPS on the base domain. How will I get Matrix federating?

 If you really can't obtain an HTTPS certificate for your base domain, you can take a look at [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain)

 ### How do I install on matrix.DOMAIN without involving the base DOMAIN?

 This Ansible playbook guides you into installing a server for `DOMAIN` (user identifiers are like this: `@user:DOMAIN`), while the server is at `matrix.DOMAIN`.

 We allow `matrix.DOMAIN` to be the Matrix server handling Matrix stuff for `DOMAIN` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method.

 If you're fine with uglier identifiers (`@user:matrix.DOMAIN`, which is the equivalent of having an email address like `bob@mail.company.com`, instead of just `bob@company.com`), you can do that as well using the following configuration in your `vars.yml` file:

 ```yaml
 # This is what your identifiers are like (e.g. `@bob:matrix.YOUR_BASE_DOMAIN`).
 matrix_domain: "matrix.YOUR_BASE_DOMAIN"

 # This is where Matrix services
 matrix_server_fqn_matrix: "matrix.YOUR_BASE_DOMAIN"

 # This is where you access the Element web UI from (if enabled via `matrix_client_element_enabled: true`; enabled by default).
 # This and the Matrix FQN (see above) are expected to be on the same server.
 #
 # Feel free to use `element.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that.
 matrix_server_fqn_element: "element.YOUR_BASE_DOMAIN"

 # This is where you access Dimension (if enabled via `matrix_dimension_enabled: true`; NOT enabled by default).
 #
 # Feel free to use `dimension.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that.
 matrix_server_fqn_dimension: "dimension.YOUR_BASE_DOMAIN"

 # This is where you access Jitsi (if enabled via `matrix_jitsi_enabled: true`; NOT enabled by default).
 #
 # Feel free to use `jitsi.matrix.YOUR_BASE_DOMAIN`, if you'd prefer that.
 matrix_server_fqn_jitsi: "jitsi.YOUR_BASE_DOMAIN"
 ```

 ### I don't use the base domain for anything. How am I supposed to set up Server Delegation for Matrix services?

 If you don't use your base domain for anything, then it's hard for you to "serve files over HTTPS" on it -- something we ask you to do for the [.well-known](configuring-well-known.md) setup (needed for [Server Delegation](howto-server-delegation.md)).

 Luckily, the playbook can set up your Matrix server (at `matrix.DOMAIN`) to also handle traffic for the base domain (`DOMAIN`).

 See [Serving the base domain](configuring-playbook-base-domain-serving.md).

 ### How do I optimize this setup for a low-power server?

 You can disable some not-so-important services to save on memory.

 ```yaml
 # An identity server is not a must.
 matrix_ma1sd_enabled: false

 # Disabling this will prevent email-notifications and other such things from working.
 matrix_mailer_enabled: false

 # You can also disable this to save more RAM,
 # at the expense of audio/video calls being unreliable.
 matrix_coturn_enabled: false

 # This makes Synapse not keep track of who is online/offline.
 #
 # Keeping track of this and announcing such online-status in federated rooms with
 # hundreds of servers inside is insanely heavy (https://github.com/matrix-org/synapse/issues/3971).
 #
 # If your server does not federate with hundreds of others, enabling this doesn't hurt much.
 matrix_synapse_presence_enabled: false
 ```

 You can also consider implementing a restriction on room complexity, in order to prevent users from joining very heavy rooms:

 ```yaml
 matrix_synapse_configuration_extension_yaml: |
  limit_remote_rooms:
    enabled: true
    complexity: 1.0 # this limits joining complex (~large) rooms, can be
 					# increased, but larger values can require more RAM
 ```

 If you've installed [Jitsi](configuring-playbook-jitsi.md) (not installed by default), there are additional optimizations listed on its documentation page that you can perform.

 ### I already have Docker on my server. Can you stop installing Docker via the playbook?

 Yes, we can stop installing Docker ourselves. Just use this in your `vars.yml` file:

 ```yaml
 matrix_docker_installation_enabled: true
 ```

 ### I run another webserver on the same server where I wish to install Matrix. What now?

 By default, we install a webserver for you (nginx), but you can also use [your own webserver](configuring-playbook-own-webserver.md).

 ### How is the effective configuration determined?

 Configuration variables are defined in multiple places in this playbook and are considered in this order:

 - there are defaults coming from each role's defaults file (`role/matrix*/defaults/main.yml`). These variable values aim to be good defaults for when the role is used standalone (outside of this collection of roles, also called playbook).

 - then, there are overrides in `group_vars/matrix_servers`, which aim to adjust these "standalone role defaults" to something which better fits the playbook in its entirety.

 - finally, there's your `inventory/host_vars/matrix.DOMAIN/vars.yml` file, which is the ultimate override

 ### What configuration variables are available?

 You can discover the variables you can override in each role (`role/matrix*/defaults/main.yml`).

 As described in [How is the effective configuration determined?](#how-is-the-effective-configuration-determined), these role-defaults may be overriden by values defined in `group_vars/matrix_servers`.

 Refer to both of these for inspiration. Still, as mentioned in [Configuring the playbook](configuring-playbook.md), you're only ever supposed to edit your own `inventory/host_vars/matrix.DOMAIN/vars.yml` file and nothing else inside the playbook (unless you're meaning to contribute new features).

 ### I'd like to adjust some configuration which doesn't have a corresponding variable. How do I do it?

 The playbook doesn't aim to expose all configuration settings for all services using variables.
 Doing so would amount to hundreds of variables that we have to create and maintain.

 Instead, we only try to make some important basics configurable using dedicated variables you can see in each role.
 See [What configuration variables are available?](#what-configuration-variables-are-available).

 Besides that, each role (component) aims to provide a `matrix_SOME_COMPONENT_configuration_extension_yaml` (or `matrix_SOME_COMPONENT_configuration_extension_json`) variable, which can be used to override the configuration.

 Check each role's `role/matrix*/defaults/main.yml` for the corresponding variable and an example for how use it.


 ## Installation

 ### How do I run the installation?

 See [Installing](installing.md) to learn how to use Ansible to install Matrix services.

 Of course, don't just jump straight to Installing. Rather, start at [Prerequisites](prerequisites.md) and get guided from there (into [setting up DNS](configuring-dns.md), [configuring the playbook](configuring-playbook.md), etc).

 ### I installed Synapse some other way. Can I migrate such a setup to the playbook?

 Yes, you can.

 You generally need to do a playbook installation (start at the [Prerequisites](prerequisites.md) page), followed by importing your existing data into it.

 This Ansible playbook guides you into installing a server for `DOMAIN` (user identifiers are like this: `@user:DOMAIN`), while the server is at `matrix.DOMAIN`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `DOMAIN`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup - [How do I install on matrix.DOMAIN without involving the base DOMAIN?](#how-do-i-install-on-matrixdomain-without-involving-the-base-domain)

 After configuring the playbook and installing and **before starting** services (done with `ansible-playbook ... --tags=start`) you'd import [your SQLite](importing-synapse-sqlite.md) (or [Postgres](importing-postgres.md)) database and also [import your media store](importing-synapse-media-store.md).

 ### I've downloaded Ansible and the playbook on the server. It can't connect using SSH.

 If you're using the playbook directly on the server, then Ansible doesn't need to connect using SSH.

 It can perform a local connection instead. Just set `ansible_connection=local` at the end of the server line in `inventory/hosts` and re-run the playbook.

 If you're running Ansible from within a container (one of the possibilities we list on our [dedicated Ansible documentation page](ansible.md)), then using `ansible_connection=local` is not possible.


 ## Troubleshooting

 ### I get "Error response from daemon: configured logging driver does not support reading" when I do `docker logs matrix-synapse`.

 See [How can I see the logs?](#how-can-i-see-the-logs).

 ### How can I see the logs?

 We utilize [systemd/journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html#Description) for logging.

 To see logs for Synapse, run `journalctl -fu matrix-synapse.service`. You may wish to see the [manual page for journalctl](https://www.commandlinux.com/man-page/man1/journalctl.1.html).

 Available service names can be seen by doing `ls /etc/systemd/system/matrix*.service` on the server.

 Some services also log to files in `/matrix/*/data/..`, but we're slowly moving away from that.

 We also disable Docker logging, so you can't use `docker logs matrix-*` either. We do this to prevent useless double (or even triple) logging and to avoid having to rotate log files.

 We just simply delegate logging to journald and it takes care of persistence and expiring old data.

 Also see: [How long do systemd/journald logs persist for?](#how-long-do-systemdjournald-logs-persist-for)

 ### How long do systemd/journald logs persist for?

 On some distros, the journald logs are just in-memory and not persisted to disk.

 Consult (and feel free to adjust) your distro's journald logging configuration in `/etc/systemd/journald.conf`.

 To enable persistence and put some limits on how large the journal log files can become, adjust your configuration like this:

 ```ini
 [Journal]
 RuntimeMaxUse=200M
 SystemMaxUse=1G
 RateLimitInterval=0
 RateLimitBurst=0
 Storage=persistent
 ```


 ## Maintenance

 ### Do I need to do anything to keep my Matrix server updated?

 Yes. We don't update anything for you automatically.

 See our [documentation page about upgrading services](maintenance-upgrading-services.md).

 ### How do I move my existing installation to another (VM) server?

 If you have an existing installation done using this Ansible playbook, you can easily migrate that to another server using [our dedicated server migration guide](maintenance-migrating.md).

 If your previous installation is done in some other way (not using this Ansible playbook), see [I installed Synapse some other way. Can I migrate such a setup to the playbook?](#i-installed-synapse-some-other-way-can-i-migrate-such-a-setup-to-the-playbook).

 ### How do I back up the data on my server?

 We haven't documented this properly yet, but the general advice is to:

 - back up Postgres by making a database dump. See [Backing up PostgreSQL](maintenance-postgres.md#backing-up-postgresql)

 - back up all `/matrix` files, except for `/matrix/postgres/data` (you already have a dump) and `/matrix/postgres/data-auto-upgrade-backup` (this directory may exist and contain your old data if you've [performed a major Postgres upgrade](maintenance-postgres.md#upgrading-postgresql)).

 You can later restore these roughly like this:

 - restore the `/matrix` directory and files on the new server manually
 - run the playbook again (see [Installing](installing.md)), but **don't** start services yet (**don't run** `... --tags=start`). This step will fix any file permission mismatches and will also set up additional software (Docker, etc.) and files on the server (systemd service, etc.).
 - perform a Postgres database import (see [Importing Postgres](importing-postgres.md)) to restore your database backup
 - start services (see [Starting the services](installing.md#starting-the-services))

 If your server's IP address has changed, you may need to [set up DNS](configuring-dns.md) again.

 ### What is this `/matrix/postgres/data-auto-upgrade-backup` directory that is taking up so much space?

 When you [perform a major Postgres upgrade](maintenance-postgres.md#upgrading-postgresql), we save the the old data files in `/matrix/postgres/data-auto-upgrade-backup`, just so you could easily restore them should something have gone wrong.

 After verifying that everything still works after the Postgres upgrade, you can safely delete `/matrix/postgres/data-auto-upgrade-backup`

 ### How do I debug or force SSL certificate renewal?

 SSL certificate renewal normally happens automatically via [systemd timers](https://wiki.archlinux.org/index.php/Systemd/Timers).

 If you're having trouble with SSL certificate renewal, you can inspect the renewal logs using:

 - `journalctl -fu matrix-ssl-lets-encrypt-certificates-renew.service`
 - *or* by looking at the log files in `/matrix/ssl/log/`

 To trigger renewal, run: `systemctl start matrix-ssl-lets-encrypt-certificates-renew.service`. You can then take a look at the logs again.

 If you're using the integrated webserver (`matrix-nginx-proxy`), you can reload it manually like this: `systemctl reload matrix-nginx-proxy`. Reloading also happens periodically via a systemd timer.

 If you're [using your own webserver](configuring-playbook-own-webserver.md) instead of the integrated one (`matrix-nginx-proxy`) you may also need to reload/restart it, to make it pick up the renewed SSL certificate files.
--- a/docs/getting-the-playbook.md
+++ b/docs/getting-the-playbook.md
@@ -1,41 +0,0 @@
 # Getting the playbook

 This Ansible playbook is meant to be executed on your own computer (not the Matrix server).

 In special cases (if your computer cannot run Ansible, etc.) you may put the playbook on the server as well.

 You can retrieve the playbook's source code by:

 - [Using git to get the playbook](#using-git-to-get-the-playbook) (recommended)

 - [Downloading the playbook as a ZIP archive](#downloading-the-playbook-as-a-zip-archive) (not recommended)


 ## Using git to get the playbook

 We recommend using the [git](https://git-scm.com/) tool to get the playbook's source code, because it lets you easily keep up to date in the future when [Maintaining services](maintenance-upgrading-services.md).

 Once you've installed git on your computer, you can go to any directory of your choosing and run the following command to retrieve the playbook's source code:

 ```bash
 git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
 ```

 This will create a new `matrix-docker-ansible-deploy` directory.
 You're supposed to execute all other installation commands inside that directory.


 ## Downloading the playbook as a ZIP archive

 Alternatively, you can download the playbook as a ZIP archive.
 This is not recommended, as it's not easy to keep up to date with future updates. We suggest you [use git](#using-git-to-get-the-playbook) instead.

 The latest version is always at the following URL: https://github.com/spantaleev/matrix-docker-ansible-deploy/archive/master.zip

 You can extract this archive anywhere. You'll get a directory called `matrix-docker-ansible-deploy-master`.
 You're supposed to execute all other installation commands inside that directory.


 ---------------------------------------------

 No matter which method you've used to download the playbook, you can proceed by [Configuring the playbook](configuring-playbook.md).
--- a/docs/howto-server-delegation.md
+++ b/docs/howto-server-delegation.md
@@ -1,132 +0,0 @@
 # Server Delegation

 To have a server on a subdomain (e.g. `matrix.<your-domain>`) handle Matrix federation traffic for the base domain (`<your-domain>`), we need to instruct the Matrix network of such a delegation.

 By default, this playbook guides you into setting up [Server Delegation via a well-known file](#server-delegation-via-a-well-known-file).
 However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation.

 It is a complicated matter, so unless you are affected by the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation), we suggest you stay on the simple/default path.


 ## Server Delegation via a well-known file

 Serving a `/.well-known/matrix/server` file from the base domain is the most straightforward way to set up server delegation, but it suffers from some problems that we list in [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation).

 As we already mention in [Configuring DNS](configuring-dns.md) and [Configuring Service Discovery via .well-known](configuring-well-known.md),
 this playbook already properly guides you into setting up such delegation by means of a `/.well-known/matrix/server` file served from the base domain (`<your-domain>`).

 If this is okay with you, feel free to not read ahead.


 ### Downsides of well-known-based Server Delegation

 Server Delegation by means of a `/.well-known/matrix/server` file is the most straightforward, but suffers from the following downsides:

 - you need to have a working HTTPS server for the base domain (`<your-domain>`). If you don't have any server for the base domain at all, you can easily solve it by making the playbook [serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md).

 - any downtime on the base domain (`<your-domain>`) or network trouble between the matrix subdomain (`matrix.<your-domain>`) and the base `<domain>` may cause Matrix Federation outages. As the [Server-Server spec says](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery):

 > Errors are recommended to be cached for up to an hour, and servers are encouraged to exponentially back off for repeated failures.

 **For most people, this is a reasonable tradeoff** given that it's easy and straightforward to set up. We recommend you stay on this path.

 Otherwise, you can decide to go against the default for this playbook, and instead set up [Server Delegation via a DNS SRV record (advanced)](#server-delegation-via-a-dns-srv-record-advanced) (much more complicated).


 ## Server Delegation via a DNS SRV record (advanced)

 **NOTE**: doing Server Delegation via a DNS SRV record is a more **advanced** way to do it and is not the default for this playbook. This is usually **much more complicated** to set up, so **we don't recommend it**. If you're not an experience sysadmin, you'd better stay away from this.

 As per the [Server-Server spec](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), it's possible to do Server Delegation using only a SRV record (without a `/.well-known/matrix/server` file).

 This prevents you from suffering the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation).

 To use DNS SRV record validation, you need to:

 - ensure that `/.well-known/matrix/server` is **not served** from the base domain, as that would interfere with DNS SRV record Server Delegation. To make the playbook **not** generate and serve the file, use the following configuration: `matrix_well_known_matrix_server_enabled: false`.

 - ensure that you have a `_matrix._tcp` DNS SRV record for your base domain (`<your-domain>`) with a value of `10 0 8448 matrix.<your-domain>`

 - ensure that you are serving the Matrix Federation API (tcp/8448) with a certificate for `<your-domain>` (not `matrix.<your-domain>`!). Getting this certificate to the `matrix.<your-domain>` server may be complicated. The playbook's automatic SSL obtaining/renewal flow will likely not work and you'll need to copy certificates around manually. See below.


 ### Obtaining certificates

 How you can obtain a valid certificate for `<your-domain>` on the `matrix.<your-domain>` server is up to you.

 If `<your-domain>` and `matrix.<your-domain>` are hosted on the same machine, you can let the playbook obtain the certificate for you, by following our [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) guide.

 If `<your-domain>` and `matrix.<your-domain>` are not hosted on the same machine, you can copy over the certificate files manually.
 Don't forget that they may get renewed once in a while, so you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire.


 ### Serving the Federation API with your certificates

 Regardless of which method for obtaining certificates you've used, once you've managed to get certificates for your base domain onto the `matrix.<your-domain>` machine you can put them to use.

 Based on your setup, you have different ways to go about it:

 - [Serving the Federation API with your certificates and matrix-nginx-proxy](#serving-the-federation-api-with-your-certificates-and-matrix-nginx-proxy)

 - [Serving the Federation API with your certificates and another webserver](#serving-the-federation-api-with-your-certificates-and-another-webserver)

 - [Serving the Federation API with your certificates and Synapse handling Federation](#serving-the-federation-api-with-your-certificates-and-synapse-handling-federation)


 ### Serving the Federation API with your certificates and matrix-nginx-proxy

 **If you are using matrix-nginx-proxy**, a reverse-proxy webserver used by default in this playbook, you only need to override the certificates used for the Matrix Federation API. You can do that using:

 ```yaml
 # Adjust paths below to point to your certificate.
 #
 # NOTE: these are in-container paths. `/matrix/ssl` on the host is mounted into the container
 # at the same path (`/matrix/ssl`) by default, so if that's the path you need, it would be seamless.
 matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate: /matrix/ssl/config/live/<your-domain>/fullchain.pem
 matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: /matrix/ssl/config/live/<your-domain>/privkey.pem
 ```

 If your files are not in `/matrix/ssl` but in some other location, you would need to mount them into the container:

 ```yaml
 matrix_nginx_proxy_container_extra_arguments:
  - "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
 ```

 You then refer to them (for `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate` and `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key`) by using `/some/path/inside/the/container`.

 Make sure to reload matrix-nginx-proxy once in a while (`systemctl reload matrix-nginx-proxy`), so that newer certificates can kick in.
 Reloading doesn't cause any downtime.


 ### Serving the Federation API with your certificates and another webserver

 **If you are NOT using matrix-nginx-proxy**, but rather some other webserver, you can set up reverse-proxying for the `tcp/8448` port by yourself.
 Make sure to use the proper certificates for `<your-domain>` (not for `matrix.<your-domain>`) when serving the `tcp/8448` port.

 Proxying needs to happen to `127.0.0.1:8048` (unencrypted Synapse federation listener).

 Make sure to reload/restart your webserver once in a while, so that newer certificates can kick in.


 ### Serving the Federation API with your certificates and Synapse handling Federation

 **Alternatively**, if you are **NOT using matrix-nginx-proxy** and **would rather not use your own webserver for Federation traffic**, you can let Synapse handle Federation by itself.

 To do that, make sure the certificate files are mounted into the Synapse container:

 ```yaml
 matrix_synapse_container_extra_arguments:
  - "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
 ```

 You can then tell Synapse to serve Federation traffic over TLS on `tcp/8448`:

 ```yaml
 matrix_synapse_tls_federation_listener_enabled: true
 matrix_synapse_tls_certificate_path: /some/path/inside/the/container/certificate.crt
 matrix_synapse_tls_private_key_path: /some/path/inside/the/container/private.key
 ```

 Make sure to reload Synapse once in a while (`systemctl reload matrix-synapse`), so that newer certificates can kick in.
 Reloading doesn't cause any downtime.
--- a/docs/importing-postgres.md
+++ b/docs/importing-postgres.md
@@ -1,105 +0,0 @@
 # Importing an existing Postgres database from another installation (optional)

 Run this if you'd like to import your database from a previous installation.
 (don't forget to import your Synapse `media_store` files as well - see [the importing-synape-media-store guide](importing-synapse-media-store.md)).


 ## Prerequisites

 For this to work, **the database name in Postgres must match** what this playbook uses.
 This playbook uses a Postgres database name of `synapse` by default (controlled by the `matrix_synapse_database_database` variable).
 If your database name differs, be sure to change `matrix_synapse_database_database` to your desired name and to re-run the playbook before proceeding.

 The playbook supports importing Postgres dump files in **text** (e.g. `pg_dump > dump.sql`) or **gzipped** formats (e.g. `pg_dump | gzip -c > dump.sql.gz`).

 Importing multiple databases (as dumped by `pg_dumpall`) is also supported.
 But the migration might be a good moment, to "reset" a not properly working bridge. Be aware, that it might affect all users (new link to bridge, new rooms, ...)

 Before doing the actual import, **you need to upload your Postgres dump file to the server** (any path is okay).


 ## Importing

 To import, run this command (make sure to replace `<server-path-to-postgres-dump.sql>` with a file path on your server):

 ```sh
 ansible-playbook -i inventory/hosts setup.yml \
 --extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql> postgres_default_import_database=matrix' \
 --tags=import-postgres
 ```

 **Notes**:

 - `<server-path-to-postgres-dump.sql>` must be a file path to a Postgres dump file on the server (not on your local machine!)
 - `postgres_default_import_database` defaults to `matrix`, which is useful for importing multiple databases (for dumps made with `pg_dumpall`). If you're importing a single database (e.g. `synapse`), consider changing `postgres_default_import_database` accordingly


 ## Troubleshooting

 ### Table Ownership
 A table ownership issue can occur if you are importing from a Synapse installation which was both:

 - migrated from SQLite to Postgres, and
 - used a username other than 'synapse'

 In this case you may run into the following error during the import task:

 ```
 "ERROR:  role \"synapse_user\" does not exist"
 ```

 where `synapse_user` is the database username from the previous Synapse installation.

 This can be verified by examining the dump for ALTER TABLE statements which set OWNER TO that username:

 ```Shell
 $ grep "ALTER TABLE" homeserver.sql
 ALTER TABLE public.access_tokens OWNER TO synapse_user;
 ALTER TABLE public.account_data OWNER TO synapse_user;
 ALTER TABLE public.account_data_max_stream_id OWNER TO synapse_user;
 ALTER TABLE public.account_validity OWNER TO synapse_user;
 ALTER TABLE public.application_services_state OWNER TO synapse_user;
 ...
 ```

 It can be worked around by changing the username to `synapse`, for example by using `sed`:

 ```Shell
 $ sed -i "s/OWNER TO synapse_user;/OWNER TO synapse;/g" homeserver.sql
 ```

 This uses sed to perform an 'in-place' (`-i`) replacement globally (`/g`), searching for `synapse_user` and replacing with `synapse` (`s/synapse_user/synapse`). If your database username was different, change `synapse_user` to that username instead. Expand search/replace statement as shown in example above, in case of old user name like `matrix` - replacing `matrix` only would... well - you can imagine.

 Note that if the previous import failed with an error it may have made changes which are incompatible with re-running the import task right away; if you do so it may fail with an error such as:

 ```
 ERROR:  relation \"access_tokens\" already exists
 ```

 ### Repeat import

 In this case you can use the command suggested in the import task to clear the database before retrying the import:

 ```Shell
 # systemctl stop matrix-postgres
 # rm -rf /matrix/postgres/data/*
 # systemctl start matrix-postgres
 ```

 Now on your local machine run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-postgres` to prepare the database roles etc.

 If not, you probably get this error. `synapse` is the correct table owner, but the role is missing in database.
 ```
 "ERROR:  role synapse does not exist"
 ```

 Once the database is clear and the ownership of the tables has been fixed in the SQL file, the import task should succeed.
 Check, if `--dbname` is set to `synapse` (not `matrix`) and replace paths (or even better, copy this line from your terminal)

 ```
 /usr/bin/env docker run --rm --name matrix-postgres-import --log-driver=none --user=998:1001 --cap-drop=ALL --network=matrix --env-file=/matrix/postgres/env-postgres-psql --mount type=bind,src=/migration/synapse_dump.sql,dst=/synapse_dump.sql,ro --entrypoint=/bin/sh docker.io/postgres:14.1-alpine -c "cat /synapse_dump.sql | grep -vE '^(CREATE|ALTER) ROLE (matrix)(;| WITH)' | grep -vE '^CREATE DATABASE (matrix)\s' | psql -v ON_ERROR_STOP=1 -h matrix-postgres --dbname=synapse"
 ```

 ### Hints

 To open psql terminal run `/usr/local/bin/matrix-postgres-cli`
--- a/docs/importing-synapse-media-store.md
+++ b/docs/importing-synapse-media-store.md
@@ -1,22 +0,0 @@
 # Importing `media_store` data files from an existing Synapse installation (optional)

 Run this if you'd like to import your `media_store` files from a previous installation of Synapse.


 ## Prerequisites

 Before doing the actual data restore, **you need to upload your media store directory to the server** (any path is okay).

 If you are [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional), restoring with this tool is not possible right now.
 As an alternative, you can perform a manual restore using the [AWS CLI tool](https://aws.amazon.com/cli/) (e.g. `aws s3 sync /path/to/server/media_store/. s3://name-of-bucket/`)

 **Note for Mac users**: Due to case-sensitivity issues on certain Mac filesystems (HFS or HFS+), filename corruption may occur if you copy a `media_store` directory to your Mac. If you're transferring a `media_store` directory between 2 servers, make sure you do it directly (from server to server with a tool such as [rsync](https://rsync.samba.org/)), and not by downloading the files to your Mac.


 ## Importing

 Run this command (make sure to replace `<server-path-to-media_store>` with a path on your server):

 	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_media_store=<server-path-to-media_store>' --tags=import-synapse-media-store

 **Note**: `<server-path-to-media_store>` must be a file path to a `media_store` directory on the server (not on your local machine!).
--- a/docs/importing-synapse-sqlite.md
+++ b/docs/importing-synapse-sqlite.md
@@ -1,26 +0,0 @@
 # Importing an existing SQLite database from another Synapse installation (optional)

 Run this if you'd like to import your database from a previous default installation of Synapse.
 (don't forget to import your `media_store` files as well - see [the importing-synapse-media-store guide](importing-synapse-media-store.md)).

 While this playbook always sets up PostgreSQL, by default a Synapse installation would run
 using an SQLite database.

 If you have such a Synapse setup and wish to migrate it here (and over to PostgreSQL), this command is for you.


 ## Prerequisites

 Before doing the actual import, **you need to upload your SQLite database file to the server** (any path is okay).


 ## Importing

 Run this command (make sure to replace `<server-path-to-homeserver.db>` with a file path on your server):

 	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_homeserver_db=<server-path-to-homeserver.db>' --tags=import-synapse-sqlite-db

 **Notes**:

 - `<server-path-to-homeserver.db>` must be a file path to a `homeserver.db` **file on the server** (not on your local machine!).
 - if the SQLite database is from an older version of Synapse, the **importing procedure may run migrations on it to bring it up to date**. That is, your SQLite database file may get modified and become unusable with your older Synapse version. Keeping a copy of the original is probably wise.
--- a/docs/installing.md
+++ b/docs/installing.md
@@ -1,56 +0,0 @@
 # Installing

 ## 1. Installing the Matrix services

 If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure.

 Run this command to install the Matrix services:

 ```bash
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
 ```

 The above command **doesn't start any services just yet** (another step does this later - below). Feel free to **re-run this setup command any time** you think something is off with the server configuration.

 **Notes**:
 - if you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the above (and all other) Ansible commands.
 - if you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to the above (and all other) Ansible commands.


 ## 2. Things you might want to do after installing

 **Before starting the services**, you may want to do additional things like:

 - [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)

 - [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)

 - [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)


 ## 3. Starting the services

 When you're ready to start the Matrix services (and set them up to auto-start in the future), run this command:

 ```bash
 ansible-playbook -i inventory/hosts setup.yml --tags=start
 ```

 ## 4. Finalize the installation

 Now that services are running, you need to **finalize the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md).


 ## 5. Things to do next

 After you have started the services and **finalized the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md), you can:

 - [check if services work](maintenance-checking-services.md)
 - or [create your first Matrix user account](registering-users.md)
 - or [set up additional services](configuring-playbook.md#other-configuration-options) (bridges to other chat networks, bots, etc.)
 - or learn how to [upgrade services when new versions are released](maintenance-upgrading-services.md)
 - or learn how to [maintain your server](faq.md#maintenance)
 - or join some Matrix rooms:
  * via the *Explore rooms* feature in Element or some other client, or by discovering them using this [matrix-static list](https://view.matrix.org). Note: joining large rooms may overload small servers.
  * or come say Hi in our support room - [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting.
 - or help make this playbook better by contributing (code, documentation, or [coffee/beer](https://liberapay.com/s.pantaleev/donate))
--- a/docs/maintenance-and-troubleshooting.md
+++ b/docs/maintenance-and-troubleshooting.md
@@ -1,49 +0,0 @@
 # Maintenance and Troubleshooting

 ## How to see the current status of your services

 You can check the status of your services by using `systemctl status`. Example:
 ```
 sudo systemctl status matrix-nginx-proxy

 ● matrix-nginx-proxy.service - Matrix nginx proxy server
   Loaded: loaded (/etc/systemd/system/matrix-nginx-proxy.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2018-11-14 19:38:35 UTC; 49min ago
 ```

 You can see the logs by using journalctl. Example:
 ```
 sudo journalctl -fu matrix-synapse
 ```


 ## Increasing Synapse logging

 Because the [Synapse](https://github.com/matrix-org/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`.

 If you'd like to debug an issue or [report a Synapse bug](https://github.com/matrix-org/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increasing the logging level to `INFO`.

 Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`):

 ```yaml
 matrix_synapse_log_level: "INFO"
 matrix_synapse_storage_sql_log_level: "INFO"
 matrix_synapse_root_log_level: "INFO"
 ```

 Re-run the playbook after making these configuration changes.

 ## Remove unused Docker data

 You can free some disk space from Docker, see [docker system prune](https://docs.docker.com/engine/reference/commandline/system_prune/) for more information.
 ```bash
 ansible-playbook -i inventory/hosts setup.yml --tags=run-docker-prune
 ```

 ## Postgres

 See the dedicated [PostgreSQL Maintenance](maintenance-postgres.md) documentation page.

 ## Ma1sd

 See the dedicated [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md) documentation page.
--- a/docs/maintenance-checking-services.md
+++ b/docs/maintenance-checking-services.md
@@ -1,13 +0,0 @@
 # Checking if services work

 This playbook can perform a check to ensure that you've configured things correctly and that services are running.

 To perform the check, run:

 ```bash
 ansible-playbook -i inventory/hosts setup.yml --tags=self-check
 ```

 If it's all green, everything is probably running correctly.

 Besides this self-check, you can also check your server using the [Federation Tester](https://federationtester.matrix.org/).
--- a/docs/maintenance-migrating.md
+++ b/docs/maintenance-migrating.md
@@ -1,14 +0,0 @@
 > **Note**: This migration guide is applicable if you migrate from one server to another server having the same CPU architecture (e.g. both servers being `amd64`). 
 > 
 > If you're trying to migrate between different architectures (e.g. `amd64` --> `arm64`), simply copying the complete `/matrix` directory is not possible as it would move the raw PostgreSQL data between different architectures. In this specific case, you can use the guide below as a reference, but you would also need to dump the database on your current server and import it properly on the new server. See our [Backing up PostgreSQL](maintenance-postgres.md#backing-up-postgresql) docs for help with PostgreSQL backup/restore.

 # Migrating to new server

 1. Prepare by lowering DNS TTL for your domains (`matrix.DOMAIN`, etc.), so that DNS record changes (step 4 below) would happen faster, leading to less downtime
 2. Stop all services on the old server and make sure they won't be starting again. Execute this on the old server: `systemctl disable --now matrix*`
 3. Copy directory `/matrix` from the old server to the new server. Make sure to preserve ownership and permissions (use `cp -p` or `rsync -ar`)!
 4. Make sure your DNS records are adjusted to point to the new server's IP address
 5. Remove old server from the `inventory/hosts` file and add new server.
 6. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-system-user`. This will create the `matrix` user and group on the new server
 7. Because the `matrix` user and group are created dynamically on each server, the user/group id may differ between the old and new server. We suggest that you adjust ownership of `/matrix` files manually by running this on the new server: `chown -R matrix:matrix /matrix`.
 8. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` to finish the installation and start all services
--- a/docs/maintenance-postgres.md
+++ b/docs/maintenance-postgres.md
@@ -1,159 +0,0 @@
 # PostgreSQL maintenance

 This document shows you how to perform various maintenance tasks related to the Postgres database server used by Matrix.

 Table of contents:

 - [Getting a database terminal](#getting-a-database-terminal), for when you wish to execute SQL queries

 - [Vacuuming PostgreSQL](#vacuuming-postgresql), for when you wish to run a Postgres [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html) (optimizing disk space)

 - [Backing up PostgreSQL](#backing-up-postgresql), for when you wish to make a backup

 - [Upgrading PostgreSQL](#upgrading-postgresql), for upgrading to new major versions of PostgreSQL. Such **manual upgrades are sometimes required**.

 - [Tuning PostgreSQL](#tuning-postgresql) to make it run faster

 ## Getting a database terminal

 You can use the `/usr/local/bin/matrix-postgres-cli` tool to get interactive terminal access ([psql](https://www.postgresql.org/docs/11/app-psql.html)) to the PostgreSQL server.

 If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above tool will not be available.

 By default, this tool puts you in the `matrix` database, which contains nothing.

 To see the available databases, run `\list` (or just `\l`).

 To change to another database (for example `synapse`), run `\connect synapse` (or just `\c synapse`).

 You can then proceed to write queries. Example: `SELECT COUNT(*) FROM users;`

 **Be careful**. Modifying the database directly (especially as services are running) is dangerous and may lead to irreversible database corruption.
 When in doubt, consider [making a backup](#backing-up-postgresql).


 ## Vacuuming PostgreSQL

 Deleting lots data from Postgres does not make it release disk space, until you perform a `VACUUM` operation.

 To perform a `FULL` Postgres [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html), run the playbook with `--tags=run-postgres-vacuum`.

 Example:

 ```bash
 ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-vacuum,start
 ```

 **Note**: this will automatically stop Synapse temporarily and restart it later. You'll also need plenty of available disk space in your Postgres data directory (usually `/matrix/postgres/data`).


 ## Backing up PostgreSQL

 To automatically make Postgres database backups on a fixed schedule, see [Setting up postgres backup](configuring-playbook-postgres-backup.md).

 To make a one off back up of the current PostgreSQL database, make sure it's running and then execute a command like this on the server:

 ```bash
 /usr/bin/docker exec \
 --env-file=/matrix/postgres/env-postgres-psql \
 matrix-postgres \
 /usr/local/bin/pg_dumpall -h matrix-postgres \
 | gzip -c \
 > /matrix/postgres.sql.gz
 ```

 If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above command will not work, because neither the credentials file (`/matrix/postgres/env-postgres-psql`), nor the `matrix-postgres` container is available.

 Restoring a backup made this way can be done by [importing it](importing-postgres.md).


 ## Upgrading PostgreSQL

 Unless you are using an [external Postgres server](configuring-playbook-external-postgres.md), this playbook initially installs Postgres for you.

 Once installed, the playbook attempts to preserve the Postgres version it starts with.
 This is because newer Postgres versions cannot start with data generated by older Postgres versions.

 Upgrades must be performed manually.

 This playbook can upgrade your existing Postgres setup with the following command:

 	ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres

 **The old Postgres data directory is backed up** automatically, by renaming it to `/matrix/postgres/data-auto-upgrade-backup`.
 To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="postgres_auto_upgrade_backup_data_path=/another/disk/matrix-postgres-before-upgrade"`

 The auto-upgrade-backup directory stays around forever, until you **manually decide to delete it**.

 As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty Postgres server is started, and then the dump is restored into the new server.
 To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`

 To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage.
 If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`.
 Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`

 **All databases, roles, etc. on the Postgres server are migrated**.


 ## Tuning PostgreSQL

 PostgreSQL can be tuned to make it run faster. This is done by passing extra arguments to Postgres with the `matrix_postgres_process_extra_arguments` variable. You should use a website like https://pgtune.leopard.in.ua/ or information from https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server to determine what Postgres settings you should change.

 **Note**: the configuration generator at https://pgtune.leopard.in.ua/ adds spaces around the `=` sign, which is invalid. You'll need to remove it manually (`max_connections = 300` -> `max_connections=300`)

 ### Here are some examples:

 These are not recommended values and they may not work well for you. This is just to give you an idea of some of the options that can be set. If you are an experienced PostgreSQL admin feel free to update this documentation with better examples.

 Here is an example config for a small 2 core server with 4GB of RAM and SSD storage:
 ```
 matrix_postgres_process_extra_arguments: [
  "-c shared_buffers=128MB",
  "-c effective_cache_size=2304MB",
  "-c effective_io_concurrency=100",
  "-c random_page_cost=2.0",
  "-c min_wal_size=500MB",
 ]
 ```

 Here is an example config for a 4 core server with 8GB of RAM on a Virtual Private Server (VPS); the paramters have been configured using https://pgtune.leopard.in.ua with the following setup: PostgreSQL version 12, OS Type: Linux, DB Type: Mixed type of application, Data Storage: SSD storage:
 ```
 matrix_postgres_process_extra_arguments: [
  "-c max_connections=100",
  "-c shared_buffers=2GB",
  "-c effective_cache_size=6GB",
  "-c maintenance_work_mem=512MB",
  "-c checkpoint_completion_target=0.9",
  "-c wal_buffers=16MB",
  "-c default_statistics_target=100",
  "-c random_page_cost=1.1",
  "-c effective_io_concurrency=200",
  "-c work_mem=5242kB",
  "-c min_wal_size=1GB",
  "-c max_wal_size=4GB",
  "-c max_worker_processes=4",
  "-c max_parallel_workers_per_gather=2",
  "-c max_parallel_workers=4",
  "-c max_parallel_maintenance_workers=2",
 ]
 ```

 Here is an example config for a large 6 core server with 24GB of RAM:
 ```
 matrix_postgres_process_extra_arguments: [
  "-c max_connections=40",
  "-c shared_buffers=1536MB",
  "-c checkpoint_completion_target=0.7",
  "-c wal_buffers=16MB",
  "-c default_statistics_target=100",
  "-c random_page_cost=1.1",
  "-c effective_io_concurrency=100",
  "-c work_mem=2621kB",
  "-c min_wal_size=1GB",
  "-c max_wal_size=4GB",
  "-c max_worker_processes=6",
  "-c max_parallel_workers_per_gather=3",
  "-c max_parallel_workers=6",
  "-c max_parallel_maintenance_workers=3",
 ]
 ```
--- a/docs/maintenance-synapse.md
+++ b/docs/maintenance-synapse.md
@@ -1,77 +0,0 @@
 # Synapse maintenance

 This document shows you how to perform various maintenance tasks related to the Synapse chat server.

 Table of contents:

 - [Purging old data with the Purge History API](#purging-old-data-with-the-purge-history-api), for when you wish to delete in-use (but old) data from the Synapse database

 - [Compressing state with rust-synapse-compress-state](#compressing-state-with-rust-synapse-compress-state)

 - [Browse and manipulate the database](#browse-and-manipulate-the-database), for when you really need to take matters into your own hands

 - [Make Synapse faster](#make-synapse-faster)

 ## Purging old data with the Purge History API

 You can use the **[Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md)** to delete old messages on a per-room basis. **This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.

 To make use of this API, **you'll need an admin access token** first. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).

 Synapse's Admin API is not exposed to the internet by default. To expose it you will need to add `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true` to your `vars.yml` file.

 Follow the [Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md) documentation page for the actual purging instructions.

 After deleting data, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).


 ## Compressing state with rust-synapse-compress-state

 [rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state) can be used to optimize some `_state` tables used by Synapse. If your server participates in large rooms this is the most effective way to reduce the size of your database.

 This tool should be safe to use (even when Synapse is running), but it's always a good idea to [make Postgres backups](./maintenance-postgres.md#backing-up-postgresql) first.

 To ask the playbook to run rust-synapse-compress-state, execute:

 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=rust-synapse-compress-state
 ```

 By default, all rooms with more than `100000` state group rows will be compressed.
 If you need to adjust this, pass: `--extra-vars='matrix_synapse_rust_synapse_compress_state_min_state_groups_required=SOME_NUMBER_HERE'` to the command above.

 After state compression, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).


 ## Browse and manipulate the database

 When the [Synapse Admin API](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) and the other tools do not provide a more convenient way, having a look at synapse's postgresql database can satisfy a lot of admins' needs.

 Editing the database manually is not recommended or supported by the Synapse developers. If you are going to do so you should [make a database backup](./maintenance-postgres.md#backing-up-postgresql).

 First, set up an SSH tunnel to your matrix server (skip if it is your local machine):

 ```
 # you may replace 1799 with an arbitrary port unbound on both machines
 ssh -L 1799:localhost:1799 matrix.DOMAIN
 ```

 Then start up an ephemeral [adminer](https://www.adminer.org/) container on the Matrix server, connecting it to the `matrix` network and linking the postgresql container:

 ```
 docker run --rm --publish 1799:8080 --link matrix-postgres --net matrix adminer
 ```

 You should then be able to browse the adminer database administration GUI at http://localhost:1799/ after entering your DB credentials (found in the `host_vars` or on the server in `{{matrix_synapse_config_dir_path}}/homeserver.yaml` under `database.args`)

 ⚠️ Be **very careful** with this, there is **no undo** for impromptu DB operations.

 ## Make Synapse faster

 Synapse's presence feature which tracks which users are online and which are offline can use a lot of processing power. You can disable presence by adding `matrix_synapse_presence_enabled: false` to your `vars.yml` file.

 Tuning Synapse's cache factor can help reduce RAM usage. [See the upstream documentation](https://github.com/matrix-org/synapse#help-synapse-is-slow-and-eats-all-my-ram-cpu) for more information on what value to set the cache factor to. Use the variable `matrix_synapse_caches_global_factor` to set the cache factor.

 Tuning your PostgreSQL database will also make Synapse run significantly faster. See [maintenance-postgres.md##tuning-postgresql](maintenance-postgres.md##tuning-postgresql).

 See also [How do I optimize this setup for a low-power server?](faq.md#how-do-i-optimize-this-setup-for-a-low-power-server).
--- a/docs/maintenance-upgrading-services.md
+++ b/docs/maintenance-upgrading-services.md
@@ -1,17 +0,0 @@
 # Upgrading the Matrix services

 This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available.

 If you want to be notified when new versions of Synapse are released, you should join the Synapse Homeowners room: [#homeowners:matrix.org](https://matrix.to/#/#homeowners:matrix.org).

 To upgrade services:

 - update your playbook directory (`git pull`), so you'd obtain everything new we've done

 - take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of

 - re-run the [playbook setup](installing.md): `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`

 - restart the services: `ansible-playbook -i inventory/hosts setup.yml --tags=start`

 **Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).
--- a/docs/obtaining-access-tokens.md
+++ b/docs/obtaining-access-tokens.md
@@ -1,49 +0,0 @@
 # Obtaining an Access Token

 When setting up some optional features like bots and bridges you will need to provide an access token for some user. This document provides documentation on how to obtain such an access token.

 **Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**

 ## Prerequisites

 The user for whom you want to obtain an access token needs to already exist. You can use this playbook to [register a new user](registering-users.md), if you have not already.

 Below, we describe 2 ways to generate an access token for a user - using [Element](#obtain-an-access-token-via-element) or [curl](#obtain-an-access-token-via-curl). For both ways you need the user's password.

 ## Obtain an access token via Element

 1. In a private browsing session (incognito window), open Element.
 1. Log in with the user's credentials.
 1. In the settings page, choose "Help & About", scroll down to the bottom and expand the `Access Token` section (see screenshot below).
 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.

 ![Obtaining an access token with Element](assets/obtain_admin_access_token_element.png)


 ## Obtain an access token via curl

 You can use the following command to get an access token for your user directly from the [Matrix Client-Server API](https://www.matrix.org/docs/guides/client-server-api#login):

 ```
 curl -XPOST -d '{
    "identifier": { "type": "m.id.user", "user": "USERNAME" },
    "password": "PASSWORD",
    "type": "m.login.password",
    "device_id": "YOURDEVICEID"
 }' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
 ```
 Change `USERNAME`, `PASSWORD`, and `YOURDOMAIN` accordingly.

 `YOURDEVICEID` is optional and can be used to more easily identify the session later. When omitted (mind the commas in the JSON payload if you'll be omitting it), a random device ID will be generated.

 Your response will look like this (prettified):

 ```
 {
    "user_id":"@USERNAME:YOURDOMAIN",
    "access_token":">>>YOUR_ACCESS_TOKEN_IS_HERE<<<",
    "home_server":"YOURDOMAIN",
    "device_id":"YOURDEVICEID"
 }
 ```
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
@@ -1,41 +0,0 @@
 # Prerequisites

 To install Matrix services using this Ansible playbook, you need:

 - (Recommended) An **x86** server ([What kind of server specs do I need?](faq.md#what-kind-of-server-specs-do-i-need)) running one of these operating systems:
  - **CentOS** (7 only for now; [8 is not yet supported](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/300))
  - **Debian** (10/Buster or newer)
  - **Ubuntu** (18.04 or newer, although [20.04 may be problematic](ansible.md#supported-ansible-versions))
  - **Archlinux**

 Generally, newer is better. We only strive to support released stable versions of distributions, not betas or pre-releases. This playbook can take over your whole server or co-exist with other services that you have there.

 This playbook somewhat supports running on non-`amd64` architectures like ARM. See [Alternative Architectures](alternative-architectures.md).

 If your distro runs within an [LXC container](https://linuxcontainers.org/), you may hit [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/703). It can be worked around, if absolutely necessary, but we suggest that you avoid running from within an LXC container.

 - `root` access to your server (or a user capable of elevating to `root` via `sudo`).

 - [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python3`). On some distros, Ansible may incorrectly [detect the Python version](https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html) (2 vs 3) and you may need to explicitly specify the interpreter path in `inventory/hosts` during installation (e.g. `ansible_python_interpreter=/usr/bin/python3`)

 - The [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible.

 - [`git`](https://git-scm.com/) is the recommended way to download the playbook to your computer. `git` may also be required on the server if you will be [self-building](self-building.md) components.

 - An HTTPS-capable web server at the base domain name (`<your-domain>`) which is capable of serving static files. Unless you decide to [Serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md) or alternatively, to use DNS SRV records for [Server Delegation](howto-server-delegation.md).

 - Properly configured DNS records for `<your-domain>` (details in [Configuring DNS](configuring-dns.md)).

 - Some TCP/UDP ports open. This playbook (actually [Docker itself](https://docs.docker.com/network/iptables/)) configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports:

  - `80/tcp`: HTTP webserver
  - `443/tcp`: HTTPS webserver
  - `3478/tcp`: TURN over TCP (used by Coturn)
  - `3478/udp`: TURN over UDP (used by Coturn)
  - `5349/tcp`: TURN over TCP (used by Coturn)
  - `5349/udp`: TURN over UDP (used by Coturn)
  - `8448/tcp`: Matrix Federation API HTTPS webserver. In some cases, this **may necessary even with federation disabled**. Integration Servers (like Dimension) and Identity Servers (like ma1sd) may need to access `openid` APIs on the federation port.
  - the range `49152-49172/udp`: TURN over UDP
  - potentially some other ports, depending on the additional (non-default) services that you enable in the **configuring the playbook** step (later on). Consult each service's documentation page in `docs/` for that.

 When ready to proceed, continue with [Configuring DNS](configuring-dns.md).
--- a/docs/registering-users.md
+++ b/docs/registering-users.md
@@ -1,70 +0,0 @@
 # Registering users

 This documentation page tells you how to create user account on your Matrix server.

 Table of contents:

 - [Registering users](#registering-users)
 	- [Registering users manually](#registering-users-manually)
 	- [Managing users via a Web UI](#managing-users-via-a-web-ui)
 	- [Letting certain users register on your private server](#letting-certain-users-register-on-your-private-server)
 	- [Enabling public user registration](#enabling-public-user-registration)
 	- [Adding/Removing Administrator privileges to an existing user](#addingremoving-administrator-privileges-to-an-existing-user)


 ## Registering users manually

 You can do it via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):

 ```
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user
 ```

 **or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):

 ```
 /usr/local/bin/matrix-synapse-register-user <your-username> <your-password> <admin access: 0 or 1>
 ```

 **Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:<your-domain>` identifier.

 **You can then log in with that user** via the Element service that this playbook has created for you at a URL like this: `https://element.<domain>/`.

 -----

 If you've just installed Matrix, **to finalize the installation process**, it's best if you proceed to [Configuring service discovery via .well-known](configuring-well-known.md)


 ## Managing users via a Web UI

 To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).


 ## Letting certain users register on your private server

 If you'd rather **keep your server private** (public registration closed, as is the default), and **let certain people create accounts by themselves** (instead of creating user accounts manually like this), consider installing and making use of [matrix-registration](configuring-playbook-matrix-registration.md).


 ## Enabling public user registration

 To **open up user registration publicly** (usually **not recommended**), consider using the following configuration:

 ```yaml
 matrix_synapse_enable_registration: true
 ```

 and running the [installation](installing.md) procedure once again.

 If you're opening up registrations publicly like this, you might also wish to [configure CAPTCHA protection](configuring-captcha.md).


 ## Adding/Removing Administrator privileges to an existing user

 The script `/usr/local/bin/matrix-change-user-admin-status` may be used to change a user's admin privileges.

 * log on to your server with ssh
 * execute with the username and 0/1 (0 = non-admin | 1 = admin)

 ```
 /usr/local/bin/matrix-change-user-admin-status <username> <0/1>
 ```
--- a/docs/self-building.md
+++ b/docs/self-building.md
@@ -1,45 +0,0 @@
 # Self-building

 **Caution: self-building does not have to be used on its own. See the [Alternative Architectures](alternative-architectures.md) page.**

 The playbook supports self-building of various components, which don't have a container image for your architecture (see the [container images we use](container-images.md)). For `amd64`, self-building is not required.

 For other architectures (e.g. `arm32`, `arm64`), ready-made container images are used when available. If there's no ready-made image for a specific component and said component supports self-building, an image will be built on the host. Building images like this takes more time and resources (some build tools need to get installed by the playbook to assist building).

 To make use of self-building, you don't need to do anything besides change your architecture variable (e.g. `matrix_architecture: arm64`). If a component has an image for the specified architecture, the playbook will use it directly. If not, it will build the image on the server itself.

 Note that **not all components support self-building yet**.

 List of roles where self-building the Docker image is currently possible:
 - `matrix-synapse`
 - `matrix-synapse-admin`
 - `matrix-client-element`
 - `matrix-client-hydrogen`
 - `matrix-client-cinny`
 - `matrix-registration`
 - `matrix-coturn`
 - `matrix-corporal`
 - `matrix-dimension`
 - `matrix-ma1sd`
 - `matrix-mailer`
 - `matrix-bridge-hookshot`
 - `matrix-bridge-appservice-irc`
 - `matrix-bridge-appservice-slack`
 - `matrix-bridge-appservice-webhooks`
 - `matrix-bridge-beeper-linkedin`
 - `matrix-bridge-mautrix-facebook`
 - `matrix-bridge-mautrix-hangouts`
 - `matrix-bridge-mautrix-googlechat`
 - `matrix-bridge-mautrix-telegram`
 - `matrix-bridge-mautrix-signal`
 - `matrix-bridge-mautrix-whatsapp`
 - `matrix-bridge-mx-puppet-steam`
 - `matrix-bot-mjolnir`
 - `matrix-bot-honoroit`
 - `matrix-bot-matrix-reminder-bot`
 - `matrix-bot-maubot`
 - `matrix-email2matrix`

 Adding self-building support to other roles is welcome. Feel free to contribute!

 If you'd like **to force self-building** even if an image is available for your architecture, look into the `matrix_*_self_build` variables provided by individual roles.