WIP: feat(synapse): sane defaults for compressing state without choking host CPU

Bridge mautrix signal and mautrix whatsapp encryption

.github/FUNDING.yml

@@ -0,0 +1,7 @@
+---
+# These are supported funding model platforms
+
+# https://liberapay.com/s.pantaleev/
+liberapay: s.pantaleev
+# https://ko-fi.com/spantaleev
+ko_fi: spantaleev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,57 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+<!--
+NOTE: This Ansible playbook installs tens of separate services. If you're having a problem with a specific service, it is likely that the problem is not with our deployment method, but with the service itself. You may wish to report that problem at the source, upstream, and not to us
+-->
+
+**To Reproduce**
+My `vars.yml` file looks like this:
+
+```yaml
+Paste your vars.yml file here.
+Make sure to remove any secret values before posting your vars.yml file publicly.
+```
+
+<!-- Below this line, tell us what you're doing to reproduce the problem. -->
+
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Matrix Server:**
+ - OS: [e.g. Ubuntu 21.04]
+ - Architecture [e.g. amd64, arm32, arm64]
+
+**Ansible:**
+If your problem appears to be with Ansible, tell us:
+- where you run Ansible -- e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
+- what version of Ansible you're running (see `ansible --version`)
+
+<!--
+The above is only applicable if you're hitting a problem with Ansible itself.
+We don't need this information in most cases. Delete this section if not applicable.
+-->
+
+**Client:**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+<!--
+The above is only applicable if you're hitting a problem with a specific device, but not with others.
+We don't need this information in most cases. Delete this section if not applicable.
+-->
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+<!--
+NOTE: When submitting feature requests, be aware that:
+
+- This Ansible playbook installs tens of separate services. If you're having a problem with a specific service or you'd like some functionality added to it, it is likely that the problem is not with our deployment method, but with the service itself. You may wish to report that problem at the source, upstream, and not to us.
+
+- This is a community project with no financial backing. The easiest way to get a feature into this project is to just develop it yourself.
+-->
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

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

@@ -0,0 +1,49 @@
+---
+name: I need help
+about: Get support from our community
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+NOTE: you can usually get more timely support and from more people by joining our Matrix room (also bridged to IRC). See the [Support section of our README](https://github.com/spantaleev/matrix-docker-ansible-deploy#support)
+-->
+
+**Playbook Configuration**:
+
+My `vars.yml` file looks like this:
+
+```yaml
+Paste your vars.yml file here.
+Make sure to remove any secret values before posting your vars.yml file publicly.
+```
+
+**Matrix Server:**
+ - OS: [e.g. Ubuntu 21.04]
+ - Architecture [e.g. amd64, arm32, arm64]
+
+**Ansible:**
+If your problem appears to be with Ansible, tell us:
+- where you run Ansible -- e.g. on the Matrix server itself; on another computer (which OS? distro? standard installation or containerized Ansible?)
+- what version of Ansible you're running (see `ansible --version`)
+
+**Problem description**:
+
+Describe what you're doing, what you expect to happen and what happens instead here.
+Tell us what you've tried and what you're aiming to achieve.
+
+**Client (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+<!--
+The above is only applicable if you're hitting a problem with a specific device, but not with others.
+We don't need this information in most cases. Delete this section if not applicable.
+-->
+
+**Additional context**
+Add any other context about the problem here.

.github/dependabot.yaml

@@ -0,0 +1,7 @@
+---
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: daily

.github/workflows/matrix.yml

@@ -0,0 +1,16 @@
+---
+name: Matrix CI
+
+on:  # yamllint disable-line rule:truthy
+  push:
+  pull_request:
+
+jobs:
+  yamllint:
+    name: 🧹 yamllint
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⤵️ Check out configuration from GitHub
+        uses: actions/checkout@v3
+      - name: 🚀 Run yamllint
+        uses: frenck/action-yamllint@v1.1.2

.gitignore

@@ -1,5 +1,3 @@
-/inventory/*
-!/inventory/.gitkeep
-!/inventory/host_vars/.gitkeep
-!/inventory/scripts
 /roles/*/files/scratchpad
+.DS_Store
+.python-version

.yamllint

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

CHANGELOG.md

@@ -1,3 +1,796 @@
+# 2022-04-25
+
+## buscarron bot support
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [the Buscarron bot](https://gitlab.com/etke.cc/buscarron). It's a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room
+
+See our [Setting up Buscarron](docs/configuring-playbook-bot-buscarron.md) documentation to get started.
+
+
+# 2022-04-21
+
+## matrix-registration-bot support
+
+Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now help you set up [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) - a bot that is used to create and manage registration tokens for a Matrix server.
+
+See our [Setting up matrix-registration-bot](docs/configuring-playbook-bot-matrix-registration-bot.md) documentation to get started.
+
+
+# 2022-04-19
+
+## Borg backup support
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [Borg](https://www.borgbackup.org/) backups with [borgmatic](https://torsion.org/borgmatic/) of your Matrix server.
+
+See our [Setting up borg backup](docs/configuring-playbook-backup-borg.md) documentation to get started.
+
+
+## (Compatibility Break) Upgrading to Synapse v1.57 on setups using workers may require manual action
+
+If you're running a worker setup for Synapse (`matrix_synapse_workers_enabled: true`), the [Synapse v1.57 upgrade notes](https://github.com/matrix-org/synapse/blob/v1.57.0rc1/docs/upgrade.md#changes-to-database-schema-for-application-services) say that you may need to take special care when upgrading:
+
+> Synapse v1.57.0 includes a change to the way transaction IDs are managed for application services. If your deployment uses a dedicated worker for application service traffic, **it must be stopped** when the database is upgraded (which normally happens when the main process is upgraded), to ensure the change is made safely without any risk of reusing transaction IDs.
+
+If you're not running an `appservice` worker (`matrix_synapse_workers_preset: little-federation-helper` or `matrix_synapse_workers_appservice_workers_count: 0`), you are probably safe to upgrade as per normal, without taking any special care.
+
+If you are running a setup with an `appservice` worker, or otherwise want to be on the safe side, we recommend the following upgrade path:
+
+0. Pull the latest playbook changes
+1. Stop all services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
+2. Re-run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`)
+3. Start Postgres (`systemctl start matrix-postgres` on the server)
+4. Start the main Synapse process (`systemctl start matrix-synapse` on the server)
+5. Wait a while so that Synapse can start and complete the database migrations. You can use `journalctl -fu matrix-synapse` on the server to get a clue. Waiting a few minutes should also be enough.
+6. It should now be safe to start all other services. `ansible-playbook -i inventory/hosts setup.yml --tags=start` will do it for you
+
+
+# 2022-04-14
+
+## (Compatibility Break) Changes to `docker-src` permissions necessitating manual action
+
+Users who build container images from source will need to manually correct file permissions of some directories on the server.
+
+When self-building, the playbook used to `git clone` repositories (into `/matrix/SERVICE/docker-src`) using the `root` user, but now uses `matrix` instead to work around [the following issue with git 2.35.2](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1749).
+
+If you're on a non-`amd64` architecture (that is, you're overriding `matrix_architecture` in your `vars.yml` file) or you have enabled self-building for some service (e.g. `matrix_*_self_build: true`), you're certainly building some container images from source and have `docker-src` directories with mixed permissions lying around in various `/matrix/SERVICE` directories.
+
+The playbook *could* correct these permissions automatically, but that requires additional Ansible tasks in some ~45 different places - something that takes considerable effort. So we ask users observing errors related to `docker-src` directories to correct the problem manually by **running this command on the Matrix server** (which deletes all `/matrix/*/docker-src` directories): `find /matrix -maxdepth 2 -name 'docker-src' | xargs rm -rf`
+
+
+# 2022-03-17
+
+## (Compatibility Break) ma1sd identity server no longer installed by default
+
+The playbook no longer installs the [ma1sd](https://github.com/ma1uta/ma1sd) identity server by default. The next time you run the playbook, ma1sd will be uninstalled from your server, unless you explicitly enable the ma1sd service (see how below).
+
+The main reason we used to install ma1sd by default in the past was to prevent Element from talking to the `matrix.org` / `vector.im` identity servers, by forcing it to talk to our own self-hosted (but otherwise useless) identity server instead, thus preventing contact list leaks.
+
+Since Element no longer defaults to using a public identity server if another one is not provided, we can stop installing ma1sd.
+
+If you need to install the ma1sd identity server for some reason, you can explicitly enable it by adding this to your `vars.yml` file:
+
+```yaml
+matrix_ma1sd_enabled: true
+```
+
+
+# 2022-02-12
+
+## matrix_encryption_disabler support
+
+We now support installing the [matrix_encryption_disabler](https://github.com/digitalentity/matrix_encryption_disabler) Synapse module, which lets you prevent End-to-End-Encryption from being enabled by users on your homeserver. The popular opinion is that this is dangerous and shouldn't be done, but there are valid use cases for disabling encryption discussed [here](https://github.com/matrix-org/synapse/issues/4401).
+
+To enable this module (and prevent encryption from being used on your homserver), add `matrix_synapse_ext_encryption_disabler_enabled: true` to your configuration. This module provides further customization. Check its other configuration settings (and defaults) in `roles/matrix-synapse/defaults/main.yml`.
+
+
+# 2022-02-01
+
+## matrix-hookshot bridging support
+
+Thanks to [HarHarLinks](https://github.com/HarHarLinks), the playbook can now install the [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) bridge for bridging Matrix to multiple project management services, such as GitHub, GitLab and JIRA.
+See our [Setting up matrix-hookshot](docs/configuring-playbook-bridge-hookshot.md) documentation to get started.
+
+
+# 2022-01-31
+
+## ARM support for matrix-corporal
+
+[matrix-corporal](https://github.com/devture/matrix-corporal) (as of version `2.2.3`) is now published to Docker Hub (see [devture/matrix-corporal](https://hub.docker.com/r/devture/matrix-corporal)) as a multi-arch container image with support for all these platforms: `linux/amd64`, `linux/arm64/v8` and `linux/arm/v7`. The playbook no longer resorts to self-building matrix-corporal on these ARM architectures.
+
+
+# 2022-01-07
+
+## Dendrite support
+
+**TLDR**: We now have optional experimental [Dendrite](https://github.com/matrix-org/dendrite) homeserver support for new installations. **Existing (Synapse) installations need to be updated**, because some internals changed. See [Adapting the configuration for existing Synapse installations](#adapting-the-configuration-for-existing-synapse-installations).
+
+[Jip J. Dekker](https://github.com/Dekker1) did the [initial work](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/818) of adding [Dendrite](https://github.com/matrix-org/dendrite) support to the playbook back in January 2021. Lots of work (and time) later, Dendrite support is finally ready for testing.
+
+We believe that 2022 will be the year of the non-Synapse Matrix server!
+
+The playbook was previously quite [Synapse](https://github.com/matrix-org/synapse)-centric, but can now accommodate multiple homeserver implementations. Only one homeserver implementation can be active (installed) at a given time.
+
+**Synapse is still the default homeserver implementation** installed by the playbook. A new variable (`matrix_homeserver_implementation`) controls which server implementation is enabled (`synapse` or `dendrite` at the given moment).
+
+### Adapting the configuration for existing Synapse installations
+
+Because the playbook is not so Synapse-centric anymore, a small configuration change is necessary for existing installations to bring them up to date.
+
+The `vars.yml` file for **existing installations will need to be updated** by adding this **additional configuration**:
+
+```yaml
+# All secrets keys are now derived from `matrix_homeserver_generic_secret_key`, not from `matrix_synapse_macaroon_secret_key`.
+# To keep them all the same, define `matrix_homeserver_generic_secret_key` in terms of `matrix_synapse_macaroon_secret_key`.
+# Using a new secret value for this configuration key is also possible and should not cause any problems.
+#
+# Fun fact: new installations (based on the new `examples/vars.yml` file) do this in reverse.
+# That is, the Synapse macaroon secret is derived from `matrix_homeserver_generic_secret_key`.
+matrix_homeserver_generic_secret_key: "{{ matrix_synapse_macaroon_secret_key }}"
+```
+
+### Trying out Dendrite
+
+Finally, **to try out Dendrite**, we recommend that you **use a new server** and the following addition to your `vars.yml` configuration:
+
+```yaml
+matrix_homeserver_implementation: dendrite
+```
+
+**The homeserver implementation of an existing server cannot be changed** (e.g. from Synapse to Dendrite) without data loss.
+
+We're excited to gain support for other homeserver implementations, like [Conduit](https://conduit.rs/), etc!
+
+
+## Honoroit bot support
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now help you set up [Honoroit](https://gitlab.com/etke.cc/honoroit) - a helpdesk bot.
+
+See our [Setting up Honoroit](docs/configuring-playbook-bot-honoroit.md) documentation to get started.
+
+
+# 2022-01-06
+
+## Cinny support
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook now supports [Cinny](https://cinny.in/) - a new simple, elegant and secure Matrix client.
+
+By default, we still install Element. Still, people who'd like to try Cinny out can now install it via the playbook.
+
+Additional details are available in [Setting up Cinny](docs/configuring-playbook-client-cinny.md).
+
+
+# 2021-12-22
+
+## Twitter bridging support via mautrix-twitter
+
+Thanks to [Matthew Cengia](https://github.com/mattcen) and [Shreyas Ajjarapu](https://github.com/shreyasajj), besides [mx-puppet-twitter](docs/configuring-playbook-bridge-mx-puppet-twitter.md), bridging to [Twitter](https://twitter.com/) can now also happen with [mautrix-twitter](docs/configuring-playbook-bridge-mautrix-twitter.md).
+
+
+# 2021-12-14
+
+## (Security) Users of the Signal bridge may wish to upgrade it to work around log4j vulnerability
+
+Recently, a security vulnerability affecting the Java logging package `log4j` [has been discovered](https://www.huntress.com/blog/rapid-response-critical-rce-vulnerability-is-affecting-java). Software that uses this Java package is potentially vulnerable.
+
+One such piece of software that is part of the playbook is the [mautrix-signal bridge](./docs/configuring-playbook-bridge-mautrix-signal.md), which [has been patched already](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1452). If you're running this bridge, you may wish to [upgrade](./docs/maintenance-upgrading-services.md).
+
+
+# 2021-11-11
+
+## Dropped support for Postgres v9.6
+
+Postgres v9.6 reached its end of life today, so the playbook will refuse to run for you if you're still on that version.
+
+Synapse still supports v9.6 (for now), but we're retiring support for it early, to avoid having to maintain support for so many Postgres versions. Users that are still on Postgres v9.6 can easily [upgrade Postgres](docs/maintenance-postgres.md#upgrading-postgresql) via the playbook.
+
+
+# 2021-10-23
+
+## Hangouts bridge no longer updated, superseded by a Googlechat bridge
+
+The mautrix-hangouts bridge is no longer receiving updates upstream and is likely to stop working in the future.
+We still retain support for this bridge in the playbook, but you're encouraged to switch away from it.
+
+There's a new [mautrix-googlechat](https://github.com/mautrix/googlechat) bridge that you can [install using the playbook](docs/configuring-playbook-bridge-mautrix-googlechat.md).
+Your **Hangouts bridge data will not be migrated**, however. You need to start fresh with the new bridge.
+
+
+# 2021-08-23
+
+## LinkedIn bridging support via beeper-linkedin
+
+Thanks to [Alexandar Mechev](https://github.com/apmechev), the playbook can now install the [beeper-linkedin](https://gitlab.com/beeper/linkedin) bridge for bridging to [LinkedIn](https://www.linkedin.com/) Messaging.
+
+This brings the total number of bridges supported by the playbook up to 20. See all supported bridges [here](docs/configuring-playbook.md#bridging-other-networks).
+
+To get started with bridging to LinkedIn, see [Setting up Beeper LinkedIn bridging](docs/configuring-playbook-bridge-beeper-linkedin.md).
+
+
+# 2021-08-20
+
+# Sygnal upgraded - ARM support and no longer requires a database
+
+The [Sygnal](docs/configuring-playbook-sygnal.md) push gateway has been upgraded from `v0.9.0` to `v0.10.1`.
+
+This is an optional component for the playbook, so most of our users wouldn't care about this announcement.
+
+Since this feels like a relatively big (and untested, as of yet) Sygnal change, we're putting up this changelog entry.
+
+The new version is also available for the ARM architecture. It also no longer requires a database anymore.
+If you need to downgrade to the previous version, changing `matrix_sygnal_version` or `matrix_sygnal_docker_image` will not be enough, as we've removed the `database` configuration completely. You'd need to switch to an earlier playbook commit.
+
+
+# 2021-05-21
+
+## Hydrogen support
+
+Thanks to [Aaron Raimist](https://github.com/aaronraimist), the playbook now supports [Hydrogen](https://github.com/vector-im/hydrogen-web) - a new lightweight matrix client with legacy and mobile browser support.
+
+By default, we still install Element, as Hydrogen is still not fully-featured. Still, people who'd like to try Hydrogen out can now install it via the playbook.
+
+Additional details are available in [Setting up Hydrogen](docs/configuring-playbook-client-hydrogen.md).
+
+
+# 2021-05-19
+
+## Heisenbridge support
+
+Thanks to [Toni Spets (hifi)](https://github.com/hifi), the playbook now supports bridging to [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) using yet another bridge (besides matrix-appservice-irc), called [Heisenbridge](https://github.com/hifi/heisenbridge).
+
+Additional details are available in [Setting up Heisenbridge bouncer-style IRC bridging](docs/configuring-playbook-bridge-heisenbridge.md).
+
+
+# 2021-04-16
+
+## Disabling TLSv1 and TLSv1.1 for Coturn
+
+To improve security, we've [removed TLSv1 and TLSv1.1 support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/999) from our default [Coturn](https://github.com/coturn/coturn) configuration.
+
+If you need to support old clients, you can re-enable both (or whichever one you need) with the following configuration:
+
+```yaml
+matrix_coturn_tls_v1_enabled: true
+matrix_coturn_tls_v1_1_enabled: true
+```
+
+
+# 2021-04-05
+
+## Automated local Postgres backup support
+
+Thanks to [foxcris](https://github.com/foxcris), the playbook can now make automated local Postgres backups on a fixed schedule using [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local).
+
+Additional details are available in [Setting up postgres backup](docs/configuring-playbook-postgres-backup.md).
+
+
+
+# 2021-04-03
+
+## Mjolnir moderation tool (bot) support
+
+Thanks to [Aaron Raimist](https://github.com/aaronraimist), the playbook can now install and configure the [Mjolnir](https://github.com/matrix-org/mjolnir) moderation tool (bot).
+
+Additional details are available in [Setting up Mjolnir](docs/configuring-playbook-bot-mjolnir.md).
+
+
+# 2021-03-20
+
+## Sygnal push gateway support
+
+The playbook can now install the [Sygnal](https://github.com/matrix-org/sygnal) push gateway for you.
+
+This is only useful to people who develop/build their own Matrix client applications.
+
+Additional details are available in our [Setting up Sygnal](docs/configuring-playbook-sygnal.md) docs.
+
+
+# 2021-03-16
+
+## Go-NEB support
+
+Thanks to [Zir0h](https://github.com/Zir0h), the playbook can now install and configure the [Go-NEB](https://github.com/matrix-org/go-neb) bot.
+
+Additional details are available in [Setting up Go-NEB](docs/configuring-playbook-bot-go-neb.md).
+
+
+# 2021-02-19
+
+## GroupMe bridging support via mx-puppet-groupme
+
+Thanks to [Cody Neiman](https://github.com/xangelix), the playbook can now install the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge for bridging to [GroupMe](https://groupme.com).
+
+This brings the total number of bridges supported by the playbook up to 18. See all supported bridges [here](docs/configuring-playbook.md#bridging-other-networks).
+
+To get started, follow our [Setting up MX Puppet GroupMe](docs/configuring-playbook-bridge-mx-puppet-groupme.md) docs.
+
+## Mautrix Instagram bridging support
+
+The playbook now supports bridging with [Instagram](https://www.instagram.com/) by installing the [mautrix-instagram](https://github.com/tulir/mautrix-instagram) bridge. This playbook functionality is available thanks to [@MarcProe](https://github.com/MarcProe).
+
+Additional details are available in [Setting up Mautrix Instagram bridging](docs/configuring-playbook-bridge-mautrix-instagram.md).
+
+## Synapse workers support
+
+After [lots and lots of work](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/456) (done over many months by [Marcel Partap](https://github.com/eMPee584), [Max Klenk](https://github.com/maxklenk), a few others from the [Technical University of Dresden, Germany](https://tu-dresden.de/) and various other contributors), support for Synapse workers has finally landed.
+
+Having support for workers makes the playbook suitable for larger homeserver deployments.
+
+Our setup is not yet perfect (we don't support all types of workers; scaling some of them (like `pusher`, `federation_sender`) beyond a single instance is not yet supported). Still, it's a great start and can already power homeservers with thousands of users, like the [Matrix deployment at TU Dresden](https://doc.matrix.tu-dresden.de/en/) discussed in [Matrix Live S06E09 - TU Dresden on their Matrix deployment](https://www.youtube.com/watch?v=UHJX2pmT2gk).
+
+By default, workers are disabled and Synapse runs as a single process (homeservers don't necessarily need the complexity and increased memory requirements of running a worker-based setup).
+
+To enable Synapse workers, follow our [Load balancing with workers](docs/configuring-playbook-synapse.md#load-balancing-with-workers) documentation.
+
+
+# 2021-02-12
+
+## (Potential Breaking Change) Monitoring/metrics support using Prometheus and Grafana
+
+Thanks to [@Peetz0r](https://github.com/Peetz0r), the playbook can now install a bunch of tools for monitoring your Matrix server: the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI.
+
+To get get these installed, follow our [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) docs page.
+
+This update comes with a **potential breaking change** for people who were already exposing Synapse metrics (for consumption via another Prometheus installation). From now on, `matrix_synapse_metrics_enabled: true` no longer exposes metrics publicly via matrix-nginx-proxy (at `https://matrix.DOMAIN/_synapse/metrics`). To do so, you'd need to explicitly set `matrix_nginx_proxy_proxy_synapse_metrics: true`.
+
+
+# 2021-01-31
+
+## Etherpad support
+
+Thanks to [@pushytoxin](https://github.com/pushytoxin), the playbook can now install the [Etherpad](https://etherpad.org) realtime collaborative text editor. It can be used in a [Jitsi](https://jitsi.org/) audio/video call or integrated as a widget into Matrix chat rooms via the [Dimension](https://dimension.t2bot.io) integration manager.
+
+To get it installed, follow [our Etherpad docs page](docs/configuring-playbook-etherpad.md).
+
+
+# 2021-01-22
+
+## (Breaking Change) Postgres changes that require manual intervention
+
+We've made a lot of changes to our Postgres setup and some manual action is required (described below). Sorry about the hassle.
+
+**TLDR**: people running an [external Postgres server](docs/configuring-playbook-external-postgres.md) don't need to change anything for now. Everyone else (the common/default case) is affected and manual intervention is required.
+
+### Why?
+
+- we had a default Postgres password (`matrix_postgres_connection_password: synapse-password`), which we think is **not ideal for security anymore**. We now ask you to generate/provide a strong password yourself. Postgres is normally not exposed outside the container network, making it relatively secure, but still:
+  - by tweaking the configuration, you may end up intentionally or unintentionally exposing your Postgres server to the local network (or even publicly), while still using the default default credentials (`synapse` + `synapse-password`)
+  - we can't be sure we trust all these services (bridges, etc). Some of them may try to talk to or attack `matrix-postgres` using the default credentials (`synapse` + `synapse-password`)
+  - you may have other containers running on the same Docker network, which may try to talk to or attack `matrix-postgres` using the default credentials (`synapse` + `synapse-password`)
+- our Postgres usage **was overly-focused on Synapse** (default username of `synapse` and default/main database of `homeserver`). Additional homeserver options are likely coming in the future ([Dendrite](https://matrix.org/docs/projects/server/dendrite), [Conduit](https://matrix.org/docs/projects/server/conduit), [The Construct](https://matrix.org/docs/projects/server/construct)), so being too focused on `matrix-synapse` is not great. From now on, Synapse is just another component of this playbook, which happens to have an *additional database* (called `synapse`) on the Postgres server.
+- we try to reorganize things a bit, to make the playbook even friendlier to people running an [external Postgres server](docs/configuring-playbook-external-postgres.md). Work on this will proceed in the future.
+
+So, this is some **effort to improve security** and to **prepare for a brighter future of having more homeserver options** than just Synapse.
+
+### What has really changed?
+
+- the default superuser Postgres username is now `matrix` (used to be `synapse`)
+- the default Postgres database is now `matrix` (used to be `homeserver`)
+- Synapse's database is now `synapse` (used to be `homeserver`). This is now just another "additional database" that the playbook manages for you
+- Synapse's user called `synapse` is just a regular user that can only use the `synapse` database (not a superuser anymore)
+
+### What do I do if I'm using the integrated Postgres server (default)?
+
+By default, the playbook runs an integrated Postgres server for you in a container (`matrix-postgres`). Unless you've explicitly configured an [external Postgres server](docs/configuring-playbook-external-postgres.md), these steps are meant for you.
+
+To migrate to the new setup, expect a few minutes of downtime, while you follow these steps:
+
+1. We believe the steps below are safe and you won't encounter any data loss, but consider [making a Postgres backup](docs/maintenance-postgres.md#backing-up-postgresql) anyway. If you've never backed up Postgres, now would be a good time to try it.
+
+2. Generate a strong password to be used for your superuser Postgres user (called `matrix`). You can use `pwgen -s 64 1` to generate it, or some other tool. The **maximum length** for a Postgres password is 100 bytes (characters). Don't go crazy!
+
+3. Update your playbook's `inventory/host_vars/matrix.DOMAIN/vars.yml` file, adding a line like this:
+```yaml
+matrix_postgres_connection_password: 'YOUR_POSTGRES_PASSWORD_HERE'
+```
+
+.. where `YOUR_POSTGRES_PASSWORD_HERE` is to be replaced with the password you generated during step #2.
+
+4. Stop all services: `ansible-playbook -i inventory/hosts setup.yml --tags=stop`
+5. Log in to the server via SSH. The next commands will be performed there.
+6. Start the Postgres database server: `systemctl start matrix-postgres`
+7. Open a Postgres shell: `/usr/local/bin/matrix-postgres-cli`
+8. Execute the following query, while making sure to **change the password inside** (**don't forget the ending `;`**):
+
+```sql
+CREATE ROLE matrix LOGIN SUPERUSER PASSWORD 'YOUR_POSTGRES_PASSWORD_HERE';
+```
+
+.. where `YOUR_POSTGRES_PASSWORD_HERE` is to be replaced with the password you generated during step #2.
+
+9. Execute the following queries as you see them (no modifications necessary, so you can just **paste them all at once**):
+
+```sql
+CREATE DATABASE matrix OWNER matrix;
+
+ALTER DATABASE postgres OWNER TO matrix;
+ALTER DATABASE template0 OWNER TO matrix;
+ALTER DATABASE template1 OWNER TO matrix;
+
+\c matrix;
+
+ALTER DATABASE homeserver RENAME TO synapse;
+
+ALTER ROLE synapse NOSUPERUSER NOCREATEDB NOCREATEROLE;
+
+\quit
+```
+
+You may need to press *Enter* after pasting the lines above.
+
+10. Re-run the playbook normally: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+
+### What do I do if I'm using an external Postgres server?
+
+If you've explicitly configured an [external Postgres server](docs/configuring-playbook-external-postgres.md), there are **no changes** that you need to do at this time.
+
+The fact that we've renamed Synapse's database from `homeserver` to `synapse` (in our defaults) should not affect you, as you're already explicitly defining `matrix_synapse_database_database` (if you've followed our guide, that is). If you're not explicitly defining this variable, you may wish to do so (`matrix_synapse_database_database: homeserver`), to avoid the new `synapse` default and keep things as they were.
+
+
+# 2021-01-20
+
+## (Breaking Change) The mautrix-facebook bridge now requires a Postgres database
+
+**Update from 2021-11-15**: SQLite support has been re-added to the mautrix-facebook bridge in [v0.3.2](https://github.com/mautrix/facebook/releases/tag/v0.3.2). You can ignore this changelog entry.
+
+A new version of the [mautrix-facebook](https://github.com/tulir/mautrix-facebook) bridge has been released. It's a full rewrite of its backend and the bridge now requires Postgres. New versions of the bridge can no longer run on SQLite.
+
+**TLDR**: if you're NOT using an [external Postgres server](docs/configuring-playbook-external-postgres.md) and have NOT forcefully kept the bridge on SQLite during [The big move to all-on-Postgres (potentially dangerous)](#the-big-move-to-all-on-postgres-potentially-dangerous), you will be automatically upgraded without manual intervention. All you need to do is send a `login` message to the Facebook bridge bot again.
+
+Whether this change requires your intervention depends mostly on:
+- whether you're using an [external Postgres server](docs/configuring-playbook-external-postgres.md). If yes, then [you need to do something](#upgrade-path-for-people-running-an-external-postgres-server).
+- or whether you've force-changed the bridge's database engine to SQLite (`matrix_mautrix_facebook_database_engine: 'sqlite'` in your `vars.yml`) some time in the past (likely during [The big move to all-on-Postgres (potentially dangerous)](#the-big-move-to-all-on-postgres-potentially-dangerous)).
+
+As already mentioned above, you most likely don't need to do anything. If you rerun the playbook and don't get an error, you've been automatically upgraded. Just send a `login` message to the Facebook bridge bot again. Otherwise, read below for a solution.
+
+### Upgrade path for people NOT running an external Postgres server (default for the playbook)
+
+If you're **not running an external Postgres server**, then this bridge either already works on Postgres for you, or you've intentionally kept it back on SQLite with custom configuration (`matrix_mautrix_facebook_database_engine: 'sqlite'` in your `vars.yml`) .
+
+Simply remove that custom configuration from your `vars.yml` file (if it's there) and re-run the playbook. It should upgrade you automatically.
+You'll need to send a `login` message to the Facebook bridge bot again.
+
+Alternatively, [you can stay on SQLite for a little longer](#staying-on-sqlite-for-a-little-longer-temporary-solution).
+
+### Upgrade path for people running an external Postgres server
+
+For people using the internal Postgres server (the default for the playbook):
+- we automatically create an additional `matrix_mautrix_facebook` Postgres database and credentials to access it
+- we automatically adjust the bridge's `matrix_mautrix_facebook_database_*` variables to point the bridge to that Postgres database
+- we use [pgloader](https://pgloader.io/) to automatically import the existing SQLite data for the bridge into the `matrix_mautrix_facebook` Postgres database
+
+If you are using an [external Postgres server](docs/configuring-playbook-external-postgres.md), unfortunately we currently can't do any of that for you.
+
+You have 3 ways to proceed:
+
+- contribute to the playbook to make this possible (difficult)
+- or, do the migration "steps" manually:
+  - stop the bridge (`systemctl stop matrix-mautrix-facebook`)
+  - create a new `matrix_mautrix_facebook` Postgres database for it
+  - run [pgloader](https://pgloader.io/) manually (we import this bridge's data using default settings and it works well)
+  - define `matrix_mautrix_facebook_database_*` variables in your `vars.yml` file (credentials, etc.) - you can find their defaults in `roles/matrix-mautrix-facebook/defaults/main.yml`
+  - switch the bridge to Postgres (`matrix_mautrix_facebook_database_engine: 'postgres'` in your `vars.yml` file)
+  - re-run the playbook (`--tags=setup-all,start`) and ensure the bridge works (`systemctl status matrix-mautrix-facebook` and `journalctl -fu matrix-mautrix-facebook`)
+  - send a `login` message to the Facebook bridge bot again
+- or, [stay on SQLite for a little longer (temporary solution)](#staying-on-sqlite-for-a-little-longer-temporary-solution)
+
+### Staying on SQLite for a little longer (temporary solution)
+
+To keep using this bridge with SQLite for a little longer (**not recommended**), use the following configuration in your `vars.yml` file:
+
+```yaml
+# Force-change the database engine to SQLite.
+matrix_mautrix_facebook_database_engine: 'sqlite'
+
+# Force-downgrade to the last bridge version which supported SQLite.
+matrix_mautrix_facebook_docker_image: "{{ matrix_mautrix_facebook_docker_image_name_prefix }}tulir/mautrix-facebook:da1b4ec596e334325a1589e70829dea46e73064b"
+```
+
+If you do this, keep in mind that **you can't run this forever**. This SQLite-supporting bridge version is not getting any updates and will break sooner or later. The playbook will also drop support for SQLite at some point in the future.
+
+
+# 2021-01-17
+
+## matrix-corporal goes 2.0
+
+[matrix-corporal v2 has been released](https://github.com/devture/matrix-corporal/releases/tag/2.0.0) and the playbook also supports it now.
+
+No manual intervention is required in the common case.
+
+The new [matrix-corporal](https://github.com/devture/matrix-corporal) version is also the first one to support Interactive Authentication. If you wish to enable that (hint: you should), you'll need to set up the [REST auth password provider](docs/configuring-playbook-rest-auth.md). There's more information in [our matrix-corporal docs](docs/configuring-playbook-matrix-corporal.md).
+
+
+# 2021-01-14
+
+## Moving from cronjobs to systemd timers
+
+We no longer use cronjobs for Let's Encrypt SSL renewal and `matrix-nginx-proxy`/`matrix-coturn` reloading. Instead, we've switched to systemd timers.
+
+The largest benefit of this is that we no longer require you to install a cron daemon, thus simplifying our install procedure.
+
+The playbook will migrate you from cronjobs to systemd timers automatically. This is just a heads up.
+
+
+# 2021-01-08
+
+## (Breaking Change) New SSL configuration
+
+SSL configuration (protocols, ciphers) can now be more easily controlled thanks to us making use of configuration presets.
+
+We define a few presets (old, intermediate, modern), following the [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/#server=nginx).
+
+A new variable `matrix_nginx_proxy_ssl_preset` controls which preset is used (defaults to `"intermediate"`).
+
+Compared to before, this changes nginx's `ssl_prefer_server_ciphers` to `off`  (used to default to `on`). It also add some more ciphers to the list, giving better performance on mobile devices, and removes some weak ciphers. More information in the [documentation](docs/configuring-playbook-nginx.md).
+
+To revert to the old behaviour, set the following variables:
+
+```yaml
+matrix_nginx_proxy_ssl_ciphers: "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"
+matrix_nginx_proxy_ssl_prefer_server_ciphers: "on"
+```
+
+Just like before, you can still use your own custom protocols by specifying them in `matrix_nginx_proxy_ssl_protocols`. Doing so overrides the values coming from the preset.
+
+
+# 2021-01-03
+
+## Signal bridging support via mautrix-signal
+
+Thanks to [laszabine](https://github.com/laszabine)'s efforts, the playbook now supports bridging to [Signal](https://www.signal.org/) via the [mautrix-signal](https://github.com/tulir/mautrix-signal) bridge. See our [Setting up Mautrix Signal bridging](docs/configuring-playbook-bridge-mautrix-signal.md) documentation page for getting started.
+
+If you had installed the mautrix-signal bridge while its Pull Request was still work-in-progress, you can migrate your data to the new and final setup by referring to [this comment](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/686#issuecomment-753510789).
+
+
+# 2020-12-23
+
+## The big move to all-on-Postgres (potentially dangerous)
+
+**TLDR**: all your bridges (and other services) will likely be auto-migrated from SQLite/nedb to Postgres, hopefully without trouble. You can opt-out (see how below), if too worried about breakage.
+
+Until now, we've only used Postgres as a database for Synapse. All other services (bridges, bots, etc.) were kept simple and used a file-based database (SQLite or nedb).
+
+Since [this huge pull request](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/740), **all of our services now use Postgres by default**. Thanks to [Johanna Dorothea Reichmann](https://github.com/jdreichmann) for starting the work on it and for providing great input!
+
+Moving all services to Postgres brings a few **benefits** to us:
+
+- **improved performance**
+- **improved compatibility**. Most bridges are deprecating SQLite/nedb support or offer less features when not on Postgres.
+- **easier backups**. It's still some effort to take a proper backup (Postgres dump + various files, keys), but a Postgres dump now takes you much further.
+- we're now **more prepared to introduce other services** that need a Postgres database - [Dendrite](https://github.com/matrix-org/dendrite), the [mautrix-signal](https://github.com/tulir/mautrix-signal) bridge (existing [pull request](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/686)), etc.
+
+### Key takeway
+
+- existing installations that use an [external Postgres](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook-external-postgres.md) server should be unaffected (they remain on SQLite/nedb for all services, except Synapse)
+
+- for existing installations which use our integrated Postgres database server (`matrix-postgres`, which is the default), **we automatically migrate data** from SQLite/nedb to Postgres and **archive the database files** (`something.db` -> `something.db.backup`), so you can restore them if you need to go back (see how below).
+
+### Opting-out of the Postgres migration
+
+This is a **very large and somewhat untested change** (potentially dangerous), so **if you're not feeling confident/experimental, opt-out** of it for now. Still, it's the new default and what we (and various bridges) will focus on going forward, so don't stick to old ways for too long.
+
+You can remain on SQLite/nedb (at least for now) by adding a variable like this to your `vars.yml` file for each service you use: `matrix_COMPONENT_database_engine: sqlite` (e.g. `matrix_mautrix_facebook_database_engine: sqlite`).
+
+Some services (like `appservice-irc` and `appservice-slack`) don't use SQLite, so use `nedb`, instead of `sqlite` for them.
+
+### Going back to SQLite/nedb if things went wrong
+
+If you went with the Postgres migration and it went badly for you (some bridge not working as expected or not working at all), do this:
+
+- stop all services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
+- SSH into the server and rename the old database files (`something.db.backup` -> `something.db`). Example: `mv /matrix/mautrix-facebook/data/mautrix-facebook.db.backup /matrix/mautrix-facebook/data/mautrix-facebook.db`
+- switch the affected service back to SQLite (e.g. `matrix_mautrix_facebook_database_engine: sqlite`). Some services (like `appservice-irc` and `appservice-slack`) don't use SQLite, so use `nedb`, instead of `sqlite` for them.
+- re-run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`)
+- [get in touch](README.md#support) with us
+
+# 2020-12-11
+
+## synapse-janitor support removed
+
+We've removed support for the unmaintained [synapse-janitor](https://github.com/xwiki-labs/synapse_scripts) script. There's been past reports of it corrupting the Synapse database. Since there hasn't been any new development on it and it doesn't seem too useful nowadays, there's no point in including it in the playbook.
+
+If you need to clean up or compact your database, consider using the Synapse Admin APIs directly. See our [Synapse maintenance](docs/maintenance-synapse.md) and [Postgres maintenance](docs/maintenance-postgres.md) documentation pages for more details.
+
+
+## Docker 20.10 is here
+
+(No need to do anything special in relation to this. Just something to keep in mind)
+
+Docker 20.10 got released recently and your server will likely get it the next time you update.
+
+This is the first major Docker update in a long time and it packs a lot of changes.
+Some of them introduced some breakage for us initially (see [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/commit/d08b27784f222effcbce2abf924bf07bbe0893be) and [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/commit/7593d969e316cc0144bce378a5be58c76c2c37ee)), but it should be all good now.
+
+
+# 2020-12-08
+
+## openid APIs exposed by default on the federation port when federation disabled
+
+We've changed some defaults. People running with our default configuration (federation enabled), are not affected at all.
+
+If you are running an unfederated server (`matrix_synapse_federation_enabled: false`), this may be of interest to you.
+
+When federation is disabled, but ma1sd or Dimension are enabled, we'll now expose the `openid` APIs on the federation port.
+These APIs are necessary for some ma1sd features to work. If you'd like to prevent this, you can: `matrix_synapse_federation_port_openid_resource_required: false`.
+
+
+# 2020-11-27
+
+## Recent Jitsi updates may require configuration changes
+
+We've recently [updated from Jitsi build 4857 to build 5142](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/719), which brings a lot of configuration changes.
+
+**If you use our default Jitsi settings, you won't have to do anything.**
+
+People who have [fine-tuned Jitsi](docs/configuring-playbook-jitsi.md#optional-fine-tune-jitsi) may find that some options got renamed now, others are gone and yet others still need to be defined in another way.
+
+The next time you run the playbook [installation](docs/installing.md) command, our validation logic will tell you if you're using some variables like that and will recommend a migration path for each one.
+
+Additionally, we've recently disabled transcriptions (`matrix_jitsi_enable_transcriptions: false`) and recording (`matrix_jitsi_enable_recording: false`) by default. These features did not work anyway, because we don't install the required dependencies for them (Jigasi and Jibri, respectively). If you've been somehow pointing your Jitsi installation to some manually installed Jigasi/Jibri service, you may need to toggle these flags back to enabled to have transcriptions and recordings working.
+
+
+# 2020-11-23
+
+## Breaking change matrix-sms-bridge
+
+Because of many problems using gammu as SMS provider, matrix-sms-bridge now uses (https://github.com/RebekkaMa/android-sms-gateway-server) by default. See (the docs)[./docs/configuring-playbook-bridge-matrix-bridge-sms.md] which new vars you need to add.
+
+If you are using this playbook to deploy matrix-sms-bridge and still really want to use gammu as SMS provider, we could possibly add support for both android-sms-gateway-server and gammu.
+
+# 2020-11-13
+
+## Breaking change matrix-sms-bridge
+
+The new version of [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) changed its database from neo4j to h2. You need to sync the bridge at the first start. Note that this only will sync rooms where the @smsbot:yourServer is member. For rooms without @smsbot:yourServer you need to kick and invite the telephone number **or** invite @smsbot:yourServer.
+
+1. Add the following to your `vars.yml` file: `matrix_sms_bridge_container_extra_arguments=['--env SPRING_PROFILES_ACTIVE=initialsync']`
+2. Login to your host shell and remove old systemd file from your host: `rm /etc/systemd/system/matrix-sms-bridge-database.service`
+2. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-sms-bridge,start`
+3. Login to your host shell and check the logs with `journalctl -u matrix-sms-bridge` until the sync finished.
+4. Remove the var from the first step.
+5. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`.
+
+# 2020-11-10
+
+## Dynamic DNS support
+
+Thanks to [Scott Crossen](https://github.com/scottcrossen), the playbook can now manage Dynamic DNS for you using [ddclient](https://ddclient.net/).
+
+To learn more, follow our [Dynamic DNS docs page](docs/configuring-playbook-dynamic-dns.md).
+
+
+# 2020-10-28
+
+## (Compatibility Break) https://matrix.DOMAIN/ now redirects to https://element.DOMAIN/
+
+Until now, we used to serve a static page coming from Synapse at `https://matrix.DOMAIN/`. This page was not very useful to anyone.
+
+Since `matrix.DOMAIN` may be accessed by regular users in certain conditions, it's probably better to redirect them to a better place (e.g. to the [Element](docs/configuring-playbook-client-element.md) client).
+
+If Element is installed (`matrix_client_element_enabled: true`, which it is by default), we now redirect people to it, instead of showing them a Synapse static page.
+
+If you'd like to control where the redirect goes, use the `matrix_nginx_proxy_proxy_matrix_client_redirect_root_uri_to_domain` variable.
+To restore the old behavior of not redirecting anywhere and serving the Synapse static page, set it to an empty value (`matrix_nginx_proxy_proxy_matrix_client_redirect_root_uri_to_domain: ""`).
+
+
+# 2020-10-26
+
+## (Compatibility Break) /_synapse/admin is no longer publicly exposed by default
+
+We used to expose the Synapse Admin APIs publicly (at `https://matrix.DOMAIN/_synapse/admin`).
+These APIs require authentication with a valid access token, so it's not that big a deal to expose them.
+
+However, following [official Synapse's reverse-proxying recommendations](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints), we're no longer exposing `/_synapse/admin` by default.
+
+If you'd like to restore restore the old behavior and expose `/_synapse/admin` publicly, you can use the following configuration (in your `vars.yml`):
+
+```yaml
+matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true
+```
+
+
+# 2020-10-02
+
+## Minimum Ansible version raised to v2.7.0
+
+We were claiming to support [Ansible](https://www.ansible.com/) v2.5.2 and higher, but issues like [#662](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/662) demonstrate that we need at least v2.7.0.
+
+If you've been using the playbook without getting any errors until now, you're probably on a version higher than that already (or you're not using the `matrix-ma1sd` and `matrix-client-element` roles).
+
+Our [Ansible docs page](docs/ansible.md) contains information on how to run a more up-to-date version of Ansible.
+
+
+# 2020-10-01
+
+## Postgres 13 support
+
+The playbook now installs [Postgres 13](https://www.postgresql.org/about/news/postgresql-13-released-2077/) by default.
+
+If you have have an existing setup, it's likely running on an older Postgres version (9.x, 10.x, 11.x or 12.x). You can easily upgrade by following the [upgrading PostgreSQL guide](docs/maintenance-postgres.md#upgrading-postgresql).
+
+# 2020-09-01
+
+## matrix-registration support
+
+The playbook can now help you set up [matrix-registration](https://github.com/ZerataX/matrix-registration) - an application that lets you keep your Matrix server's registration private, but still allow certain users (those having a unique registration link) to register by themselves.
+
+See our [Setting up matrix-registration](docs/configuring-playbook-matrix-registration.md) documentation page to get started.
+
+
+# 2020-08-21
+
+## rust-synapse-compress-state support
+
+The playbook can now help you use [rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state) to compress the state groups in your Synapse database.
+
+See our [Compressing state with rust-synapse-compress-state](docs/maintenance-synapse.md#compressing-state-with-rust-synapse-compress-state) documentation page to get started.
+
+
+# 2020-07-22
+
+## Synapse Admin support
+
+The playbook can now help you set up [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin).
+
+See our [Setting up Synapse Admin](docs/configuring-playbook-synapse-admin.md) documentation to get started.
+
+
+# 2020-07-20
+
+## matrix-reminder-bot support
+
+The playbook can now help you set up [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot).
+
+See our [Setting up matrix-reminder-bot](docs/configuring-playbook-bot-matrix-reminder-bot.md) documentation to get started.
+
+
+# 2020-07-17
+
+## (Compatibility Break) Riot is now Element
+
+As per the official announcement, [Riot has been rebraned to Element](https://element.io/blog/welcome-to-element/).
+
+The playbook follows suit. Existing installations have a few options for how to handle this.
+
+See our [Migrating to Element](docs/configuring-playbook-riot-web.md#migrating-to-element) documentation page for more details.
+
+
+# 2020-07-03
+
+## Steam bridging support via mx-puppet-steam
+
+Thanks to [Hugues Morisset](https://github.com/izissise)'s efforts, the playbook now supports bridging to [Steam](https://steamapp.com/) via the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge. See our [Setting up MX Puppet Steam bridging](docs/configuring-playbook-bridge-mx-puppet-steam.md) documentation page for getting started.
+
+
+# 2020-07-01
+
+## Discord bridging support via mx-puppet-discord
+
+Thanks to [Hugues Morisset](https://github.com/izissise)'s efforts, the playbook now supports bridging to [Discord](https://discordapp.com/) via the [mx-puppet-discord](https://github.com/Sorunome/mx-puppet-discord) bridge. See our [Setting up MX Puppet Discord bridging](docs/configuring-playbook-bridge-mx-puppet-discord.md) documentation page for getting started.
+
+**Note**: this is a new Discord bridge. The playbook still retains Discord bridging via [matrix-appservice-discord](docs/configuring-playbook-bridge-appservice-discord.md). You're free too use the bridge that serves you better, or even both (for different users and use-cases).
+
+
+# 2020-06-30
+
+## Instagram and Twitter bridging support
+
+Thanks to [Johanna Dorothea Reichmann](https://github.com/jdreichmann)'s efforts, the playbook now supports bridging to [Instagram](https://www.instagram.com/) via the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge. See our [Setting up MX Puppet Instagram bridging](docs/configuring-playbook-bridge-mx-puppet-instagram.md) documentation page for getting started.
+
+Thanks to [Tulir Asokan](https://github.com/tulir)'s efforts, the playbook now supports bridging to [Twitter](https://twitter.com/) via the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge. See our [Setting up MX Puppet Twitter bridging](docs/configuring-playbook-bridge-mx-puppet-twitter.md) documentation page for getting started.
+
+
+# 2020-06-28
+
+## (Post Mortem / fixed Security Issue) Re-enabling User Directory search powered by the ma1sd Identity Server
+
+User Directory search requests used to go to the ma1sd identity server by default, which queried its own stores and the Synapse database.
+
+ma1sd's [security issue](https://github.com/ma1uta/ma1sd/issues/44) has been fixed in version `2.4.0`, with [this commit](ma1uta/ma1sd@2bb5a734d11662b06471113cf3d6b4cee5e33a85). `ma1sd 2.4.0` is now the default version for this playbook. For more information on what happened, please check the mentioned issue.
+
+We are re-enabling user directory search with this update. Those who would like to keep it disabled can use this configuration: `matrix_nginx_proxy_proxy_matrix_user_directory_search_enabled: false`
+
+As always, re-running the playbook is enough to get the updated bits.
+
 # 2020-06-11
 
 ## SMS bridging requires db reset
@@ -12,7 +805,7 @@ To reuse your existing rooms, invite `@smsbot:yourServer` to the room or write a
 
 Thanks to [benkuly](https://github.com/benkuly)'s efforts, the playbook now supports bridging to SMS (with one telephone number only) via [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge).
 
-See our [Setting up Matrix SMS bridging](docs/configuring-playbook-matrix-bridge-sms.md) documentation page for getting started.
+See our [Setting up Matrix SMS bridging](docs/configuring-playbook-bridge-matrix-bridge-sms.md) documentation page for getting started.
 
 
 # 2020-05-19

README.md

@@ -1,26 +1,37 @@
+[![Support room on Matrix](https://img.shields.io/matrix/matrix-docker-ansible-deploy:devture.com.svg?label=%23matrix-docker-ansible-deploy%3Adevture.com&logo=matrix&style=for-the-badge&server_fqdn=matrix.devture.com)](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate)
+
 # Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker
 
 ## Purpose
 
-This Ansible playbook is meant to easily let you run your own [Matrix](http://matrix.org/) homeserver.
+This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#supported-services) related to that.
 
-That is, it lets you join the Matrix network with your own `@<username>:<your-domain>` identifier, all hosted on your own server.
+That is, it lets you join the Matrix network using your own `@<username>:<your-domain>` identifier, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
+
+We run all services in [Docker](https://www.docker.com/) containers (see [the container images we use](docs/container-images.md)), which lets us have a predictable and up-to-date setup, across multiple supported distros (see [prerequisites](docs/prerequisites.md)) and [architectures](docs/alternative-architectures.md) (x86/amd64 being recommended).
+
+[Installation](docs/README.md) (upgrades) and some maintenance tasks are automated using [Ansible](https://www.ansible.com/) (see [our Ansible guide](docs/ansible.md)).
+
+
+## Supported services
 
 Using this playbook, you can get the following services configured on your server:
 
 - (optional, default) a [Synapse](https://github.com/matrix-org/synapse) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network
 
+- (optional) a [Dendrite](https://github.com/matrix-org/dendrite) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse.
+
 - (optional) [Amazon S3](https://aws.amazon.com/s3/) storage for Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys)
 
 - (optional, default) [PostgreSQL](https://www.postgresql.org/) database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible.
 
 - (optional, default) a [coturn](https://github.com/coturn/coturn) STUN/TURN server for WebRTC audio/video calls
 
-- (optional, default) free [Let's Encrypt](https://letsencrypt.org/) SSL certificate, which secures the connection to the Synapse server and the Riot web UI
+- (optional, default) free [Let's Encrypt](https://letsencrypt.org/) SSL certificate, which secures the connection to the Synapse server and the Element web UI
 
-- (optional, default) a [Riot](https://riot.im/) web UI, which is configured to connect to your own Synapse server by default
+- (optional, default) an [Element](https://app.element.io/) ([formerly Riot](https://element.io/previously-riot)) web UI, which is configured to connect to your own Synapse server by default
 
-- (optional, default) an [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
+- (optional) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
 
 - (optional, default) an [Exim](https://www.exim.org/) mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server)
 
@@ -36,13 +47,23 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional, advanced) the [Matrix Corporal](https://github.com/devture/matrix-corporal) reconciliator and gateway for a managed Matrix server
 
-- (optional) the [mautrix-telegram](https://github.com/tulir/mautrix-telegram) bridge for bridging your Matrix server to [Telegram](https://telegram.org/)
+- (optional) the [mautrix-telegram](https://github.com/mautrix/telegram) bridge for bridging your Matrix server to [Telegram](https://telegram.org/)
 
-- (optional) the [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) bridge for bridging your Matrix server to [Whatsapp](https://www.whatsapp.com/)
+- (optional) the [mautrix-whatsapp](https://github.com/mautrix/whatsapp) bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/)
 
-- (optional) the [mautrix-facebook](https://github.com/tulir/mautrix-facebook) bridge for bridging your Matrix server to [Facebook](https://facebook.com/)
+- (optional) the [mautrix-facebook](https://github.com/mautrix/facebook) bridge for bridging your Matrix server to [Facebook](https://facebook.com/)
 
-- (optional) the [mautrix-hangouts](https://github.com/tulir/mautrix-hangouts) bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts)
+- (optional) the [mautrix-twitter](https://github.com/mautrix/twitter) bridge for bridging your Matrix server to [Twitter](https://twitter.com/)
+
+- (optional) the [mautrix-hangouts](https://github.com/mautrix/hangouts) bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts)
+
+- (optional) the [mautrix-googlechat](https://github.com/mautrix/googlechat) bridge for bridging your Matrix server to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat)
+
+- (optional) the [mautrix-instagram](https://github.com/mautrix/instagram) bridge for bridging your Matrix server to [Instagram](https://instagram.com/)
+
+- (optional) the [mautrix-signal](https://github.com/mautrix/signal) bridge for bridging your Matrix server to [Signal](https://www.signal.org/)
+
+- (optional) the [beeper-linkedin](https://gitlab.com/beeper/linkedin) bridge for bridging your Matrix server to [LinkedIn](https://www.linkedin.com/)
 
 - (optional) the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat)
 
@@ -52,46 +73,65 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) the [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.)
 
-- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS
+- (optional) the [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) bridge for bridging Matrix to generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular
 
-- (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms
+- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
 
-- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients
+- (optional) the [Heisenbridge](https://github.com/hifi/heisenbridge) for bridging your Matrix server to IRC bouncer-style - see [docs/configuring-playbook-bridge-heisenbridge.md](docs/configuring-playbook-bridge-heisenbridge.md) for setup documentation
 
-- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform
+- (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
 
-Basically, this playbook aims to get you up-and-running with all the basic necessities around Matrix, without you having to do anything else.
+- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
+
+- (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
+
+- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
+
+- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
+
+- (optional) the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
+
+- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
+
+- (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
+
+- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
+
+- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
+
+- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
+
+- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation
+
+- (optional) [honoroit](https://gitlab.com/etke.cc/honoroit) helpdesk bot - see [docs/configuring-playbook-bot-honoroit.md](docs/configuring-playbook-bot-honoroit.md) for setup documentation
+
+- (optional) [Go-NEB](https://github.com/matrix-org/go-neb) multi functional bot written in Go - see [docs/configuring-playbook-bot-go-neb.md](docs/configuring-playbook-bot-go-neb.md) for setup documentation
+
+- (optional) [Mjolnir](https://github.com/matrix-org/mjolnir), a moderation tool for Matrix - see [docs/configuring-playbook-bot-mjolnir.md](docs/configuring-playbook-bot-mjolnir.md) for setup documentation
+
+- (optional) [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), a web UI tool for administrating users and rooms on your Matrix server - see [docs/configuring-playbook-synapse-admin.md](docs/configuring-playbook-synapse-admin.md) for setup documentation
+
+- (optional) [matrix-registration](https://github.com/ZerataX/matrix-registration), a simple python application to have a token based matrix registration - see [docs/configuring-playbook-matrix-registration.md](docs/configuring-playbook-matrix-registration.md) for setup documentation
+
+- (optional) the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI - see [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) for setup documentation
+
+- (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation
+
+- (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation
+
+- (optional) the [Cinny](https://github.com/ajbura/cinny) web client - see [docs/configuring-playbook-client-cinny.md](docs/configuring-playbook-client-cinny.md) for setup documentation
+
+- (optional) the [Borg](https://borgbackup.org) backup - see [docs/configuring-playbook-backup-borg.md](docs/configuring-playbook-backup-borg.md) for setup documentation
+
+- (optional) the [Buscarron](https://gitlab.com/etke.cc/buscarron) bot - see [docs/configuring-playbook-bot-buscarron.md](docs/configuring-playbook-bot-buscarron.md) for setup documentation
+
+Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
 
 **Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.
 Sticking with the defaults (which install a subset of the above components) is the best choice, especially for a new installation.
 You can always re-run the playbook later to add or remove components.
 
 
-## What's different about this Ansible playbook?
-
-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 re-ran many times** without causing trouble
-
-- works on various distros: **CentOS** (7.0+), Debian-based distributions (**Debian** 9/Stretch+, **Ubuntu** 16.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](docs/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](#docker-images-used-by-this-playbook))
-
-- 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)
-
-
 ## Installation
 
 To configure and install Matrix on your own server, follow the [README in the docs/ directory](docs/README.md).
@@ -104,76 +144,15 @@ This playbook evolves over time, sometimes with backward-incompatible changes.
 When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
 
 
-## Docker images used by this playbook
-
-This playbook sets up your server using the following Docker images:
-
-- [matrixdotorg/synapse](https://hub.docker.com/r/matrixdotorg/synapse/) - the official [Synapse](https://github.com/matrix-org/synapse) Matrix homeserver (optional)
-
-- [instrumentisto/coturn](https://hub.docker.com/r/instrumentisto/coturn/) - the [Coturn](https://github.com/coturn/coturn) STUN/TURN server (optional)
-
-- [vectorim/riot-web](https://hub.docker.com/r/vectorim/riot-web/) - the [Riot.im](https://about.riot.im/) web client (optional)
-
-- [ma1uta/ma1sd](https://hub.docker.com/r/ma1uta/ma1sd/) - the [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server (optional)
-
-- [postgres](https://hub.docker.com/_/postgres/) - the [Postgres](https://www.postgresql.org/) database server (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)
-
-- [devture/exim-relay](https://hub.docker.com/r/devture/exim-relay/) - the [Exim](https://www.exim.org/) email server (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)
-
-- [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)
-
-- [tulir/mautrix-telegram](https://hub.docker.com/r/tulir/mautrix-telegram/) - the [mautrix-telegram](https://github.com/tulir/mautrix-telegram) bridge to [Telegram](https://telegram.org/) (optional)
-
-- [tulir/mautrix-whatsapp](https://hub.docker.com/r/tulir/mautrix-whatsapp/) - the [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) bridge to [Whatsapp](https://www.whatsapp.com/) (optional)
-
-- [tulir/mautrix-facebook](https://hub.docker.com/r/tulir/mautrix-facebook/) - the [mautrix-facebook](https://github.com/tulir/mautrix-facebook) bridge to [Facebook](https://facebook.com/) (optional)
-
-- [tulir/mautrix-hangouts](https://hub.docker.com/r/tulir/mautrix-hangouts/) - the [mautrix-hangouts](https://github.com/tulir/mautrix-hangouts) bridge to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts) (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-brdige](https://github.com/benkuly/matrix-sms-bridge) (optional)
-
-- [sorunome/mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) - the [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) bridge to [Skype](https:/www.skype.com) (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)
-
-- [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)
-
-
-## Deficiencies
-
-This Ansible playbook can be improved in the following ways:
-
-- setting up automatic backups to one or more storage providers
-
-
 ## Support
 
 - Matrix room: [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)
 
-- IRC channel: `#matrix-docker-ansible-deploy` on the [Freenode](https://freenode.net/) IRC network (irc.freenode.net)
+- IRC channel: `#matrix-docker-ansible-deploy` on the [Libera Chat](https://libera.chat/) IRC network (irc.libera.chat:6697)
 
-- Github issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
+- GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
+
+
+## Services by the community
+
+- [etke.cc](https://etke.cc) - matrix-docker-ansible-deploy and system stuff "as a service". That service will create your matrix homeserver on your domain and server (doesn't matter if it's cloud provider or on an old laptop in the corner of your room), (optional) maintains it (server's system updates, cleanup, security adjustments, tuning, etc.; matrix homeserver updates & maintenance) and (optional) provide full-featured email service for your domain

ansible.cfg

@@ -1,5 +1,11 @@
 [defaults]
+
+vault_password_file = gpg/open_vault.sh
+
 retry_files_enabled = False
+stdout_callback = yaml
+
+inventory = inventory/hosts
 
 [connection]
 pipelining = True

collections/requirements.yml

@@ -0,0 +1,4 @@
+---
+collections:
+  - name: community.general
+  - name: community.docker

docs/README.md

@@ -1,6 +1,8 @@
 # Table of Contents
 
-- [Prerequisites](prerequisites.md)
+- [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)
 
@@ -10,6 +12,14 @@
 
 - [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)

docs/alternative-architectures.md

@@ -1,8 +1,8 @@
 # Alternative architectures
 
-As stated in the [Prerequisites](prerequisites.md), currently only x86_64 is supported. However, it is possible to set the target architecture, and some tools can be built on the host or other measures can be used.
+As stated in the [Prerequisites](prerequisites.md), currently only `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.yaml` file:
+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>
@@ -13,7 +13,7 @@ Currently supported architectures are the following:
 - `arm64`
 - `arm32`
 
-so for the Raspberry Pi, the following should be in your `vars.yaml` file:
+so for the Raspberry Pi, the following should be in your `vars.yml` file:
 
 ```yaml
 matrix_architecture: "arm32"
@@ -21,9 +21,6 @@ matrix_architecture: "arm32"
 
 ## Implementation details
 
-This subsection is used for a reminder, how the different roles implement architecture differences. This is **not** aimed at the users, so one does not have to do anything based on this subsection.
+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).
 
-On most roles [self-building](self-building.md) is used if the architecture is not `amd64`, however there are some special cases:
-- `matrix-bridge-mautrix-facebook`: there is a pre-built Docker image for `arm64` as well
-- `matrix-bridge-mautrix-hangouts`: there is a pre-built Docker image for `arm64` as well
-- `matrix-nginx-proxy`: Certbot has a pre-built Docker image for both `arm32` and `arm64`, however tagging is used, which requires special handling.
+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.

docs/ansible.md

@@ -9,7 +9,9 @@ If your local computer cannot run Ansible, you can also run Ansible on some serv
 
 ## Supported Ansible versions
 
-Ansible 2.5.2 or newer is required.
+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
@@ -49,7 +51,7 @@ docker run -it --rm \
 -v `pwd`:/work \
 -v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
 --entrypoint=/bin/sh \
-devture/ansible:2.9.9-r0
+docker.io/devture/ansible:2.11.6-r1
 ```
 
 The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`).

docs/configuring-captcha.md

@@ -0,0 +1,23 @@
+(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'
+```

docs/configuring-dns.md

@@ -15,38 +15,62 @@ As we discuss in [Server Delegation](howto-server-delegation.md), there are 2 di
 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.
 
-
-## General outline of DNS settings you need to do
+## DNS settings for services enabled by default
 
 | Type  | Host                         | Priority | Weight | Port | Target                 |
 | ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
 | A     | `matrix`                     | -        | -      | -    | `matrix-server-IP`     |
-| CNAME | `riot`                       | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `dimension` (*)              | -        | -      | -    | `matrix.<your-domain>` |
-| CNAME | `jitsi` (*)                  | -        | -      | -    | `matrix.<your-domain>` |
+| 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.
+
+## DNS settings for optional services/features
+
+| Type  | Host                         | Priority | Weight | Port | Target                 |
+| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
 | SRV   | `_matrix-identity._tcp`      | 10       | 0      | 443  | `matrix.<your-domain>` |
-
-
-DNS records marked with `(*)` above are optional. They refer to services that will not be installed by default (see the section below). If you won't be installing these services, feel free to skip creating these DNS records.
-
+| CNAME | `dimension`                  | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `jitsi`                      | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `stats`                      | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `goneb`                      | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `sygnal`                     | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `hydrogen`                   | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `cinny`                      | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `buscarron`                  | -        | -      | -    | `matrix.<your-domain>` |
 
 ## Subdomains setup
 
-As the table above illustrates, you need to create 2 subdomains (`matrix.<your-domain>` and `riot.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
+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 `riot.<your-domain>` subdomain is necessary, because this playbook installs the Riot web client for you.
-If you'd rather instruct the playbook not to install Riot (`matrix_riot_web_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `riot.<your-domain>` DNS record.
+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 `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.<your-domain>` DNS record.
+
+The `cinny.<your-domain>` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up cinny, feel free to skip the `cinny.<your-domain>` DNS record.
+
+The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etke.cc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.<your-domain>` DNS record.
 
 ## `_matrix-identity._tcp` SRV record setup
 
-To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook installs for you) be authoritative for your domain name, set up one more SRV record that looks like this:
+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.
 
-When you're done with the DNS configuration and ready to proceed, continue with [Configuring this Ansible playbook](configuring-playbook.md).
+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).

docs/configuring-playbook-backup-borg.md

@@ -0,0 +1,69 @@
+# 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: |
+	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`
+* 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
+
+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
+```

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

@@ -14,7 +14,7 @@ Usually, there are 2 options:
 
 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 **and use the following configuration**:
+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

docs/configuring-playbook-bot-buscarron.md

@@ -0,0 +1,75 @@
+# 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
+    extensions: [] # (optional) list of form extensions (not used yet)
+
+matrix_bot_buscarron_spam_hosts: [] # (optional) list of email domains/hosts that should be rejected automatically
+matrix_bot_buscarron_spam_emails: [] # (optional) list of email addresses that should be rejected automatically
+```
+
+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).

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

@@ -0,0 +1,226 @@
+# 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
+```
+
+
+## Getting an access token
+
+If you use curl, you can get an access token like this:
+
+```
+curl -X POST --header 'Content-Type: application/json' -d '{
+    "identifier": { "type": "m.id.user", "user": "bot.go-neb" },
+    "password": "a strong password",
+    "type": "m.login.password"
+}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
+```
+
+Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token), but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start).
+
+
+## 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).

docs/configuring-playbook-bot-honoroit.md

@@ -0,0 +1,55 @@
+# 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).

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

@@ -0,0 +1,72 @@
+# 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. As you created an admin user for the
+bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
+(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
+You can expand "Access token" to copy it.
+
+![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
+
+**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
+
+## 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 `YOUR_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).

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

@@ -0,0 +1,59 @@
+# 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).

docs/configuring-playbook-bot-mjolnir.md

@@ -0,0 +1,132 @@
+# 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
+
+If you use curl, you can get an access token like this:
+
+```
+curl -X POST --header 'Content-Type: application/json' -d '{
+    "identifier": { "type": "m.id.user", "user": "bot.mjolnir" },
+    "password": "PASSWORD_FOR_THE_BOT",
+    "type": "m.login.password"
+}' 'https://matrix.DOMAIN/_matrix/client/r0/login'
+```
+
+Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token).
+
+
+## 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. [Currently there is no Synapse config option for this](https://github.com/matrix-org/synapse/issues/6286) so you have to manually edit the Synapse database. Manually editing the Synapse database is rarely a good idea but in this case it is required. Please ask for help if you are uncomfortable with these steps.
+
+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
+```

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

@@ -1,5 +1,7 @@
 # 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) bridge 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.
@@ -20,31 +22,56 @@ matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
 matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
 ```
 
-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.
-5. Retrieve Discord invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`)
-6. Invite the Bot to Discord servers you wish to bridge. Administrator permission is recommended.
-7. 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: `discordapp.com/channels/guild_id/channel_id`. Once you have figured out the appropriate room addrss, you can join by doing `/join #_discord_guildid_channelid` in your Matrix client.
+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)
 
-## Getting Administrator access in a room
+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](#adjusting-room-access-privileges) or do various other things (change the room name subsequently, etc.), you'd wish to become an Administrator.
+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'
 ```
-docker exec -it matrix-appservice-discord /bin/sh -c 'cp /build/tools/adminme.js /tmp/adminme.js && cp /cfg/registration.yaml /tmp/discord-registration.yaml && cd /tmp && node /tmp/adminme.js -c /cfg/config.yaml -r "!ROOM_ID:SERVER" -u "@USER:SERVER" -p 100'
-```
-
-
-## Adjusting room access privileges
-
-All rooms created by the bridge are **listed publicly** in your server's directory and **joinable by everyone** by default.
-
-To get more control of them, [make yourself a room Administrator](#getting-administrator-access-in-a-room) first.
-
-You can then unlist the room from the directory and change the join rules.

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

@@ -1,6 +1,8 @@
 # Setting up Appservice IRC (optional)
 
-The playbook can install and configure [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) for you.
+**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.
 

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

@@ -1,5 +1,7 @@
 # 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.
@@ -9,7 +11,7 @@ See the project's [documentation](https://github.com/matrix-org/matrix-appservic
 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 Riot by making a message, opening the options for that message and choosing "view source". The
+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:
 
@@ -27,7 +29,7 @@ matrix_appservice_slack_control_room_id: "Your matrix admin room id"
 
 Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
 
-5. Create a new Slack App [here](https://api.slack.com/apps).
+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).
 
@@ -106,5 +108,5 @@ 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 
+then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link
 your room multiple times without unlinking it after each failed attempt.

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

@@ -2,6 +2,8 @@
 
 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:
@@ -45,7 +47,7 @@ matrix_appservice_webhooks_log_level: '<log_level>'
     "text": "Hello world!",
     "format": "plain",
     "displayName": "My Cool Webhook",
-    "avatarUrl": "http://i.imgur.com/IDOBtEJ.png"
+    "avatar_url": "http://i.imgur.com/IDOBtEJ.png"
 }
 ```
 
@@ -57,7 +59,7 @@ curl --header "Content-Type: application/json" \
 "text": "Hello world!",
 "format": "plain",
 "displayName": "My Cool Webhook",
-"avatarUrl": "http://i.imgur.com/IDOBtEJ.png"
+"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
 }' \
 <the link you've gotten in 5.>
 ```

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

@@ -0,0 +1,59 @@
+# Setting up Beeper Linkedin (optional)
+
+The playbook can install and configure [beeper-linkedin](https://gitlab.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges
+
+See the project's [documentation](https://gitlab.com/beeper/linkedin/-/blob/master/README.md) to learn what it does and why it might be useful to you.
+
+```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.

docs/configuring-playbook-bridge-heisenbridge.md

@@ -0,0 +1,38 @@
+# 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.

docs/configuring-playbook-bridge-hookshot.md

@@ -0,0 +1,70 @@
+# 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/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/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`.
+5. Refer to [Hookshot's official instructions](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) to start using the bridge. **Important:** Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](urls-for-bridges-setup) below.
+
+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.
+
+### 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 | `/hookshot/metrics/` (on `stats.` subdomain) | `matrix_hookshot_metrics_endpoint` | 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
+
+If metrics are enabled, they will be automatically available in the builtin Prometheus and Grafana, but you need to set up your own Dashboard for now. If additionally metrics proxying for use with external Prometheus is enabled (`matrix_nginx_proxy_proxy_synapse_metrics`), hookshot metrics will also be available (at `matrix_hookshot_metrics_endpoint`, default `/hookshot/metrics`, on the stats subdomain) and with the same password. See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).
+
+### 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_'`).

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

@@ -0,0 +1,37 @@
+# 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.

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

@@ -1,17 +1,38 @@
 # Setting up Mautrix Facebook (optional)
 
-The playbook can install and configure [mautrix-facebook](https://github.com/tulir/mautrix-facebook) for you.
+The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you.
 
-See the project's [documentation](https://github.com/tulir/mautrix-facebook/wiki#usage) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/mautrix/facebook/blob/master/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:YOUR_DOMAIN': admin
+```
+
+You may wish to look at `roles/matrix-bridge-mautrix-facebook/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://github.com/tulir/mautrix-facebook/wiki/Authentication#double-puppeting) (hint: you most likely do), you have 2 ways of going about it.
+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
 
@@ -42,40 +63,13 @@ https://matrix.DOMAIN/_matrix/client/r0/login
 
 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 YOUR_FACEBOOK_PASSWORD` 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://github.com/tulir/mautrix-facebook/wiki/Authentication).
+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.
 
 
-## Set up community-grouping
-
-This is an **optional feature** that you may wish to enable.
-
-The Facebook bridge can create a Matrix community for you, which would contain all your chats and contacts.
-
-For this to work, the bridge's bot needs to have permissions to create communities (also referred to as groups).
-Since the bot is a non-admin user, you need to enable such group-creation for non-privileged users in [Synapse's settings](configuring-playbook-synapse.md).
-
-Here's an example configuration:
-
-```yaml
-matrix_synapse_configuration_extension_yaml: |
-  enable_group_creation: true
-  group_creation_prefix: "unofficial/"
-
-matrix_mautrix_facebook_configuration_extension_yaml: |
-  bridge:
-    community_template: "unofficial/facebook_{localpart}={server}"
-```
-
-Once the bridge is restarted, it would create a community and invite you to it. You need to accept the community invitation manually.
-If you don't see all your contacts, you may wish to send a `sync` message to the bot.
-
-
 ## Troubleshooting
 
 ### Facebook rejecting login attempts and forcing you to change password

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

@@ -0,0 +1,58 @@
+# 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. You can use the following command:
+
+```
+curl \
+--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-googlechat", "initial_device_display_name": "Mautrix-googlechat"}' \
+https://matrix.DOMAIN/_matrix/client/r0/login
+```
+
+- 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.
+

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

@@ -1,8 +1,10 @@
+# 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/tulir/mautrix-hangouts) for you.
+The playbook can install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts) for you.
 
-See the project's [documentation](https://github.com/tulir/mautrix-hangouts/wiki#usage) to learn what it does and why it might be useful to 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:
 
@@ -14,7 +16,7 @@ matrix_mautrix_hangouts_enabled: true
 
 ## Set up Double Puppeting
 
-If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-hangouts/wiki/Authentication#double-puppeting) (hint: you most likely do), you have 2 ways of going about it.
+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
 
@@ -52,7 +54,7 @@ Automatic login may not work. If it does not, reload the page and select the "Ma
 
 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://github.com/tulir/mautrix-hangouts/wiki/Authentication).
+You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/hangouts/authentication.html).
 
 After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
 

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

@@ -0,0 +1,17 @@
+# 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
+```
+
+## 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).

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

@@ -0,0 +1,91 @@
+# 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. You can use the following command:
+
+```
+curl \
+--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Signal", "initial_device_display_name": "Mautrix-Signal"}' \
+https://matrix.DOMAIN/_matrix/client/r0/login
+```
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature
+
+
+## Usage
+
+You then need to start a chat with `@signalbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

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

@@ -1,10 +1,10 @@
 # Setting up Mautrix Telegram (optional)
 
-The playbook can install and configure [mautrix-telegram](https://github.com/tulir/mautrix-telegram) for you.
+The playbook can install and configure [mautrix-telegram](https://github.com/mautrix/telegram) for you.
 
-See the project's [documentation](https://github.com/tulir/mautrix-telegram/wiki#usage) to learn what it does and why it might be useful to 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` and then use the following playbook configuration:
+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
@@ -12,10 +12,9 @@ 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://github.com/tulir/mautrix-telegram/wiki/Authentication#replacing-telegram-accounts-matrix-puppet-with-matrix-account) (hint: you most likely do), you have 2 ways of going about it.
+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
 
@@ -46,8 +45,23 @@ https://matrix.DOMAIN/_matrix/client/r0/login
 
 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://github.com/tulir/mautrix-telegram/wiki/Relay-bot)), which allows anonymous user to chat with telegram users, use the following additional playbook configuration:
+If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, 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

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

@@ -0,0 +1,35 @@
+# 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.

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

@@ -1,19 +1,36 @@
 # Setting up Mautrix Whatsapp (optional)
 
-The playbook can install and configure [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) for you.
+The playbook can install and configure [mautrix-whatsapp](https://github.com/mautrix/whatsapp) for you.
 
-See the project's [documentation](https://github.com/tulir/mautrix-whatsapp/wiki) to learn what it does and why it might be useful to 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://github.com/tulir/mautrix-whatsapp/wiki/Authentication#replacing-whatsapp-accounts-matrix-puppet-with-matrix-account) (hint: you most likely do), you have 2 ways of going about it.
+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
 

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

@@ -0,0 +1,36 @@
+# 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) bridge 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.

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

@@ -0,0 +1,36 @@
+# Setting up MX Puppet GroupMe (optional)
+
+The playbook can install and configure
+[mx-puppet-groupme](https://gitlab.com/robintown/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.

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

@@ -0,0 +1,36 @@
+# 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.
+

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

@@ -1,20 +1,33 @@
 # Setting up MX Puppet Slack (optional)
 
-The playbook can install and configure
-[mx-puppet-slack](https://github.com/Sorunome/mx-puppet-slack) for you.
+**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.
 
-To enable the [Slack](https://slack.com/) bridge just use the following
-playbook configuration:
+## Setup
 
+To enable the [Slack](https://slack.com/) bridge:
 
-```yaml
-matrix_mx_puppet_slack_enabled: true
-matrix_mx_puppet_slack_client_id: ""
-matrix_mx_puppet_slack_client_secret: ""
-```
-
+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
 

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

@@ -0,0 +1,32 @@
+# 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.

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

@@ -0,0 +1,36 @@
+# 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.

docs/configuring-playbook-client-cinny.md

@@ -0,0 +1,21 @@
+# 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 }}"
+```

docs/configuring-playbook-client-element.md

@@ -0,0 +1,41 @@
+# Configuring Element (optional)
+
+By default, this playbook installs the [Element](https://github.com/vector-im/element-web) Matrix client web application.
+If that's okay, you can skip this document.
+
+
+## Disabling Element
+
+If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+
+```yaml
+matrix_client_element_enabled: false
+```
+
+
+## Configuring Element settings
+
+The playbook provides some customization variables you could use to change Element's settings.
+
+Their defaults are defined in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/matrix-client-element/templates/config.json.j2`](../roles/matrix-client-element/templates/config.json.j2) template.
+
+**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
+
+Alternatively, **if there is no pre-defined variable** for an Element setting you wish to change:
+
+- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Element's various settings that rarely get used.
+
+- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
+
+- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
+
+
+## Themes
+
+To change the look of Element, you can define your own themes manually by using the `matrix_client_element__settingDefaults_custom_themes` setting.
+
+Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_element_themes_enabled: true`).
+
+If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
+
+Note that for a custom theme to work well, all Element instances that you use must have the same theme installed.

docs/configuring-playbook-client-hydrogen.md

@@ -0,0 +1,21 @@
+# 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 }}"
+```

docs/configuring-playbook-dimension.md

@@ -3,11 +3,12 @@
 **[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
 
-This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and an [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environment. This is handled automatically based on the value of `matrix_synapse_federation_enabled`.
-
-Other important prerequisite is the `dimension.<your-domain>` DNS record being set up correctly. See [Configuring your DNS server](configuring-dns.md) on how to set up DNS record correctly.
+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
@@ -21,7 +22,7 @@ matrix_dimension_enabled: true
 
 ## Define admin users
 
-These users can modify the integrations this Dimension supports. Admin interface is accessible by opening Dimension in Riot and clicking the settings icon.
+These users can modify the integrations this Dimension supports. 
 Add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
 
 ```yaml
@@ -30,6 +31,7 @@ matrix_dimension_admins:
   - "@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
 
@@ -37,14 +39,27 @@ We recommend that you create a dedicated Matrix user for Dimension (`dimension`
 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, follow these steps:
+To get an access token for the Dimension user, you can follow one of two options:
 
-1. In a private browsing session (incognito window), open Riot.
-2. Log in with the `dimension` user and its password.
+*Through an interactive login*:
+
+1. In a private browsing session (incognito window), open Element.
+1. Log in with the `dimension` user and its password.
 1. Set the display name and avatar, if required.
-2. In the settings page choose "Help & About", scroll down to the bottom and click `Access Token: <click to reveal>`.
-3. Copy the highlighted text to your configuration.
-4. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
+1. In the settings page choose "Help & About", scroll down to the bottom and expand the `Access Token` section.
+1. Copy the access token to your configuration.
+1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
+
+*With CURL*
+
+```
+curl -X POST --header 'Content-Type: application/json' -d '{
+    "identifier": { "type": "m.id.user", "user": "YourDimensionUsername" },
+    "password": "YourDimensionPassword",
+    "type": "m.login.password"
+}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
+```
+*Change `YourDimensionUsername`, `YourDimensionPassword`, and `YOURDOMAIN` accordingly.*
 
 **Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
 
@@ -65,12 +80,14 @@ After these variables have been set, please run the following command to re-run
 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 riot-web, go to *Manage Integrations* &rightarrow; *Settings* &rightarrow; *Widgets* &rightarrow; *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
+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

docs/configuring-playbook-dynamic-dns.md

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

docs/configuring-playbook-etherpad.md

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

docs/configuring-playbook-external-postgres.md

@@ -4,7 +4,10 @@ By default, this playbook would set up a PostgreSQL database server on your mach
 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`).
-It should be something like this:
+
+**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
@@ -14,6 +17,10 @@ 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.

docs/configuring-playbook-federation.md

@@ -37,3 +37,30 @@ 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.**

docs/configuring-playbook-jitsi.md

@@ -1,6 +1,6 @@
 # Jitsi
 
-The playbook can install the [Jitsi](https://jitsi.org/) video-conferencing platform and integrate it with [Riot](configuring-playbook-riot-web.md).
+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.
 
@@ -13,8 +13,8 @@ Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record.
 
 You may also need to open the following ports to your server:
 
-- `10000/udp` - RTP media over UDP
 - `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
@@ -26,7 +26,6 @@ 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_component_secret: ""
 matrix_jitsi_jicofo_auth_password: ""
 matrix_jitsi_jvb_auth_password: ""
 matrix_jitsi_jibri_recorder_password: ""
@@ -42,13 +41,23 @@ If you're fine with such an open Jitsi instance, please skip to [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 two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
+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:
@@ -56,11 +65,19 @@ The default authentication mode of Jitsi is `internal`, however LDAP is also sup
 ```yaml
 matrix_jitsi_enable_auth: true
 matrix_jitsi_auth_type: ldap
-matrix_jitsi_ldap_url: ldap://ldap.DOMAIN  # or ldaps:// if using tls
-matrix_jitsi_ldap_base: "OU=People,DC=DOMAIN"
-matrix_jitsi_ldap_filter: "(&(uid=%u)(employeeType=active))"
-matrix_jitsi_ldap_use_tls: false
-matrix_jitsi_ldap_start_tls: true
+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.
@@ -81,35 +98,52 @@ matrix_jitsi_jvb_container_extra_arguments:
   - '--env "DOCKER_HOST_ADDRESS=<Local IP adress 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`
 
-## Required if configuring Jitsi with internal authentication: register new users
-
-Until this gets integrated into the playbook, we need to register new users / meeting hosts for Jitsi manually.
-Please SSH into your matrix host machine and execute the following command targeting the `matrix-jitsi-prosody` container:
-
-```bash
-docker exec matrix-jitsi-prosody prosodyctl --config /config/prosody.cfg.lua register <USERNAME> matrix-jitsi-web <PASSWORD>
-```
-
-Run this command for each user you would like to create, replacing `<USERNAME>` and `<PASSWORD>` accordingly. After you've finished, please exit the host.
-
-**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).
-
 
 ## Usage
 
 You can use the self-hosted Jitsi server in multiple ways:
 
-- **by adding a widget to a room via riot-web** (the one configured by the playbook at `https://riot.DOMAIN`). Just start a voice or a video call in a room containing more than 2 members and that would create a Jitsi widget which utilizes your self-hosted Jitsi server.
+- **by adding a widget to a room via Element** (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**: Riot 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).
+**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

docs/configuring-playbook-ma1sd.md

@@ -1,10 +1,21 @@
 # Adjusting ma1sd Identity Server configuration (optional)
 
-By default, this playbook configures an [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you.
+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.
+*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
 
@@ -31,12 +42,17 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
 
 - `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:
@@ -88,6 +104,22 @@ matrix_ma1sd_configuration_extension_yaml: |
             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).

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

@@ -1,31 +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.
-
-First you need to ensure, that the bridge has unix read and write rights to your modem. On debian based distributions there is nothing to do. On others distributions you either add a group `dialout` to your host and assign it to your modem or you give the matrix user or group access to your modem.
-
-To enable the bridge just use the following
-playbook configuration:
-
-
-```yaml
-matrix_sms_bridge_enabled: true
-matrix_sms_bridge_gammu_modem: "/dev/serial/by-id/myDeviceId"
-# generate a secret passwort e.g. with pwgen -s 64 1
-matrix_sms_bridge_database_password: ""
-# (optional) a room id to a default room
-matrix_sms_bridge_default_room: "" 
-# (optional) gammu reset frequencies (see https://wammu.eu/docs/manual/smsd/config.html#option-ResetFrequency)
-matrix_sms_bridge_gammu_reset_frequency: 3600
-matrix_sms_bridge_gammu_hard_reset_frequency: 0
-# (optional) group with unix read and write rights to modem
-matrix_sms_bridge_modem_group: 'dialout'
-```
-
-
-## Usage
-
-Read the [user guide](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md#user-guide) to see how this bridge works.

docs/configuring-playbook-matrix-corporal.md

@@ -11,15 +11,33 @@ The playbook can install and configure [matrix-corporal](https://github.com/devt
 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 [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md).
+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",
@@ -34,9 +52,9 @@ matrix_corporal_policy_provider_config: |
 matrix_corporal_http_api_enabled: true
 matrix_corporal_http_api_auth_token: "AUTH_TOKEN_HERE"
 
-# If you need to change the reconciliator user's id from the default (matrix-corporal)..
+# If you need to change matrix-corporal's user id from the default (matrix-corporal).
 # In any case, you need to make sure this Matrix user is created on your server.
-matrix_corporal_reconciliation_user_id_local_part: "matrix-corporal"
+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.
@@ -57,10 +75,48 @@ 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). 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 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
 
@@ -72,4 +128,4 @@ The following local filesystem paths are mounted in the `matrix-corporal` contai
 
 - `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write)
 
-As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container path `/etc/matrix-corporal`
+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).

docs/configuring-playbook-matrix-registration.md

@@ -0,0 +1,66 @@
+# Setting up matrix-registration (optional)
+
+The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you.
+
+> 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
+```

docs/configuring-playbook-nginx.md

@@ -23,3 +23,62 @@ 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`
+```

docs/configuring-playbook-own-webserver.md

@@ -55,6 +55,8 @@ Note that if your nginx version is old, it might not like our default choice of
 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
 
@@ -62,14 +64,14 @@ Once you've followed the [Preparation](#preparation) guide above, you can take a
 
 ### 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 for a sample configuration.
+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/conf.d/).
+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
@@ -106,6 +108,12 @@ matrix_nginx_proxy_container_federation_host_bind_port: '127.0.0.1:8449'
 # 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.
@@ -113,7 +121,7 @@ With this, nginx would still be in use, but it would not bother with anything SS
 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; `riot.DOMAIN` and `dimension.DOMAIN` are optional).
+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
 
@@ -131,6 +139,12 @@ matrix_nginx_proxy_https_enabled: false
 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
@@ -144,8 +158,7 @@ matrix_nginx_proxy_container_extra_arguments:
   - '--label "traefik.enable=true"'
 
   # The Nginx proxy container will receive traffic from these subdomains
-  # (Replace DOMAIN with your domain, e.g. example.com)
-  - '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`matrix.DOMAIN`,`riot.DOMAIN`,`dimension.DOMAIN`)"'
+  - '--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"'
@@ -161,8 +174,7 @@ matrix_synapse_container_extra_arguments:
   - '--label "traefik.enable=true"'
 
   # The Synapse container will receive traffic from this subdomain
-  # (Replace DOMAIN with your domain, e.g. example.com)
-  - '--label "traefik.http.routers.matrix-synapse.rule=Host(`matrix.DOMAIN`)"'
+  - '--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"'
@@ -174,7 +186,7 @@ matrix_synapse_container_extra_arguments:
   - '--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`, `riot.DOMAIN`, and `dimension.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.
+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:
 
@@ -195,3 +207,38 @@ Note that this configuration on its own does **not** redirect traffic on port 80
       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
+```

docs/configuring-playbook-postgres-backup.md

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

docs/configuring-playbook-prometheus-grafana.md

@@ -0,0 +1,134 @@
+# 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
+
+matrix_prometheus_node_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_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 you wish, you could expose homeserver metrics without enabling (installing) Prometheus and Grafana via the playbook. This may be useful for hooking Matrix services to an external Prometheus/Grafana installation.
+
+To do this, you may be interested in the following variables:
+
+Name | Description
+-----|----------
+`matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
+`matrix_nginx_proxy_proxy_synapse_metrics`|Set this to `true` to make matrix-nginx-proxy expose the Synapse metrics at `https://matrix.DOMAIN/_synapse/metrics`
+`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled`|Set this to `true` to password-protect (using HTTP Basic Auth) `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus`, the password is defined in `matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`)
+`matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_key`|Set this to a password to use for HTTP Basic Auth for protecting `https://matrix.DOMAIN/_synapse/metrics` (the username is always `prometheus` - it's not configurable). Do not write the password in plain text. See `man 1 htpasswd` or use `htpasswd -c mypass.htpasswd prometheus` to generate the expected hash for nginx. 
+`matrix_server_fqn_grafana`|Use this variable to override the domain at which the Grafana web user-interface is at (defaults to `stats.DOMAIN`)
+
+### Collecting worker metrics to an external Prometheus server
+
+If you are using workers (`matrix_synapse_workers_enabled`) and have enabled `matrix_nginx_proxy_proxy_synapse_metrics` as described above, the playbook will also automatically proxy the all worker threads's metrics to `https://matrix.DOMAIN/_synapse-worker-TYPE-ID/metrics`, where `TYPE` corresponds to the type and `ID` to the instanceId of a worker as exemplified in `matrix_synapse_workers_enabled_list`.
+
+The playbook also generates an exemplary prometheus.yml config file (`matrix_base_data_path/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs, especially 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: /_synapse/metrics
+    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: 'synapse-generic_worker-1'
+    metrics_path: /_synapse-worker-generic_worker-18111/metrics
+    scheme: https
+    basic_auth:
+      username: prometheus
+      password_file: /etc/prometheus/password.pwd
+    static_configs:
+      - targets: ['matrix.DOMAIN:443']
+        labels:
+          job: "generic_worker"
+          index: 18111
+```
+
+### Collecting system and Postgres metrics to an external Prometheus server (advanced)
+
+When you normally enable the Prometheus and Grafana via the playbook, it will also show general system (via node-exporter) and Postgres (via postgres-exporter) stats. If you are instead collecting your metrics to an external Prometheus server, you can follow this advanced configuration example to also export these stats.
+
+It would be possible to use `matrix_prometheus_node_exporter_container_http_host_bind_port` etc., but that is not always the best choice, for example because your server is on a public network.
+
+Use the following variables in addition to the ones mentioned above:
+
+Name | Description
+-----|----------
+`matrix_nginx_proxy_proxy_grafana_enabled`|Set this to `true` to make the stats subdomain (`matrix_server_fqn_grafana`) available via the Nginx proxy
+`matrix_ssl_additional_domains_to_obtain_certificates_for`|Add `"{{ matrix_server_fqn_grafana }}"` to this list to have letsencrypt fetch a certificate for the stats subdomain
+`matrix_prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter
+`matrix_prometheus_postgres_exporter_enabled`|Set this to `true` to enable the Postgres exporter
+`matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks`|Add locations to this list depending on which of the above exporters you enabled (see below)
+
+```nginx
+matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks:
+  - 'location /node-exporter/ {
+  resolver 127.0.0.11 valid=5s;
+  proxy_pass http://matrix-prometheus-node-exporter:9100/;
+  auth_basic "protected";
+  auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
+  }'
+  - 'location /postgres-exporter/ {
+  resolver 127.0.0.11 valid=5s;
+  proxy_pass http://matrix-prometheus-postgres-exporter:9187/;
+  auth_basic "protected";
+  auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
+  }'
+```
+You can customize the `location`s to your liking, just point your Prometheus to there later (e.g. `stats.DOMAIN/node-exporter/metrics`). Nginx is very picky about the `proxy_pass`syntax: take care to follow the example closely and note the trailing slash as well as absent use of variables. postgres-exporter uses the nonstandard port 9187.
+
+## 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)
+

docs/configuring-playbook-prometheus-postgres.md

@@ -0,0 +1,29 @@
+# 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
+
+# the role creates a postgres user as credential. You can configure these if required:
+matrix_prometheus_postgres_exporter_database_username: 'matrix_prometheus_postgres_exporter'
+matrix_prometheus_postgres_exporter_database_password: 'some-password'
+
+```
+
+## 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.
+
+
+## More information
+
+- [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)
+

docs/configuring-playbook-riot-web.md

@@ -1,40 +1,39 @@
 # Configuring Riot-web (optional)
 
-By default, this playbook installs the [Riot-web](https://github.com/vector-im/riot-web) Matrix client web application.
-If that's okay, you can skip this document.
+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
 
 
-## Disabling riot-web
+## Migrating to Element
 
-If you'd like for the playbook to not install (or to uninstall the previously installed riot-web), you can disable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+### 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:
 
-```yaml
-matrix_riot_web_enabled: false
 ```
-
-## Configuring riot-web settings
-
-The playbook provides some customization variables you could use to change riot-web's settings.
-
-Their defaults are defined in [`roles/matrix-riot-web/defaults/main.yml`](../roles/matrix-riot-web/defaults/main.yml) and they ultimately end up in the generated `/matrix/riot-web/config.json` file (on the server). This file is generated from the [`roles/matrix-riot-web/templates/config.json.j2`](../roles/matrix-riot-web/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 a riot-web setting you wish to change:
-
-- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of riot-web's various settings that rarely get used.
-
-- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/matrix-riot-web/templates/config.json.j2)) by making use of the `matrix_riot_web_configuration_extension_json_` variable. You can find information about this in [`roles/matrix-riot-web/defaults/main.yml`](../roles/matrix-riot-web/defaults/main.yml).
-
-- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_riot_web_configuration_default` (or `matrix_riot_web_configuration`). You can find information about this in [`roles/matrix-riot-web/defaults/main.yml`](../roles/matrix-riot-web/defaults/main.yml).
-
-
-## Themes
-
-To change the look of riot-web, you can define your own themes manually by using the `matrix_riot_web_settingDefaults_custom_themes` setting.
-
-Or better yet, you can automatically pull it all themes provided by the [aaronraimist/riot-web-themes](https://github.com/aaronraimist/riot-web-themes) project by simply flipping a flag (`matrix_riot_web_themes_enabled: true`).
-
-If you make your own theme, we encourage you to submit it to the **aaronraimist/riot-web-themes** project, so that the whole community could easily enjoy it.
-
-Note that for a custom theme to work well, all riot-web/riot-desktop instances that you use must have the same theme installed.
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```

docs/configuring-playbook-s3.md

@@ -6,6 +6,11 @@ If that's alright, you can skip this.
 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.
 
+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.
+
+
 ## 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 security policy:
@@ -47,5 +52,136 @@ You can use any S3-compatible object store by **additionally** configuring these
 
 ```yaml
 matrix_s3_media_store_custom_endpoint_enabled: true
+# Example: "https://storage.googleapis.com"
 matrix_s3_media_store_custom_endpoint: "your-custom-endpoint"
 ```
+
+### Backblaze B2
+
+To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html):
+
+- 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 use the following **custom** rules:
+  - File Path: *empty value*
+  - Days Till Hide: *empty value*
+  - Days Till Delete: `1`
+- 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
+
+Copy the `keyID` and `applicationKey`.
+
+You need the following *additional* playbook configuration (on top of what you see above):
+
+```yaml
+matrix_s3_media_store_bucket_name: "YOUR_BUCKET_NAME_GOES_HERE"
+matrix_s3_media_store_aws_access_key: "YOUR_keyID_GOES_HERE"
+matrix_s3_media_store_aws_secret_key: "YOUR_applicationKey_GOES_HERE"
+matrix_s3_media_store_custom_endpoint_enabled: true
+matrix_s3_media_store_custom_endpoint: "https://s3.us-west-002.backblazeb2.com" # this may be different for your bucket
+```
+
+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:
+
+- [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' \
+-v /matrix/synapse/storage/media-store/:/work \
+--entrypoint=/bin/sh \
+docker.io/tianon/backblaze-b2:2.1.0 \
+-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET > /dev/null && b2 sync /work/ b2://$B2_BUCKET_NAME'
+```
+
+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`

docs/configuring-playbook-ssl-certificates.md

@@ -1,9 +1,9 @@
 # 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 `riot.<your-domain>`)
+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](docs/configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the 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.
 
@@ -13,7 +13,7 @@ Things discussed in this document:
 
 - [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](docs/configuring-playbook-own-webserver.md) and would rather this playbook leaves SSL certificate management to you
+- [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
 
@@ -28,6 +28,8 @@ If self-signed certificates are alright with you, you can ask the playbook to ge
 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
 
@@ -41,8 +43,9 @@ With such a configuration, the playbook would expect you to drop the SSL certifi
 
 - `<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 `riot.<your-domain>`).
+where `<domain>` refers to the domains that you need (usually `matrix.<your-domain>` and `element.<your-domain>`).
 
 
 ## Not bothering with SSL certificates
@@ -62,22 +65,27 @@ 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 `riot.<your-domain>`, unless you have disabled the Riot component using `matrix_riot_web_enabled: false`
+- 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 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
-# Note: we need to explicitly list the aforementioned Matrix domains that you use (Matrix, Riot, Dimension).
-# In this example, we retrieve an extra certificate - one for the base domain (in the `matrix_domain` variable).
+# 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_domains_to_obtain_certificates_for:
-  - '{{ matrix_server_fqn_matrix }}'
-  - '{{ matrix_server_fqn_riot }}'
-  - '{{ matrix_server_fqn_dimension }}'
+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:
@@ -86,9 +94,18 @@ After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually ob
 
 - 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 available in `/matrix/ssl/config/live/<your-other-domain>/...`.
+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-synapse.conf`
-Don't be alarmed if the above configuraiton file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.
+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
+```

docs/configuring-playbook-sygnal.md

@@ -0,0 +1,71 @@
+# 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.

docs/configuring-playbook-synapse-admin.md

@@ -0,0 +1,64 @@
+# 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"'
+```

docs/configuring-playbook-synapse.md

@@ -16,3 +16,61 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
 - 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'"
+]
+```
+
+If you're using the default setup (the `matrix-nginx-proxy` webserver being enabled) or you're using your own `nginx` server (which imports the configuration files generated by the playbook), you're good to go. If you use some other webserver, you may need to tweak your reverse-proxy setup manually to forward traffic to the various workers.
+
+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 %}"
+```
+

docs/configuring-playbook-telemetry.md

@@ -10,7 +10,7 @@ growth of the Matrix community, and helps to make Matrix a success.
 
 ## Enabling Telemetry
 
-If you'd like to **help by enabling submission of anonymized usage statistics** for your homeserver, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+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

docs/configuring-playbook.md

@@ -8,15 +8,15 @@ To configure the playbook, you need to have done the following things:
 
 You can then follow these steps inside the playbook directory:
 
-- create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
+1. create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
 
-- copy the sample configuration file (`cp examples/host-vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
+1. copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
 
-- 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. 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.
 
-- copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
+1. copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
 
-- edit the inventory hosts file (`inventory/hosts`) to your liking
+1. edit the inventory hosts file (`inventory/hosts`) to your liking
 
 
 For a basic Matrix installation, that's all you need.
@@ -33,19 +33,20 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up the Jitsi video-conferencing platform](configuring-playbook-jitsi.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
 
 - [Configuring Synapse](configuring-playbook-synapse.md) (optional)
 
-- [Configuring Riot-web](configuring-playbook-riot-web.md) (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 ma1sd Identity Server configuration](configuring-playbook-ma1sd.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)
@@ -65,9 +66,19 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [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)
@@ -89,18 +100,69 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [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 Beeper LinkedIn bridging](configuring-playbook-bridge-beeper-linkedin.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 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)
 
 - [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 Email2Matrix](configuring-playbook-email2matrix.md) (optional)
 
-- [Setting up Matrix SMS bridging](configuring-playbook-matrix-bridge-sms.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 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)

docs/configuring-well-known.md

@@ -6,7 +6,7 @@ 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. Riot), 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)
+- (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
@@ -46,7 +46,7 @@ If you decide to go this route, you don't need to read ahead in this document. W
 
 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 (e.g. `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.
+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:
 
@@ -59,7 +59,7 @@ 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 Riot) 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.
+- 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.
@@ -69,7 +69,7 @@ It is, however, **a little fragile**, as future updates performed by this playbo
 
 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 2 might be more suitable.
+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.
 
@@ -98,16 +98,15 @@ server {
 }
 ```
 
-**For Apache**, it would be something like this:
+**For Apache2**, it would be something like this:
 
 ```apache
 <VirtualHost *:443>
 	ServerName DOMAIN
 
 	SSLProxyEngine on
-	<Location /.well-known/matrix>
-		ProxyPass "https://matrix.DOMAIN/.well-known/matrix"
-	</Location>
+	ProxyPass /.well-known/matrix https://matrix.DOMAIN/.well-known/matrix nocanon
+	ProxyPassReverse /.well-known/matrix https://matrix.DOMAIN/.well-known/matrix nocanon
 
 	# other configuration
 </VirtualHost>
@@ -116,8 +115,22 @@ server {
 **For Caddy 2**, it would be something like this:
 
 ```caddy
-reverse_proxy /.well-known/matrix/* https://matrix.DOMAIN {
-	header_up Host {http.reverse_proxy.upstream.hostport}
+DOMAIN.com {
+   @wellknown {
+         path /.well-known/matrix/*:x
+   }
+
+   handle @wellknown {
+      reverse_proxy https://matrix.DOMAIN.com {
+          header_up Host {http.reverse_proxy.upstream.hostport}
+      }
+   }
+    # Configration for the base domain goes here
+  # handle {
+  #    header -Server
+  #     encode zstd gzip
+  #    reverse_proxy localhost:4020
+  # }
 }
 ```
 
@@ -148,6 +161,13 @@ backend matrix-backend
 	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.DOMAIN/.well-known/matrix/:splat 200!
+```
+
 Make sure to:
 
 - **replace `DOMAIN`** in the server configuration with your actual domain name

docs/container-images.md

@@ -0,0 +1,111 @@
+# 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)
+
+- [matrixdotorg/dendrite-monolith](https://hub.docker.com/r/matrixdotorg/dendrite-monolith/) - the official [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-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) - the [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) bridge to [Skype](https://www.skype.com) (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/robintown/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)
+
+- [etke.cc/honoroit](https://gitlab.com/etke.cc/honoroit/container_registry) - the [honoroit](https://gitlab.com/etke.cc/honoroit) helpdesk 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

docs/faq.md

@@ -0,0 +1,475 @@
+# 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.

docs/howto-server-delegation.md

@@ -22,20 +22,20 @@ If this is okay with you, feel free to not read ahead.
 
 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>`)
+- 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.
 
-If this is not a concern for you, feel free to not read ahead.
+**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).
+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.
+**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).
 
@@ -47,7 +47,7 @@ To use DNS SRV record validation, you need to:
 
 - 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>`!). See below.
+- 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
@@ -89,7 +89,7 @@ matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: /matrix/ssl/
 If your files are not in `/matrix/ssl` but in some other location, you would need to mount them into the container:
 
 ```yaml
-matrix_synapse_container_extra_arguments:
+matrix_nginx_proxy_container_extra_arguments:
   - "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
 ```
 

docs/importing-postgres.md

@@ -1,18 +1,19 @@
 # Importing an existing Postgres database from another installation (optional)
 
-Run this if you'd like to import your database from a previous installation of Synapse.
-(don't forget to import your `media_store` files as well - see [the importing-media-store guide](importing-media-store.md)).
+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 `homeserver` by default (controlled by the `matrix_postgres_db_name` variable).
-If your database name differs, be sure to change `matrix_postgres_db_name` to your desired name and to re-run the playbook before proceeding.
+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.
+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 roomes, ...)
 
 Before doing the actual import, **you need to upload your Postgres dump file to the server** (any path is okay).
 
@@ -21,6 +22,81 @@ Before doing the actual import, **you need to upload your Postgres dump file to
 
 To import, run this command (make sure to replace `<server-path-to-postgres-dump.sql>` with a file path on your server):
 
-	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql>' --tags=import-postgres
+```sh
+ansible-playbook -i inventory/hosts setup.yml \
+--extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql>' \
+--tags=import-postgres
+```
 
 **Note**: `<server-path-to-postgres-dump.sql>` must be a file path to a Postgres dump file on the server (not on your local machine!).
+
+
+## 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`

docs/importing-synapse-media-store.md

@@ -1,4 +1,4 @@
-# Importing `media_store` data files from an existing installation (optional)
+# 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.
 
@@ -17,6 +17,6 @@ As an alternative, you can perform a manual restore using the [AWS CLI tool](htt
 
 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-media-store
+	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!).

docs/importing-synapse-sqlite.md

@@ -1,7 +1,7 @@
-# Importing an existing SQLite database from another installation (optional)
+# 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-media-store guide](importing-media-store.md)).
+(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.
@@ -18,6 +18,9 @@ Before doing the actual import, **you need to upload your SQLite database file t
 
 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-sqlite-db
+	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_homeserver_db=<server-path-to-homeserver.db>' --tags=import-synapse-sqlite-db
 
-**Note**: `<server-path-to-homeserver.db>` must be a file path to a `homeserver.db` file on the server (not on your local machine!).
+**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.

docs/installing.md

@@ -1,46 +1,56 @@
 # 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 as-is to set up a server:
+Run this command to install the Matrix services:
 
 ```bash
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
 ```
 
-**Note**: 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.
+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.
 
-**Note**: 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.
-
-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.
 
 
-## Things you might want to do after installing
+## 2. Things you might want to do after installing
 
-After installing, but before starting the services, you may want to do additional things like:
+**Before starting the services**, you may want to do additional things like:
 
-- [Importing an existing SQLite database (from another installation)](importing-sqlite.md) (optional)
+- [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 installation](importing-media-store.md) (optional)
+- [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
 
 
-## Starting the services
+## 3. Starting the services
 
-When you're ready to start the Matrix services (and set them up to auto-start in the future):
+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
 ```
 
-Now that the services are running, you might want to:
+## 4. Finalize the installation
 
-- **finalize the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md)
-- or [create your first user account](registering-users.md)
-- or [set up the Dimension Integrations Manager](configuring-playbook-dimension.md)
-- or [check if services work](maintenance-checking-services.md)
-- or learn how to [upgrade your services when new versions are released](maintenance-upgrading-services.md)
-- or learn how to [migrate to another server](maintenance-migrating.md)
+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))

docs/maintenance-and-troubleshooting.md

@@ -33,6 +33,12 @@ 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
 

docs/maintenance-migrating.md

@@ -1,6 +1,10 @@
+> **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 ot less downtime
+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

docs/maintenance-postgres.md

@@ -12,6 +12,7 @@ Table of contents:
 
 - [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
 
@@ -19,9 +20,22 @@ You can use the `/usr/local/bin/matrix-postgres-cli` tool to get interactive ter
 
 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:
@@ -35,20 +49,20 @@ ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-vacuum,start
 
 ## Backing up PostgreSQL
 
-To make a back up of the current PostgreSQL database, make sure it's running and then execute a command like this on the server:
+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
-docker run \
---rm \
---network=matrix \
+/usr/bin/docker exec \
 --env-file=/matrix/postgres/env-postgres-psql \
-postgres:12.1-alpine \
-pg_dumpall -h matrix-postgres \
+matrix-postgres \
+/usr/local/bin/pg_dumpall -h matrix-postgres \
 | gzip -c \
-> /postgres.sql.gz
+> /matrix/postgres.sql.gz
 ```
 
-If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above command will not work, because the credentials file (`/matrix/postgres/env-postgres-psql`) is not available.
+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).
 
@@ -66,7 +80,7 @@ This playbook can upgrade your existing Postgres setup with the following comman
 
 	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-auto-upgrade-backup`.
+**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**.
@@ -79,3 +93,67 @@ If you have plenty of space in `/tmp` and would rather avoid gzipping, you can e
 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",
+]
+```

docs/maintenance-synapse.md

@@ -4,59 +4,19 @@ This document shows you how to perform various maintenance tasks related to the
 
 Table of contents:
 
-- [Purging unused data with synapse-janitor](#purging-unused-data-with-synapse-janitor), for when you wish to delete unused data from the Synapse database
-
 - [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
 
-- [Synapse maintenance](#synapse-maintenance)
-	- [Purging unused data with synapse-janitor](#purging-unused-data-with-synapse-janitor)
-		- [Vacuuming Postgres](#vacuuming-postgres)
-	- [Purging old data with the Purge History API](#purging-old-data-with-the-purge-history-api)
-	- [Compressing state with rust-synapse-compress-state](#compressing-state-with-rust-synapse-compress-state)
+- [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
 
-## Purging unused data with synapse-janitor
-
-**NOTE**: There are [reports](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/465) that **synapse-janitor is dangerous to use and causes database corruption**. You may wish to refrain from using it.
-
-When you **leave** and **forget** a room, Synapse can clean up its data, but currently doesn't.
-This **unused and unreachable data** remains in your database forever.
-
-There are external tools (like [synapse-janitor](https://github.com/xwiki-labs/synapse_scripts)), which are meant to solve this problem.
-
-To ask the playbook to run synapse-janitor, execute:
-
-```bash
-ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-synapse-janitor,start
-```
-
-**Note**: this will automatically stop Synapse temporarily and restart it later.
-
-
-### Vacuuming Postgres
-
-Running synapse-janitor potentially deletes a lot of data from the Postgres database.
-However, disk space only ever gets released after a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
-
-It's easiest if you ask the playbook to run both synapse-janitor and a `VACUUM FULL` in one call:
-
-```bash
-ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-synapse-janitor,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`).
-
+- [Make Synapse faster](#make-synapse-faster)
 
 ## Purging old data with the Purge History API
 
-If [purging unused and unreachable data](#purging-unused-data-with-synapse-janitor) is not enough for you, you can start deleting in-use (but old) data.
+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**.
 
-**This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.
-
-Synapse provides a [Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.rst) that you can use to purge on a per-room basis.
-
-To make use of this API, **you'll need an admin access token** first. You can find your access token in the setting of some clients (like riot-web).
+To make use of this API, **you'll need an admin access token** first. You can find your access token in the setting of some clients (like Element).
 Alternatively, you can log in and obtain a new access token like this:
 
 ```
@@ -65,22 +25,37 @@ curl \
 https://matrix.DOMAIN/_matrix/client/r0/login
 ```
 
-Follow the [Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.rst) documentation page for the actual purging instructions.
+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.
 
-Don't forget that disk space only ever gets released after a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql) - something the playbook can help you with.
+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.
+[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.
 
-Unfortunately, at this time the playbook can't help you run this **experimental tool**.
+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).
 
-Since it's also experimental, you may wish to stay away from it, or at least [make Postgres backups](./maintenance-postgres.md#backing-up-postgresql) first.
 
 ## Browse and manipulate the database
 
-When the [matrix 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.
+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):
 
 ```
@@ -97,3 +72,13 @@ 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).

docs/prerequisites.md

@@ -1,21 +1,41 @@
 # Prerequisites
 
-- An x86 server running **CentOS** (7 only for now; [8 is not yet supported](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/300)), **Debian** (9/Stretch+), **Ubuntu** (16.04+), or **Archlinux**. This playbook doesn't support running on ARM ([see](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/299)), however a minimal subset of the tools can be built on the host, which may result in a working configuration, even on a Raspberry pi (see [Alternative Architectures](alternative-architectures.md)). 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.
+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 python`).
-
-- A `cron`-like tool installed on the server such as `cron` or `anacron` to automatically schedule the Let's Encrypt SSL certificates's renewal. *This can be ignored if you use your own SSL certificates.*
+- [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.
 
-- Either the `dig` tool or `python-dns` installed on your own computer. Used later on, by the playbook's [services check](maintenance-checking-services.md) feature.
+- [`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 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), `3478/udp` (TURN over UDP), `5349/tcp` (TURN over TCP), `5349/udp` (TURN over UDP), `8448/tcp` (Matrix Federation API HTTPS webserver), the range `49152-49172/udp` (TURN over UDP), `4443/tcp` (Jitsi Harvester fallback), `10000/udp` (Jitsi video RTP). 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)).
+- Some TCP/UDP ports open. This playbook 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).

docs/registering-users.md

@@ -1,6 +1,18 @@
 # Registering users
 
-Run this to create a new user account on your Matrix server.
+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):
 
@@ -16,16 +28,37 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-usern
 
 **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 riot-web service that this playbook has created for you at a URL like this: `https://riot.<domain>/`.
+**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).
 
 
-## Adding/Removing Administrator privileges to an existing user.  
+## 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.
 

docs/self-building.md

@@ -2,22 +2,44 @@
 
 **Caution: self-building does not have to be used on its own. See the [Alternative Architectures](alternative-architectures.md) page.**
 
-The playbook supports the self-building of some of its components. This may be useful for architectures besides x86_64, which have no Docker images right now (e g. the armv7 for the Raspberry Pi). Some playbook roles have been updated, so they build the necessary image on the host. It needs more space, as some build tools need to be present (like Java, for ma1sd).
+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.
 
-To use these modification there is a variable that needs to be switched to enable this functionality. Add this to your `vars.yaml` file:
-```yaml
-matrix_container_images_self_build: true
-```
-Setting that variable will self-build every role which supports self-building. Self-building can be set on a per-role basis as well.
+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-riot-web`
+- `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-mautrix-facebook`
-- `matrix-mautrix-hangouts`
-- `matrix-mx-puppet-skype`
+- `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-skype`
+- `matrix-bridge-mx-puppet-steam`
+- `matrix-bot-mjolnir`
+- `matrix-bot-honoroit`
+- `matrix-bot-matrix-reminder-bot`
+- `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.

docs/uninstalling.md

@@ -1,24 +1,38 @@
 # Uninstalling
 
-**Note**: If you have some trouble with your installation configuration, you can just [re-run the playbook](installing.md) and it will try to set things up again. You don't need to uninstall and install fresh.
+**Warnings**:
 
-However, if you've installed this on some server where you have other stuff you wish to preserve, and now want get rid of Matrix, it's enough to do these:
+- If your server federates with others, make sure to **leave any federated rooms before nuking your Matrix server's data**. Otherwise, the next time you set up a Matrix server for this domain (regardless of the installation method you use), you'll encounter trouble federating.
 
-- ensure all Matrix services are stopped (`systemctl stop 'matrix*'`)
+- If you have some trouble with your installation, you can just [re-run the playbook](installing.md) and it will try to set things up again. **Uninstalling and then installing anew rarely solves anything**.
 
-- delete the Matrix-related systemd .service files (`rm -f /etc/systemd/system/matrix*`) and reload systemd (`systemctl daemon-reload`)
 
-- delete all Matrix-related cronjobs (`rm -f /etc/cron.d/matrix*`)
+-----------------
+
+
+## Uninstalling using a script
+
+Installing places a `/usr/local/bin/matrix-remove-all` script on the server.
+
+You can run it to to have it uninstall things for you automatically (see below). **Use with caution!**
+
+
+## Uninstalling manually
+
+If you prefer to uninstall manually, run these commands (most are meant to be executed on the Matrix server itself):
+
+- ensure all Matrix services are stopped: `ansible-playbook -i inventory/hosts setup.yml --tags=stop` (if you can't get Ansible working to run this command, you can run `systemctl stop 'matrix*'` manually on the server)
+
+- delete the Matrix-related systemd `.service` and `.timer` files (`rm -f /etc/systemd/system/matrix*.{service,timer}`) and reload systemd (`systemctl daemon-reload`)
 
 - delete some helper scripts (`rm -f /usr/local/bin/matrix*`)
 
-- delete some cached Docker images (or just delete them all: `docker rmi $(docker images -aq)`)
+- delete some cached Docker images (`docker system prune -a`) or just delete them all (`docker rmi $(docker images -aq)`)
 
-- delete the Docker network: `docker network rm matrix`
+- delete the Docker networks: `docker network rm matrix matrix-coturn` (might have been deleted already if you ran the `docker system prune` command)
 
 - uninstall Docker itself, if necessary
 
 - delete the `/matrix` directory (`rm -rf /matrix`)
 
-The script `/usr/local/bin/matrix-remove-all` performs all these steps (**use with caution!**).
 

docs/updating-users-passwords.md

@@ -10,7 +10,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-usern
 
 **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 riot-web service that this playbook has created for you at a URL like this: `https://riot.<domain>/`.
+**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>/`.
 
 
 ## Option 2 (if you are using an external Postgres server):
@@ -26,7 +26,7 @@ and then connecting to the postgres server and executing:
 ```
 UPDATE users SET password_hash = '<password-hash>' WHERE name = '@someone:server.com'
 ```
-`
+
 where `<password-hash>` is the hash returned by the docker command above.
 
 
@@ -34,9 +34,9 @@ where `<password-hash>` is the hash returned by the docker command above.
 
 Use the Synapse User Admin API as described here: https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#reset-password
 
-This requires an access token from a server admin account. *This method will also log the user out of all of their clients while the other options do not.* 
+This requires an access token from a server admin account. *This method will also log the user out of all of their clients while the other options do not.*
 
-If you didn't make your account a server admin when you created it, you can use the `/usr/local/bin/matrix-change-user-admin-status` script as described in [registering-users.md](registering-users.md). 
+If you didn't make your account a server admin when you created it, you can use the `/usr/local/bin/matrix-change-user-admin-status` script as described in [registering-users.md](registering-users.md).
 
 ### Example:
 To set @user:domain.com's password to `correct_horse_battery_staple` you could use this curl command:

examples/apache/matrix-client-element.conf

@@ -1,8 +1,8 @@
-# This is a sample file demonstrating how to set up reverse-proxy for riot.DOMAIN.
-# If you're not using Riot (`matrix_riot_web_enabled: false`), you won't need this.
+# This is a sample file demonstrating how to set up reverse-proxy for element.DOMAIN.
+# If you're not using Element (`matrix_client_element_enabled: false`), you won't need this.
 
 <VirtualHost *:80>
-	ServerName riot.DOMAIN
+	ServerName element.DOMAIN
 
 	ProxyVia On
 
@@ -13,17 +13,17 @@
 		ProxyPass http://127.0.0.1:2402/.well-known/acme-challenge
 	</Location>
 
-	Redirect permanent / https://riot.DOMAIN/
+	Redirect permanent / https://element.DOMAIN/
 </VirtualHost>
 
 <VirtualHost *:443>
-	ServerName riot.DOMAIN
+	ServerName element.DOMAIN
 
 	SSLEngine On
 
 	# If you manage SSL certificates by yourself, these paths will differ.
-	SSLCertificateFile /matrix/ssl/config/live/riot.DOMAIN/fullchain.pem
-	SSLCertificateKeyFile /matrix/ssl/config/live/riot.DOMAIN/privkey.pem
+	SSLCertificateFile /matrix/ssl/config/live/element.DOMAIN/fullchain.pem
+	SSLCertificateKeyFile /matrix/ssl/config/live/element.DOMAIN/privkey.pem
 
 	SSLProxyEngine on
 	SSLProxyProtocol +TLSv1.2 +TLSv1.3
@@ -36,6 +36,6 @@
 	ProxyPass / http://127.0.0.1:8765/
 	ProxyPassReverse / http://127.0.0.1:8765/
 
-	ErrorLog ${APACHE_LOG_DIR}/riot.DOMAIN-error.log
-	CustomLog ${APACHE_LOG_DIR}/riot.DOMAIN-access.log combined
+	ErrorLog ${APACHE_LOG_DIR}/element.DOMAIN-error.log
+	CustomLog ${APACHE_LOG_DIR}/element.DOMAIN-access.log combined
 </VirtualHost>

examples/apache/matrix-synapse.conf

@@ -32,6 +32,7 @@
 	ProxyPreserveHost On
 	ProxyRequests Off
 	ProxyVia On
+	RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 
 	# Keep some URIs free for different proxy/location
 	ProxyPassMatch ^/.well-known/matrix/client !
@@ -43,6 +44,16 @@
 	AllowEncodedSlashes NoDecode
 	ProxyPass /_matrix http://127.0.0.1:8008/_matrix retry=0 nocanon
 	ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
+	ProxyPass /_synapse/client http://127.0.0.1:8008/_synapse/client retry=0 nocanon
+	ProxyPassReverse /_synapse/client http://127.0.0.1:8008/_synapse/client
+	
+	# Proxy Admin API (necessary for Synapse-Admin)
+	# ProxyPass /_synapse/admin http://127.0.0.1:8008/_synapse/admin retry=0 nocanon
+	# ProxyPassReverse /_synapse/admin http://127.0.0.1:8008/_synapse/admin
+	
+	# Proxy Synapse-Admin
+	# ProxyPass /synapse-admin http://127.0.0.1:8766 retry=0 nocanon
+	# ProxyPassReverse /synapse-admin http://127.0.0.1:8766
 
 	# Map /.well-known/matrix/client for client discovery
 	Alias /.well-known/matrix/client /matrix/static-files/.well-known/matrix/client
@@ -109,6 +120,7 @@ Listen 8448
 	ProxyPreserveHost On
 	ProxyRequests Off
 	ProxyVia On
+	RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 
 	# Proxy all remaining traffic to the Synapse port
 	# Beware: In this example the local traffic goes to the local synapse server at 127.0.0.1

examples/caddy/matrix-client-element

@@ -0,0 +1,8 @@
+https://element.DOMAIN {
+	# These might differ if you are supplying your own certificates
+	tls /matrix/ssl/config/live/element.DOMAIN/fullchain.pem /matrix/ssl/config/live/element.DOMAIN/privkey.pem
+
+	proxy / http://127.0.0.1:8765 {
+		transparent
+	}
+}

examples/caddy/matrix-riot-web

@@ -1,8 +0,0 @@
-https://riot.DOMAIN {
-	# These might differ if you are supplying your own certificates
-	tls /matrix/ssl/config/live/riot.DOMAIN/fullchain.pem /matrix/ssl/config/live/riot.DOMAIN/privkey.pem
-
-	proxy / http://127.0.0.1:8765 {
-		transparent
-	}
-}

examples/caddy/matrix-synapse

@@ -5,7 +5,7 @@ https://matrix.DOMAIN {
 
 	root /matrix/static-files
 
-	header {
+	header / {
 		Access-Control-Allow-Origin *
 		Strict-Transport-Security "mag=age=31536000;"
 		X-Frame-Options "DENY"
@@ -13,17 +13,19 @@ https://matrix.DOMAIN {
 	}
 
 	# Identity server traffic
-	proxy /_matrix/identity matrix-msisd:8090 {
+	proxy /_matrix/identity matrix-ma1sd:8090 {
 		transparent
 	}
-	proxy /_matrix/client/r0/user_directory/search matrix-msisd:8090 {
+	proxy /_matrix/client/r0/user_directory/search matrix-ma1sd:8090 {
 		transparent
 	}
 
 	# Synapse Client<>Server API
-	proxy / matrix-synapse:8008 {
+	proxy /_matrix matrix-synapse:8008 {
+		transparent
+		except /_matrix/identity/ /_matrix/client/r0/user_directory/search
+	}
+	proxy /_synapse/client matrix-synapse:8008 {
 		transparent
-		except /.well-known/ /_matrix/identity/ /_matrix/client/r0/user_directory/search
 	}
-
 }

examples/caddy2/Caddyfile

@@ -0,0 +1,234 @@
+matrix.DOMAIN.tld {
+
+  # creates letsencrypt certificate
+  # tls your@email.com
+
+  @identity {
+        path /_matrix/identity/*
+  }
+
+  @noidentity {
+        not path /_matrix/identity/*
+  }
+
+  @search {
+        path /_matrix/client/r0/user_directory/search/*
+  }
+
+  @nosearch {
+        not path /_matrix/client/r0/user_directory/search/*
+  }
+
+  @static {
+        path /matrix/static-files/*
+  }
+
+  @nostatic {
+        not path /matrix/static-files/*
+  }
+
+  @wellknown {
+        path /.well-known/matrix/*
+  }
+
+  header {
+        # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        # Enable cross-site filter (XSS) and tell browser to block detected attacks
+        X-XSS-Protection "1; mode=block"
+        # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
+        X-Content-Type-Options "nosniff"
+        # Disallow the site to be rendered within a frame (clickjacking protection)
+        X-Frame-Options "DENY"
+        # X-Robots-Tag
+        X-Robots-Tag "noindex, noarchive, nofollow"
+  }
+
+  # Cache
+  header @static {
+        # Cache
+    Cache-Control "public, max-age=31536000"
+    defer
+  }
+
+  # identity
+  handle @identity {
+        reverse_proxy localhost:8090  {
+               header_up X-Forwarded-Port {http.request.port}
+               header_up X-Forwarded-Proto {http.request.scheme}
+               header_up X-Forwarded-TlsProto {tls_protocol}
+               header_up X-Forwarded-TlsCipher {tls_cipher}
+               header_up X-Forwarded-HttpsProto {proto}
+        }
+  }
+
+  # search
+  handle @search {
+        reverse_proxy localhost:8090   {
+               header_up X-Forwarded-Port {http.request.port}
+               header_up X-Forwarded-Proto {http.request.scheme}
+               header_up X-Forwarded-TlsProto {tls_protocol}
+               header_up X-Forwarded-TlsCipher {tls_cipher}
+               header_up X-Forwarded-HttpsProto {proto}
+        }
+  }
+
+  handle @wellknown {
+        encode zstd gzip
+        root * /matrix/static-files
+	header Cache-Control max-age=14400
+        header Content-Type application/json
+        header Access-Control-Allow-Origin *
+        file_server
+  }
+
+  handle {
+        encode zstd gzip
+
+        reverse_proxy localhost:8008  {
+               header_up X-Forwarded-Port {http.request.port}
+               header_up X-Forwarded-Proto {http.request.scheme}
+               header_up X-Forwarded-TlsProto {tls_protocol}
+               header_up X-Forwarded-TlsCipher {tls_cipher}
+               header_up X-Forwarded-HttpsProto {proto}
+        }
+  }
+}
+
+matrix.DOMAIN.tld:8448 {
+    handle {
+        encode zstd gzip
+
+        reverse_proxy 127.0.0.1:8048 {
+               header_up X-Forwarded-Port {http.request.port}
+               header_up X-Forwarded-Proto {http.request.scheme}
+               header_up X-Forwarded-TlsProto {tls_protocol}
+               header_up X-Forwarded-TlsCipher {tls_cipher}
+               header_up X-Forwarded-HttpsProto {proto}
+        }
+    }
+}
+
+element.DOMAIN.tld {
+
+      # creates letsencrypt certificate
+      # tls your@email.com
+
+      header {
+                # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
+                Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+                # Enable cross-site filter (XSS) and tell browser to block detected attacks
+                X-XSS-Protection "1; mode=block"
+                # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
+                X-Content-Type-Options "nosniff"
+                # Disallow the site to be rendered within a frame (clickjacking protection)
+                X-Frame-Options "DENY"
+                # X-Robots-Tag
+                X-Robots-Tag "noindex, noarchive, nofollow"
+        }
+
+        handle {
+              encode zstd gzip
+
+              reverse_proxy localhost:8765 {
+                     header_up X-Forwarded-Port {http.request.port}
+                     header_up X-Forwarded-Proto {http.request.scheme}
+                     header_up X-Forwarded-TlsProto {tls_protocol}
+                     header_up X-Forwarded-TlsCipher {tls_cipher}
+                     header_up X-Forwarded-HttpsProto {proto}
+        }
+}
+
+#dimension.DOMAIN.tld {
+#
+#      # creates letsencrypt certificate
+#      # tls your@email.com
+#
+#      header {
+#          # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
+#          Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+#          # Enable cross-site filter (XSS) and tell browser to block detected attacks
+#          X-XSS-Protection "1; mode=block"
+#          # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
+#          X-Content-Type-Options "nosniff"
+#          # Disallow the site to be rendered within a frame (clickjacking protection)
+#          X-Frame-Options "DENY"
+#          # X-Robots-Tag
+#          X-Robots-Tag "noindex, noarchive, nofollow"
+#    }
+#
+#      handle {
+#          encode zstd gzip
+#
+#          reverse_proxy localhost:8184  {
+#                  header_up X-Forwarded-Port {http.request.port}
+#                  header_up X-Forwarded-Proto {http.request.scheme}
+#                  header_up X-Forwarded-TlsProto {tls_protocol}
+#                  header_up X-Forwarded-TlsCipher {tls_cipher}
+#                  header_up X-Forwarded-HttpsProto {proto}
+#          }
+#    }
+#}
+
+
+#jitsi.DOMAIN.tld {
+#
+#  creates letsencrypt certificate
+#  tls your@email.com
+#
+#  header {
+#        # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
+#        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+#
+#        # Enable cross-site filter (XSS) and tell browser to block detected attacks
+#        X-XSS-Protection "1; mode=block"
+#
+#        # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
+#        X-Content-Type-Options "nosniff"
+#
+#        # Disallow the site to be rendered within a frame (clickjacking protection)
+#        X-Frame-Options "SAMEORIGIN"
+#
+#        # Disable some features
+#        Feature-Policy "accelerometer 'none';ambient-light-sensor 'none'; autoplay 'none';camera 'none';encrypted-media 'none';focus-without-user-activation 'none'; geolocation 'none';gyroscope #'none';magnetometer 'none';microphone 'none';midi 'none';payment 'none';picture-in-picture 'none'; speaker 'none';sync-xhr 'none';usb 'none';vr 'none'"
+#
+#        # Referer
+#        Referrer-Policy "no-referrer"
+#
+#        # X-Robots-Tag
+#        X-Robots-Tag "none"
+#
+#        # Remove Server header
+#        -Server
+#  }
+#
+#  handle {
+#        encode zstd gzip
+#
+#        reverse_proxy 127.0.0.1:13080 {
+#               header_up X-Forwarded-Port {http.request.port}
+#               header_up X-Forwarded-Proto {http.request.scheme}
+#               header_up X-Forwarded-TlsProto {tls_protocol}
+#               header_up X-Forwarded-TlsCipher {tls_cipher}
+#               header_up X-Forwarded-HttpsProto {proto}
+#        }
+#  }
+#}
+#DOMAIN.com {
+# Uncomment this if you are following "(Option 3): Setting up reverse-proxying of the well-known files from the base domain's server to the Matrix server" of https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-well-known.md#option-3-setting-up-reverse-proxying-of-the-well-known-files-from-the-base-domains-server-to-the-matrix-server
+#    @wellknown {
+#        path /.well-known/matrix/*
+#    }
+#
+#    handle @wellknown {
+#        reverse_proxy https://matrix.DOMAIN.com {
+#            header_up Host {http.reverse_proxy.upstream.hostport}
+#        }
+#    }
+#    # Configration for the base domain goes here
+#   # handle {
+#   #    header -Server
+#   #     encode zstd gzip
+#   #    reverse_proxy localhost:4020
+#   # }
+#}

examples/caddy2/README.md

@@ -0,0 +1,12 @@
+# Caddyfile
+
+This directory contains sample files that show you how to do reverse-proxying using Caddy2.
+
+## Config
+
+| Variable           | Function |
+| ------------------ | -------- |
+| tls your@email.com | Specify an email address for your [ACME account](https://caddyserver.com/docs/caddyfile/directives/tls) (but if only one email is used for all sites, we recommend the email [global option](https://caddyserver.com/docs/caddyfile/options) instead) | 
+| tls                | To enable [tls](https://caddyserver.com/docs/caddyfile/directives/tls) support uncomment the lines for tls |
+| Dimension         | To enable Dimension support uncomment the lines for Dimension and set your data |
+| Jitsi              | To enable Jitsi support uncomment the lines for Jitsi and set your data |

examples/haproxy/docker-compose.yml

@@ -1,7 +1,8 @@
+---
 version: '3'
 services:
   nginx:
-    image: local/nginx 
+    image: local/nginx
     ports:
       - 40888:80
     volumes:

examples/haproxy/haproxy.cfg

@@ -39,7 +39,7 @@ frontend https-frontend
     # HAproxy wants the full chain and the private key in one file. For Letsencrypt manually generated certs (e.g., wildcard certs) you can use
     # cat /etc/letsencrypt/live/example.com/fullchain.pem /etc/letsencrypt/live/example.com/privkey.pem > /etc/haproxy/certs/star-example.com.pem
     bind *:443 ssl crt /etc/haproxy/certs/star-example.com.pem
-    #bind *:443 ssl crt /etc/haproxy/certs/riot.example.com.pem /etc/haproxy/certs/matrix.example.com.pem
+    #bind *:443 ssl crt /etc/haproxy/certs/element.example.com.pem /etc/haproxy/certs/matrix.example.com.pem
     reqadd X-Forwarded-Proto:\ https
     option httplog
     option http-server-close
@@ -60,10 +60,10 @@ frontend https-frontend
     acl synapse_admin path -i -m beg /_synapse/admin
     # Send to :8008
     use_backend matrix-main if matrix_path or synapse_admin
-    # riot.example.com
-    acl riot_domain hdr_dom(host) -i riot.example.com
+    # element.example.com
+    acl element_domain hdr_dom(host) -i element.example.com
     # Send to 8765
-    use_backend riot if riot_domain 
+    use_backend element if element_domain
     # If nothing else match, just send to default matrix backend
     use_backend matrix-main if matrix_domain
     #default_backend matrix-main
@@ -86,12 +86,12 @@ backend synapse
 
 backend nginx-static
      capture request header origin len 128
-     http-response add-header Access-Control-Allow-Origin * 
+     http-response add-header Access-Control-Allow-Origin *
      rspadd Access-Control-Allow-Methods:\ GET,\ HEAD,\ OPTIONS,\ POST,\ PUT  if { capture.req.hdr(0) -m found }
      rspadd Access-Control-Allow-Credentials:\ true  if { capture.req.hdr(0) -m found }
      rspadd Access-Control-Allow-Headers:\ Origin,\ Accept,\ X-Requested-With,\ Content-Type,\ Access-Control-Request-Method,\ Access-Control-Request-Headers,\ Authorization  if { capture.req.hdr(0) -m found }
      server nginx 127.0.0.1:40888 check
 
-backend riot
-     server riot 127.0.0.1:8765 check
+backend element
+     server element 127.0.0.1:8765 check