Merge branch 'master' into pub.solar

Update frenck/action-yamllint action to v1.4.2

.config/ansible-lint.yml

@@ -9,6 +9,7 @@ skip_list:
   - schema
   - command-instead-of-shell
   - role-name
+  - var-naming[no-role-prefix]
   # We frequently load configuration from a template (into a variable), then merge that with another variable (configuration extension)
   # before finally dumping it to a file.
   - template-instead-of-copy

.editorconfig

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

.envrc

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

.gitattributes

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

.github/renovate.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
+	"extends": [
+		"config:base"
+	],
+	"regexManagers": [
+		{
+			"fileMatch": ["defaults/main.yml$"],
+			"matchStrings": [
+				"# renovate: datasource=(?<datasource>[a-z-.]+?) depName=(?<depName>[^\\s]+?)(?: (?:lookupName|packageName)=(?<packageName>[^\\s]+?))?(?: versioning=(?<versioning>[a-z-0-9]+?))?\\s+[A-Za-z0-9_]+?(?:_version|_tag)\\s*:\\s*[\"']?(?<currentValue>.+?)[\"']?\\s"
+			]
+		}
+	]
+}

.github/workflows/matrix.yml

@@ -11,16 +11,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Run yamllint
-        uses: frenck/action-yamllint@v1.3.1
+        uses: frenck/action-yamllint@v1.4.2
   ansible-lint:
     name: ansible-lint
     runs-on: ubuntu-latest
     steps:
       - name: Check out
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Run ansible-lint
-        uses: ansible-community/ansible-lint-action@v6.8.2
+        uses: ansible-community/ansible-lint-action@v6.17.0
         with:
           path: roles/custom

.gitignore

@@ -5,6 +5,9 @@
 /roles/**/files/scratchpad
 .DS_Store
 .python-version
+.idea/
+flake.lock
+.direnv
 
 # ignore roles pulled by ansible-galaxy
 /roles/galaxy/*

CHANGELOG.md

@@ -1,3 +1,600 @@
+# 2023-10-23
+
+## Enabling `allow_public_rooms_over_federation` by default for Synapse
+
+**TDLR**: if your Matrix server is federating (which it mostly likely is, unless you've [disabled federation](docs/configuring-playbook-federation.md#disabling-federation)), your public rooms will not only be joinable across federation (as they've always been), but from now on will be discoverable (made available as a list across federation). We're changing this by flipping the value for Synapse's `allow_public_rooms_over_federation` setting to `true`, going against the upstream default. Servers that disable federation are not affected. Servers that have public rooms which are not published to the room directory are also not affected.
+
+We generally try to stick to the default configuration for Synapse (and all other components), unless these defaults seem wrong or harmful. One such previous case from a few months ago was us [Enabling `forget_rooms_on_leave` by default for Synapse](#enabling-forget_rooms_on_leave-by-default-for-synapse) - the default value was making Synapse more wasteful of resources by default.
+
+Today, we're going against upstream defaults again and flipping the `allow_public_rooms_over_federation` configuration option to `true`.
+This way, public rooms on your server will be made discoverable by others via federation, using the [`GET /_matrix/federation/v1/publicRooms` of the Server-Server API](https://spec.matrix.org/v1.8/server-server-api/#get_matrixfederationv1publicrooms).
+
+The upstream Synapse default is `false` (disabled), so that public rooms are not exposed for other servers to discover (learn about their existence). Nevertheless, even if these rooms are not exposed (listed) for discovery, they are **still joinable** by anyone who knows their address or is invited to the room by an existing member.
+
+**We go against the upstream default** in an effort to make Matrix federation more useful - a public room should be globally public - not only joinable, but also discoverable across federation.
+
+The **historical reasoning** behind this change is as follows:
+
+- `allow_public_rooms_over_federation` seems to have been enabled by default for Synapse until v1.7.0 (~2019), just like we believe it should be for a globally-federating network - rooms should be joinable and discoverable across federation.
+
+- In Synapse v1.7.0 (~2019), `allow_public_rooms_over_federation` [got disabled](https://github.com/matrix-org/synapse/blob/e9069c9f919685606506f04527332e83fbfa44d9/docs/upgrade.md?plain=1#L1877-L1891) by default in a [security-by-obscurity](https://en.wikipedia.org/wiki/Security_through_obscurity) workaround for misconfigured servers. See the [Avoiding unwelcome visitors on private Matrix servers](https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers/) `matrix.org` blog article. We believe that people wishing for a truly private server, should [disable federation](docs/configuring-playbook-federation.md#disabling-federation), instead of having a fully-federating server and trying to hide its public rooms. We also provide other workarounds below. We (and the Synapse team, obviously) believe that Matrix should federate by default, so federating the public room list seems to make sense.
+
+- [etke.cc](https://etke.cc/) has been developing the free-software [Matrix Rooms Search](https://gitlab.com/etke.cc/mrs) project for a while now. One public (demo) instance of it is hosted at [matrixrooms.info](https://matrixrooms.info/). This search engine tries to go through the Matrix federation and discover & index public rooms to allow people to find them. We believe it's vital for Matrix (and any chat or social network for that matter) to be more discoverable, so that people can find communities and others to talk to. Today (on 23rd of October 2023), `matrixrooms.info` is indexing `23066` Matrix servers. Of these, only `1567` servers (7%) are making their public rooms discoverable. Who knows what wonderful communities and rooms are available on these 93% other Matrix servers that are supposedly federating, but are still gate-keeping their public room list. Indubitably, many of these servers are hosted via matrix-docker-ansible-deploy, so we feel partially responsible for making Matrix federation less useful.
+
+Here are **actions you may wish to take** as a result of this change:
+
+- (recommended) embrace the new default. If your Matrix server is federating, your public rooms have always been joinable across federation anyway. Exposing the list of public rooms does no harm and more-so does good by contributing to the usefulness of the Matrix network by facilitating room discovery.
+
+- (switch to a better way of doings things on your semi-private server) The problem that the Synapse team appears to have solved by flipping the `allow_public_rooms_over_federation` default in Synapse v1.7.0 seems to for "mostly private" servers, which federate and have a bunch of rooms made public (and published in their room directory) in an effort to allow people on the same homeserver to easily find and join them (self-onboarding). With the introduction of Matrix Spaces, you can reorganize your flow around spaces - you can auto-join your users to a Matrix Space (via Synapse's `auto_join_rooms` setting - controlled by our `matrix_synapse_auto_join_rooms` variable), then add a bunch of rooms to the space and make them joinable by people belonging to the space. That is to say, do not make rooms public and do not publish them to the room directory unless they are really public. Instead, use other mechanisms for semi-public rooms or private rooms. One alternative is to stick to what you're doing (public rooms published to your rooms directory) but having a `m.federate: true` flag set during creation (clients like Element have a nice UI checkbox for this) to explicitly disable federation for them.
+
+- (keeping the old behavior) if you wish to keep doing what you're doing (keeping your Matrix server federating, but hiding its public rooms list), add `matrix_synapse_allow_public_rooms_over_federation: false` to your `vars.yml` configuration. This restores the old behavior. You may also consider [disabling federation](docs/configuring-playbook-federation.md#disabling-federation) completely instead of relying on security-by-obscurity measures.
+
+
+# 2023-10-18
+
+## Postgres parameters are automatically tuned now
+
+The playbook has provided some hints about [Tuning PostgreSQL](docs/maintenance-postgres.md#tuning-postgresql) for quite a while now.
+
+From now on, the [Postgres Ansible role](https://github.com/devture/com.devture.ansible.role.postgres) automatically tunes your Postgres configuration with the same [calculation logic](https://github.com/le0pard/pgtune/blob/master/src/features/configuration/configurationSlice.js) that powers https://pgtune.leopard.in.ua/.
+
+Our [Tuning PostgreSQL](docs/maintenance-postgres.md#tuning-postgresql) documentation page has details about how you can turn auto-tuning off or adjust the automatically-determined Postgres configuration parameters manually.
+
+People who [enable load-balancing with Synapse workers](docs/configuring-playbook-synapse.md#load-balancing-with-workers) no longer need to increase the maximum number of Postgres connections manually (previously done via `devture_postgres_process_extra_arguments`). There's a new variable (`devture_postgres_max_connections`) for controlling this number and the playbook automatically raises its value from `200` to `500` for setups which enable workers.
+
+
+# 2023-08-31
+
+## SchildiChat support
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up the [SchildiChat](https://github.com/SchildiChat/schildichat-desktop) client.
+
+See our [Configuring SchildiChat](docs/configuring-playbook-client-schildichat.md) documentation to get started.
+
+
+# 2023-08-23
+
+## mautrix-wsproxy support
+
+Thanks to [Johan Swetzén](https://github.com/jswetzen)'s efforts (who finished what was started by [James Reilly](https://github.com/hanthor) and [Shreyas Ajjarapu](https://github.com/shreyasajj)), the playbook now supports bridging to Android SMS and Apple iMessage via the [mautrix-wsproxy](https://github.com/mautrix/wsproxy) service (in combination with a [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android phone).
+
+See our [Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage](docs/configuring-playbook-bridge-mautrix-wsproxy.md) documentation page for getting started.
+
+
+# 2023-07-24
+
+## matrix-registration-bot usage changed
+
+[matrix-registration-bot](docs/configuring-playbook-bot-matrix-registration-bot.md) got some updates and now supports password-only-based login. Therefore the bot now doesn't need any manual configuration except setting a password in your `vars.yml`. The bot will be registered as admin and access tokens will be obtained automatically by the bot.
+
+**For existing users** You need to set `matrix_bot_matrix_registration_bot_bot_password` if you previously only used `matrix_bot_matrix_registration_bot_bot_access_token`. Please also remove the following deprecated settings
+
+* `matrix_bot_matrix_registration_bot_bot_access_token`
+* `matrix_bot_matrix_registration_bot_api_token`
+
+
+# 2023-07-21
+
+## mautrix-gmessages support
+
+Thanks to [Shreyas Ajjarapu](https://github.com/shreyasajj)'s efforts, the playbook now supports bridging to [Google Messages](https://messages.google.com/) via the [mautrix-gmessages](https://github.com/mautrix/gmessages) bridge. See our [Setting up Mautrix Google Messages bridging](docs/configuring-playbook-bridge-mautrix-gmessages.md) documentation page for getting started.
+
+
+# 2023-07-17
+
+## matrix-media-repo support
+
+Thanks to [Michael Hollister](https://github.com/Michael-Hollister) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook can now set up [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) - an alternative way to store homeserver media files, powered by a homeserver-independent implementation which supports S3 storage, IPFS, deduplication and other advanced features.
+
+To learn more see our [Storing Matrix media files using matrix-media-repo](docs/configuring-playbook-matrix-media-repo.md) documentation page.
+
+
+# 2023-05-25
+
+## Enabling `forget_rooms_on_leave` by default for Synapse
+
+With the [Synapse v1.84.0 update](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2698), we've also **changed the default value** of the `forget_rooms_on_leave` setting of Synapse to a value of `true`.
+This way, **when you leave a room, Synapse will now forget it automatically**.
+
+The upstream Synapse default is `false` (disabled), so that you must forget rooms manually after leaving.
+
+**We go against the upstream default** ([somewhat controversially](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2700)) in an effort to make Synapse leaner and potentially do what we believe most users would expect their homeserver to be doing.
+
+If you'd like to go back to the old behavior, add the following to your configuration: `matrix_synapse_forget_rooms_on_leave: false`
+
+
+# 2023-04-03
+
+## The matrix-jitsi role lives independently now
+
+**TLDR**: the `matrix-jitsi` role is now included from the [ansible-role-jitsi](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi) repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook). Some variables have been renamed. All functionality remains intact.
+
+The `matrix-jitsi` role has been relocated in its own repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) project - an Ansible playbook for self-hosting [a growing list of FOSS software](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md). If hosting a Jitsi stack on the Matrix server itself did not stand right with you or you always wanted to host most stuff, you can now use this new playbook to do so.
+
+As part of the extraction process of this role out of the Matrix playbook, a few other things improved:
+
+- **native Traefik support** has been added
+- **support for hosting under a subpath** has been added, although it suffers from a few minor issues listed [here](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/jitsi.md#url)
+
+You need to **update your roles** (`just roles` or `make roles`) regardless of whether you're using Jitsi or not.
+
+If you're making use of Jitsi via this playbook, you will need to update variable references in your `vars.yml` file:
+
+  - `matrix_jitsi_*_docker_image_` -> `matrix_jitsi_*_container_image_`
+  - `matrix_jitsi_` -> `jitsi_`
+  - some other internal variables have changed, but the playbook will tell you about them
+
+# 2023-03-22
+
+## ntfy Web App is disabled by default
+
+ntfy provides a web app, which is now disabled by default, because it may be unknown to and unused by most users of this playbook. You can enable it by setting `ntfy_web_root: "app"` (see [ntfy documentation](docs/configuring-playbook-ntfy.md)).
+
+This change was already applied a while before this entry, but as some users were reporting the missing web app, this entry was added (see [#2529](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2529)).
+
+
+# 2023-03-21
+
+## The matrix-prometheus role lives independently now
+
+**TLDR**: the `matrix-prometheus` role is now included from the [ansible-role-prometheus](https://github.com/mother-of-all-self-hosting/ansible-role-prometheus) repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook). Some variables have been renamed. All functionality remains intact.
+
+The `matrix-prometheus` role has been relocated in its own repository, part of the [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) project - an Ansible playbook for self-hosting [a growing list of FOSS software](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md). If hosting a Prometheus stack on the Matrix server itself did not stand right with you or you always wanted to host most stuff, you can now use this new playbook to do so.
+
+Extracting the Prometheus role out of this Matrix playbook required huge internal refactoring to the way the Prometheus configuration (scraping jobs) is generated. If you notice any breakage after upgrading, let us know.
+
+You need to **update your roles** (`just roles` or `make roles`) regardless of whether you're using Prometheus or not.
+
+If you're making use of Prometheus via this playbook, you will need to update variable references in your `vars.yml` file:
+
+  - `matrix_prometheus_docker_image_` -> `matrix_prometheus_container_image_`
+  - `matrix_prometheus_` -> `prometheus_`
+  - some other internal variables have changed, but the playbook will tell you about them
+
+
+# 2023-03-12
+
+## synapse-auto-compressor support
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up [rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state)'s `synapse_auto_compressor` tool to run periodically.
+
+If enabled, `synapse_auto_compressor` runs on a schedule and compresses your Synapse database's `state_groups` table. It was possible to run `rust-synapse-compress-state` manually via the playbook even before - see [Compressing state with rust-synapse-compress-state](docs/maintenance-synapse.md#compressing-state-with-rust-synapse-compress-state). However, using `synapse_auto_compressor` is better, because:
+
+- it runs on a more up-to-date version of `rust-synapse-compress-state`
+- it's a set-it-and-forget-it tool that you can enable and never have to deal with manual compression anymore
+
+This tool needs to be enabled manually, for now. In the future, we're considering enabling it by default for all Synapse installations.
+
+See our [Setting up synapse-auto-compressor](docs/configuring-playbook-synapse-auto-compressor.md) documentation to get started.
+
+
+# 2023-03-07
+
+## Sliding Sync Proxy (Element X) support
+
+Thanks to [Benjamin Kampmann](https://github.com/gnunicorn) for [getting it started](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2515), [FSG-Cat](https://github.com/FSG-Cat) for fixing it up and me ([Slavi](https://github.com/spantaleev)) for polishing it up, the playbook can now install and configure the [sliding-sync proxy](https://github.com/matrix-org/sliding-sync).
+
+The upcoming Element X clients ([Element X iOS](https://github.com/vector-im/element-x-ios) and [Element X Android](https://github.com/vector-im/element-x-android)) require the `sliding-sync` proxy to do their job. **These clients are still in beta** (especially Element X Android, which requires manual compilation to get it working with a non-`matrix.org` homeseserver). Playbook users can now easily give these clients a try and help test them thanks to us having `sliding-sync` support.
+
+To get started, see our [Setting up Sliding Sync Proxy](docs/configuring-playbook-sliding-sync-proxy.md) documentation page.
+
+
+# 2023-03-02
+
+## The matrix-etherpad role lives independently now
+
+**TLDR**: the `matrix-etherpad` role is now included from [another repository](https://gitlab.com/etke.cc/roles/etherpad). Some variables have been renamed. All functionality remains intact.
+
+You need to **update your roles** (`just roles` or `make roles`) regardless of whether you're using Etherpad or not.
+
+If you're making use of Etherpad via this playbook, you will need to update variable references in your `vars.yml` file:
+
+- Rename `matrix_etherpad_public_endpoint` to `etherpad_path_prefix`
+
+- Replace `matrix_etherpad_mode: dimension` with:
+  - for `matrix-nginx-proxy` users:
+    - `etherpad_nginx_proxy_dimension_integration_enabled: true`
+    - `etherpad_hostname: "{{ matrix_server_fqn_dimension }}"`
+  - for Traefik users:
+    - define your own `etherpad_hostname` and `etherpad_path_prefix` as you see fit
+
+- Rename all other variables:
+  - `matrix_etherpad_docker_image_` -> `matrix_etherpad_container_image_`
+  - `matrix_etherpad_` -> `etherpad_`
+
+Along with this relocation, the new role also:
+
+- supports [self-building](docs/self-building.md), so it should work on `arm32` and `arm64` architectures
+- has native Traefik reverse-proxy support (Etherpad requests no longer go through `matrix-nginx-proxy` when using Traefik)
+
+
+# 2023-02-26
+
+## Traefik is the default reverse-proxy now
+
+**TLDR**: new installations will now default to Traefik as their reverse-proxy. Existing users need to explicitly choose their reverse-proxy type. [Switching to Traefik](#how-do-i-switch-my-existing-setup-to-traefik) is strongly encouraged. `matrix-nginx-proxy` may break over time and will ultimately be removed.
+
+As mentioned 2 weeks ago in [(Backward Compatibility) Reverse-proxy configuration changes and initial Traefik support](#backward-compatibility-reverse-proxy-configuration-changes-and-initial-traefik-support), the playbook is moving to Traefik as its default SSL-terminating reverse-proxy.
+
+Until now, we've been doing the migration gradually and keeping full backward compatibility. New installations were defaulting to `matrix-nginx-proxy` (just like before), while existing installations were allowed to remain on `matrix-nginx-proxy` as well. This makes things very difficult for us, because we need to maintain and think about lots of different setups:
+
+- Traefik managed by the playbook
+- Traefik managed by the user in another way
+- another reverse-proxy on the same host (`127.0.0.1` port exposure)
+- another reverse-proxy on another host (`0.0.0.0` port exposure)
+- `matrix-nginx-proxy` - an `nginx` container managed by the playbook
+- `nginx` webserver operated by the user, running without a container on the same server
+
+Each change we do and each new feature that comes in needs to support all these different ways of reverse-proxying. Because `matrix-nginx-proxy` was the default and pretty much everyone was (and still is) using it, means that new PRs also come with `matrix-nginx-proxy` as their main focus and Traefik as an afterthought, which means we need to spend hours fixing up Traefik support.
+
+We can't spend all this time maintaining so many different configurations anymore. Traefik support has been an option for 2 weeks and lots of people have  already migrated their server and have tested things out. Traefik is what we use and preferentially test for.
+
+It's time for the **next step in our migration process** to Traefik and elimination of `matrix-nginx-proxy`:
+
+- Traefik is now the default reverse-proxy for new installations
+- All existing users need to explicitly choose their reverse-proxy type by defining the `matrix_playbook_reverse_proxy_type` variable in their `vars.yml` configuration file. We strongly encourage existing users to [switch the Traefik](#how-to-switch-an-existing-setup-to-traefik), as the nginx setup is bound to become more and more broken over time until it's ultimately removed
+
+### How do I switch my existing setup to Traefik?
+
+**For users who are on `matrix-nginx-proxy`** (the default reverse-proxy provided by the playbook), switching to Traefik can happen with a simple configuration change. Follow this section from 2 weeks ago: [How do I explicitly switch to Traefik right now?](#how-do-i-explicitly-switch-to-traefik-right-now).
+
+If you experience trouble:
+
+1. Follow [How do I remain on matrix-nginx-proxy?](#how-do-i-remain-on-matrix-nginx-proxy) to bring your server back online using the old reverse-proxy
+2. Ask for help in our [support channels](README.md#support)
+3. Try switching to Traefik again later
+
+**For users with a more special reverse-proxying setup** (another nginx server, Apache, Caddy, etc.), the migration may not be so smooth. Follow the [Using your own webserver](docs/configuring-playbook-own-webserver.md) guide. Ideally, your custom reverse-proxy will be configured in such a way that it **fronts the Traefik reverse-proxy** provided by the playbook. Other means of reverse-proxying are more fragile and may be deprecated in the future.
+
+### I already use my own Traefik server. How do I plug that in?
+
+See the [Traefik managed by the playbook](docs/configuring-playbook-own-webserver.md#traefik-managed-by-the-playbook) section.
+
+### Why is matrix-nginx-proxy used even after switching to Traefik?
+
+This playbook manages many different services. All these services were initially integrated with `matrix-nginx-proxy`.
+
+While we migrate all these components to have native Traefik support, some still go through nginx internally (Traefik -> local `matrix-nginx-proxy` -> component).
+As time goes on, internal reliance on `matrix-nginx-proxy` will gradually decrease until it's completely removed.
+
+### How do I remain on matrix-nginx-proxy?
+
+Most new work and testing targets Traefik, so remaining on nginx is **not** "the good old stable" option, but rather the "still available, but largely untested and likely to be broken very soon" option.
+
+To proceed regardless of this warning, add `matrix_playbook_reverse_proxy_type: playbook-managed-nginx` to your configuration.
+
+At some point in the **near** future (days, or even weeks at most), we hope to completely get rid of `matrix-nginx-proxy` (or break it enough to make it unusable), so you **will soon be forced to migrate** anyway. Plan your migration accordingly.
+
+### How do I keep using my own other reverse-proxy?
+
+We recommend that you follow the guide for [Fronting the integrated reverse-proxy webserver with another reverse-proxy](docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy).
+
+
+# 2023-02-25
+
+## Rageshake support
+
+Thanks to [Benjamin Kampmann](https://github.com/gnunicorn), the playbook can now install and configure the [Rageshake](https://github.com/matrix-org/rageshake) bug report server.
+
+Additional details are available in [Setting up Rageshake](docs/configuring-playbook-rageshake.md).
+
+
+# 2023-02-17
+
+## Synapse templates customization support
+
+The playbook can now help you customize Synapse's templates.
+
+Additional details are available in the [Customizing templates](docs/configuring-playbook-synapse.md#customizing-templates) section of our Synapse documentation.
+
+## The matrix-redis role lives independently now
+
+**TLDR**: the `matrix-redis` role is now included from another repository. Some variables have been renamed. All functionality remains intact.
+
+The `matrix-redis` role (which configures [Redis](https://redis.io/)) has been extracted from the playbook and now lives in its [own repository](https://gitlab.com/etke.cc/roles/redis). This makes it possible to easily use it in other Ansible playbooks.
+
+You need to **update your roles** (`just roles` or `make roles`) regardless of whether you're enabling Ntfy or not. If you're making use of Ntfy via this playbook, you will need to update variable references in your `vars.yml` file (`matrix_redis_` -> `redis_`).
+
+## The matrix-ntfy role lives independently now
+
+**TLDR**: the `matrix-ntfy` role is now included from another repository. Some variables have been renamed. All functionality remains intact.
+
+The `matrix-ntfy` role (which configures [Ntfy](https://ntfy.sh/)) has been extracted from the playbook and now lives in its [own repository](https://gitlab.com/etke.cc/roles/ntfy). This makes it possible to easily use it in other Ansible playbooks.
+
+You need to **update your roles** (`just roles` or `make roles`) regardless of whether you're enabling Ntfy or not. If you're making use of Ntfy via this playbook, you will need to update variable references in your `vars.yml` file (`matrix_ntfy_` -> `ntfy_`).
+
+
+# 2023-02-15
+
+## The matrix-grafana role lives independently now
+
+**TLDR**: the `matrix-grafana` role is now included from another repository. Some variables have been renamed. All functionality remains intact.
+
+The `matrix-grafana` role (which configures [Grafana](docs/configuring-playbook-prometheus-grafana.md)) has been extracted from the playbook and now lives in its [own repository](https://gitlab.com/etke.cc/roles/grafana). This makes it possible to easily use it in other Ansible playbooks.
+
+You need to **update your roles** (`just roles` or `make roles`) regardless of whether you're enabling Grafana or not. If you're making use of Grafana via this playbook, you will need to update variable references in your `vars.yml` file (`matrix_grafana_` -> `grafana_`).
+
+
+# 2023-02-13
+
+## The matrix-backup-borg role lives independently now
+
+**TLDR**: the `matrix-backup-borg` role is now included from another repository. Some variables have been renamed. All functionality remains intact.
+
+Thanks to [moan0s](https://github.com/moan0s), the `matrix-backup-borg` role (which configures [Borg backups](docs/configuring-playbook-backup-borg.md)) has been extracted from the playbook and now lives in its [own repository](https://gitlab.com/etke.cc/roles/backup_borg). This makes it possible to easily use it in other Ansible playbooks and will become part of [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy) soon.
+
+You need to **update your roles** (`just roles` or `make roles`) regardless of whether you're enabling Borg backup functionality or not. If you're making use of Borg backups via this playbook, you will need to update variable references in your `vars.yml` file (`matrix_backup_borg_` -> `backup_borg_`).
+
+
+# 2023-02-12
+
+## (Backward Compatibility) Reverse-proxy configuration changes and initial Traefik support
+
+**TLDR**:
+
+- there's a new `matrix_playbook_reverse_proxy_type` variable (see [roles/custom/matrix-base/defaults/main.yml](roles/custom/matrix-base/defaults/main.yml)), which lets you tell the playbook what reverse-proxy setup you'd like to have. This makes it easier for people who want to do reverse-proxying in other ways.
+- the default reverse-proxy (`matrix_playbook_reverse_proxy_type`) is still `playbook-managed-nginx` (via `matrix-nginx-proxy`), for now. **Existing `matrix-nginx-proxy` users should not observe any changes** and can stay on this for now.
+- **Users who use their [own other webserver](docs/configuring-playbook-own-webserver.md) (e.g. Apache, etc.) need to change** `matrix_playbook_reverse_proxy_type` to something like `other-on-same-host`, `other-on-another-host` or `other-nginx-non-container`
+- we now have **optional [Traefik](https://traefik.io/) support**, so you could easily host Matrix and other Traefik-native services in containers on the same server. Traefik support is still experimental (albeit, good enough) and will improve over time. It does work, but certain esoteric features may not be there yet.
+- **Traefik will become the default reverse-proxy in the near future**. `matrix-nginx-proxy` will either remain as an option, or be completely removed to simplify the playbook
+
+### Motivation for redoing our reverse-proxy setup
+
+The playbook has supported various reverse-proxy setups for a long time.
+We have various configuration variables (`matrix_nginx_proxy_enabled`, various `_host_bind_port` variables, etc.) which allow the playbook to adapt to these different setups. The whole situation was messy though - hard to figure out and with lots of variables to toggle to make things work as you'd expect - huge **operational complexity**.
+
+We love containers, proven by the fact that **everything** that this playbook manages runs in a container. Yet, we weren't allowing people to easily host other web-exposed containers alongside Matrix services on the same server. We were using `matrix-nginx-proxy` (our integrated [nginx](https://nginx.org/) server), which was handling web-exposure and SSL termination for our own services, but we **weren't helping you with all your other containers**.
+
+People who were **using `matrix-nginx-proxy`** were on the happy path on which everything worked well by default (Matrix-wise), **but** could not easily run other web-exposed services on their Matrix server because `matrix-nginx-proxy` was occupying ports `80` and `443`. Other services which wanted to get web exposure either had to be plugged into `matrix-nginx-proxy` (somewhat difficult) or people had to forgo using `matrix-nginx-proxy` in favor of something else.
+
+Of those that decided to forgo `matrix-nginx-proxy`, many were **using nginx** on the same server without a container. This was likely some ancient nginx version, depending on your choice of distro. The Matrix playbook was trying to be helpful and even with `matrix_nginx_proxy_enabled: false` was still generating nginx configuration in `/matrix/nginx-proxy/conf.d`. Those configuration files were adapted for inclusion into an nginx server running locally. Disabling the `matrix-nginx-proxy` role like this, yet still having it produce files is a bit disgusting, but it's what we've had since the early beginnings of this playbook.
+
+Others still, wanted to run Matrix locally (no SSL certificates), regardless of which web server technology this relied on, and then **reverse-proxy from another machine on the network** which was doing SSL termination. These people were:
+
+- *either* relying on `matrix_nginx_proxy_enabled: false` as well, combined with exposing services manually (setting `_bind_port` variables)
+- *or* better yet, they were keeping `matrix-nginx-proxy` enabled, but in `http`-only mode (no SSL certificate retrieval).
+
+Despite this operational complexity, things worked and were reasonably flexible to adapt to all these situations.
+
+When using `matrix-nginx-proxy` as is, we still had another problem - one of **internal playbook complexity**. Too many services need to be web-exposed (port 80/443, SSL certificates). Because of this, they all had to integrate with the `matrix-nginx-proxy` role. Tens of different roles explicitly integrating with `matrix-nginx-proxy` is not what we call clean. The `matrix-nginx-proxy` role contains variables for many of these roles (yikes). Other roles were more decoupled from it and were injecting configuration into `matrix-nginx-proxy` at runtime - see all the `inject_into_nginx_proxy.yml` task files in this playbook (more decoupled, but still.. yikes).
+
+The next problem is one of **efficiency, interoperability and cost-saving**. We're working on other playbooks:
+
+- [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy) for hosting the [Vaultwarden](https://github.com/dani-garcia/vaultwarden) server - an alternative implementation of the [Bitwarden](https://bitwarden.com/) password manager
+- [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy) - for hosting the [Gitea](https://gitea.io/) git source code hosting service
+- [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy) - for hosting the [Nextcloud](https://nextcloud.com/) groupware platform
+
+We'd love for users to be able to **seamlessly use all these playbooks (and others, even) against a single server**. We don't want `matrix-nginx-proxy` to have a monopoly on port `80`/`443` and make it hard for other services to join in on the party. Such a thing forces people into running multiple servers (one for each service), which does provide nice security benefits, but is costly and ineffiecient. We'd like to make self-hosting these services cheap and easy.
+
+These other playbooks have been using [Traefik](https://traefik.io/) as their default reverse-proxy for a long time. They can all coexist nicely together (as an example, see the [Interoperability](https://github.com/spantaleev/nextcloud-docker-ansible-deploy/blob/master/docs/configuring-playbook-interoperability.md) documentation for the [Nextcloud playbook](https://github.com/spantaleev/nextcloud-docker-ansible-deploy)). Now that this playbook is gaining Traefik support, it will be able to interoperate with them. If you're going this way, make sure to have the Matrix playbook install Traefik and have the others use `*_reverse_proxy_type: other-traefik-container`.
+
+Finally, at [etke.cc - a managed Matrix server hosting service](https://etke.cc) (built on top of this playbook, and coincidentally [turning 2 years old today](https://etke.cc/news/upsyw4ykbtgmwhz8k7ukldx0zbbfq-fh0iqi3llixi0/) 🎉), we're allowing people to host some additional services besides Matrix components. Exposing these services to the web requires ugly hacks and configuration files being dropped into `/matrix/nginx-proxy/conf.d`. We believe that everything should run in independent containers and be exposed to the web via a Traefik server, without a huge Ansible role like `matrix-nginx-proxy` that everything else needs to integrate with.
+
+### How do these changes fix all these problems?
+
+The new `matrix_playbook_reverse_proxy_type` lets you easily specify your preferred reverse-proxy type, including `other-on-same-host`, `other-on-another-host` and `none`, so people who'd like to reverse-proxy with their own web server have more options now.
+
+Using Traefik greatly simplifies things, so going forward we'll have a simpler and easier to maintain playbook, which is also interoperable with other services.
+
+Traefik is a web server, which has been specifically **designed for reverse-proxying to services running in containers**. It's ideal for usage in an Ansible playbook which runs everything in containers.
+
+**Traefik obtains SSL certificates automatically**, so there's no need for plugging additional tools like [Certbot](https://certbot.eff.org/) into your web server (like we were doing in the `matrix-nginx-proxy` role). No more certificate renewal timers, web server reloading timers, etc. It's just simpler.
+
+Traefik is a **modern web server**. [HTTP/3](https://doc.traefik.io/traefik/routing/entrypoints/#http3) is supported already (experimentally) and will move to stable soon, in the upcoming Traefik v3 release.
+
+Traefik does not lock important functionality we'd like to use into [plus packages like nginx does](https://www.nginx.com/products/nginx/), leading us to resolve to configuration workarounds. The default Traefik package is good enough as it is.
+
+### Where we're at right now?
+
+`matrix_playbook_reverse_proxy_type` still defaults to a value of `playbook-managed-nginx`.
+
+Unless we have some regression, **existing `matrix-nginx-proxy` users should be able to update their Matrix server and not observe any changes**. Their setup should still remain on nginx and everything should still work as expected.
+
+**Users using [their own webservers](docs/configuring-playbook-own-webserver.md) will need to change `matrix_playbook_reverse_proxy_type`** to something like `other-on-same-host`, `other-on-another-host` or `other-nginx-non-container`. Previously, they could toggle `matrix_nginx_proxy_enabled` to `false`, and that made the playbook automatically expose services locally. Currently, we only do this if you change the reverse-proxy type to `other-on-same-host`, `other-on-another-host` or `other-nginx-non-container`.
+
+#### How do I explicitly switch to Traefik right now?
+
+**Users who wish to migrate to Traefik** today, can do so by **adding** this to their configuration:
+
+```yaml
+matrix_playbook_reverse_proxy_type: playbook-managed-traefik
+
+devture_traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
+```
+
+You may still need to keep certain old `matrix_nginx_proxy_*` variables (like `matrix_nginx_proxy_base_domain_serving_enabled`), even when using Traefik. For now, we recommend keeping all `matrix_nginx_proxy_*` variables just in case. In the future, reliance on `matrix-nginx-proxy` will be removed.
+
+Switching to Traefik will obtain new SSL certificates from Let's Encrypt (stored in `/matrix/traefik/ssl/acme.json`). **The switch is reversible**. You can always go back to `playbook-managed-nginx` if Traefik is causing you trouble.
+
+**Note**: toggling `matrix_playbook_reverse_proxy_type` between Traefik and nginx will uninstall the Traefik role and all of its data (under `/matrix/traefik`), so you may run into a Let's Encrypt rate limit if you do it often.
+
+Treafik directly reverse-proxies to **some** services right now, but for most other services it goes through `matrix-nginx-proxy` (e.g. Traefik -> `matrix-nginx-proxy` -> [Ntfy](docs/configuring-playbook-ntfy.md)). So, even if you opt into Traefik, you'll still see `matrix-nginx-proxy` being installed in local-only mode. This will improve with time.
+
+Some services (like [Coturn](docs/configuring-playbook-turn.md) and [Postmoogle](docs/configuring-playbook-bot-postmoogle.md)) cannot be reverse-proxied to directly from Traefik, so they require direct access to SSL certificate files extracted out of Traefik. The playbook does this automatically thanks to a new [com.devture.ansible.role.traefik_certs_dumper](https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper) role utilizing the [traefik-certs-dumper](https://github.com/ldez/traefik-certs-dumper) tool.
+
+Our Traefik setup mostly works, but certain esoteric features may not work. If you have a default setup, we expect you to have a good experience.
+
+
+### Where we're going in the near future?
+
+The `matrix-nginx-proxy` role is quite messy. It manages both nginx and Certbot and its certificate renewal scripts and timers. It generates configuration even when the role is disabled (weird). Although it doesn't directly reach into variables from other roles, it has explicit awareness of various other services that it reverse-proxies to (`roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2`, etc.). We'd like to clean this up. The only way is probably to just get rid of the whole thing at some point.
+
+For now, `matrix-nginx-proxy` will stay around.
+
+As mentioned above, Traefik still reverse-proxies to some (most) services by going through a local-only `matrix-nginx-proxy` server. This has allowed us to add Traefik support to the playbook early on (without having to rework all services), but is not the final goal. We'll **work on making each service support Traefik natively**, so that traffic will not need to go through `matrix-nginx-proxy` anymore. In the end, choosing Traefik should only give you a pure Traefik installation with no `matrix-nginx-proxy` in sight.
+
+As Traefik support becomes complete and proves to be stable for a while, especially as a playbook default, we will **most likely remove `matrix-nginx-proxy` completely**. It will likely be some months before this happens though. Keeping support for both Traefik and nginx in the playbook will be a burden, especially with most of us running Traefik in the future. The Traefik role should do everything nginx does in a better and cleaner way. Users who use their own `nginx` server on the Matrix server will be inconvenienced, as nothing will generate ready-to-include nginx configuration for them. Still, we hope it won't be too hard to migrate their setup to another way of doing things, like:
+
+- not using nginx anymore. A common reason for using nginx until now was that you were running other containers and you need your own nginx to reverse-proxy to all of them. Just switch them to Traefik as well.
+- running Traefik in local-only mode (`devture_traefik_config_entrypoint_web_secure_enabled: false`) and using some nginx configuration which reverse-proxies to Traefik (we should introduce examples for this in `examples/nginx`).
+
+### How do I help?
+
+You can help by:
+
+- **explicitly switching your server to Traefik** right now (see example configuration in [How do I explicitly switch to Traefik right now?](#how-do-i-explicitly-switch-to-traefik-right-now) above), testing, reporting troubles
+
+- **adding native Traefik support to a role** (requires adding Traefik labels, etc.) - for inspiration, see these roles ([prometheus_node_exporter](https://gitlab.com/etke.cc/roles/prometheus_node_exporter), [prometheus_postgres_exporter](https://gitlab.com/etke.cc/roles/prometheus_postgres_exporter)) and how they're hooked into the playbook via [group_vars/matrix_servers](group_vars/matrix_servers).
+
+- **adding reverse-proxying examples for nginx users** in `examples/nginx`. People who insist on using their own `nginx` server on the same Matrix host, can run Traefik in local-only mode (`devture_traefik_config_entrypoint_web_secure_enabled: false`) and reverse-proxy to the Traefik server
+
+
+# 2023-02-10
+
+## Matrix Authentication Support for Jitsi
+
+Thanks to [Jakob S.](https://github.com/jakicoll) ([zakk gGmbH](https://github.com/zakk-it)), Jitsi can now use Matrix for authentication (via [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service)).
+
+Additional details are available in the [Authenticate using Matrix OpenID (Auth-Type 'matrix')](docs/configuring-playbook-jitsi.md#authenticate-using-matrix-openid-auth-type-matrix).
+
+
+## Draupnir moderation tool (bot) support
+
+Thanks to [FSG-Cat](https://github.com/FSG-Cat), the playbook can now install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool (bot). Draupnir is a fork of [Mjolnir](docs/configuring-playbook-bot-mjolnir.md) (which the playbook has supported for a long time) maintained by Mjolnir's former lead developer.
+
+Additional details are available in [Setting up Draupnir](docs/configuring-playbook-bot-draupnir.md).
+
+
+# 2023-02-05
+
+## The matrix-prometheus-postgres-exporter role lives independently now
+
+**TLDR**: the `matrix-prometheus-postgres-exporter` role is now included from another repository. Some variables have been renamed. All functionality remains intact.
+
+The `matrix-prometheus-postgres-exporter` role (which configures [Prometheus Postgres Exporter](https://github.com/prometheus-community/postgres_exporter)) has been extracted from the playbook and now lives in its own repository at https://gitlab.com/etke.cc/roles/prometheus_postgres_exporter
+
+It's still part of the playbook, but is now installed via `ansible-galaxy` (by running `just roles` / `make roles`). Some variables have been renamed (`matrix_prometheus_postgres_exporter_` -> `prometheus_postgres_exporter_`, etc.). The playbook will report all variables that you need to rename to get upgraded. All functionality remains intact.
+
+The `matrix-prometheus-services-proxy-connect` role has bee adjusted to help integrate the new `prometheus_postgres_exporter` role with our own services (`matrix-nginx-proxy`)
+
+Other roles which aren't strictly related to Matrix are likely to follow this fate of moving to their own repositories. Extracting them out allows other Ansible playbooks to make use of these roles easily.
+
+
+# 2023-01-26
+
+## Coturn can now use host-networking
+
+Large Coturn deployments (with a huge range of ports specified via `matrix_coturn_turn_udp_min_port` and `matrix_coturn_turn_udp_max_port`) experience a huge slowdown with how Docker publishes all these ports (setting up firewall forwarding rules), which leads to a very slow Coturn service startup and shutdown.
+
+Such deployments don't need to run Coturn within a private container network anymore. Coturn can now run with host-networking by using configuration like this:
+
+```yaml
+matrix_coturn_docker_network: host
+```
+
+With such a configuration, **Docker no longer needs to configure thousands of firewall forwarding rules** each time Coturn starts and stops.
+This, however, means that **you will need to ensure these ports are open** in your firewall yourself.
+
+Thanks to us [tightening Coturn security](#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues), running Coturn with host-networking should be safe and not expose neither other services running on the host, nor other services running on the local network.
+
+
+## (Backward Compatibility) Tightening Coturn security can lead to connectivity issues
+
+**TLDR**: users who run and access their Matrix server on a private network (likely a small minority of users) may experience connectivity issues with our new default Coturn blocklists. They may need to override `matrix_coturn_denied_peer_ips` and remove some IP ranges from it.
+
+Inspired by [this security article](https://www.rtcsec.com/article/cve-2020-26262-bypass-of-coturns-access-control-protection/), we've decided to make use of Coturn's `denied-peer-ip` functionality to prevent relaying network traffic to certain private IP subnets. This ensures that your Coturn server won't accidentally try to forward traffic to certain services running on your local networks. We run Coturn in a container and in a private container network by default, which should prevent such access anyway, but having additional block layers in place is better.
+
+If you access your Matrix server from a local network and need Coturn to relay to private IP addresses, you may observe that relaying is now blocked due to our new default `denied-peer-ip` lists (specified in `matrix_coturn_denied_peer_ips`). If you experience such connectivity problems, consider overriding this setting in your `vars.yml` file and removing certain networks from it.
+
+We've also added `no-multicast-peers` to the default Coturn configuration, but we don't expect this to cause trouble for most people.
+
+
+# 2023-01-21
+
+## The matrix-prometheus-node-exporter role lives independently now
+
+**TLDR**: the `matrix-prometheus-node-exporter` role is now included from another repository. Some variables have been renamed. All functionality remains intact.
+
+The `matrix-prometheus-node-exporter` role (which configures [Prometheus node exporter](https://github.com/prometheus/node_exporter)) has been extracted from the playbook and now lives in its own repository at https://gitlab.com/etke.cc/roles/prometheus_node_exporter
+
+It's still part of the playbook, but is now installed via `ansible-galaxy` (by running `just roles` / `make roles`). Some variables have been renamed (`matrix_prometheus_node_exporter_` -> `prometheus_node_exporter_`, etc.). The playbook will report all variables that you need to rename to get upgraded. All functionality remains intact.
+
+A new `matrix-prometheus-services-proxy-connect` role was added to the playbook to help integrate the new `prometheus_node_exporter` role with our own services (`matrix-nginx-proxy`)
+
+Other roles which aren't strictly related to Matrix are likely to follow this fate of moving to their own repositories. Extracting them out allows other Ansible playbooks to make use of these roles easily.
+
+
+# 2023-01-13
+
+## Support for running commands via just
+
+We've previously used [make](https://www.gnu.org/software/make/) for easily running some playbook commands (e.g. `make roles` which triggers `ansible-galaxy`, see [Makefile](Makefile)).
+Our `Makefile` is still around and you can still run these commands.
+
+In addition, we've added support for running commands via [just](https://github.com/casey/just) - a more modern command-runner alternative to `make`. Instead of `make roles`, you can now run `just roles` to accomplish the same.
+
+Our [justfile](justfile) already defines some additional helpful **shortcut** commands that weren't part of our `Makefile`. Here are some examples:
+
+- `just install-all` to trigger the much longer `ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start` command
+- `just install-all --ask-vault-pass` - commands also support additional arguments (`--ask-vault-pass` will be appended to the above installation command)
+- `just run-tags install-mautrix-slack,start` - to run specific playbook tags
+- `just start-all` - (re-)starts all services
+- `just stop-group postgres` - to stop only the Postgres service
+- `just register-user john secret-password yes` - registers a `john` user with the `secret-password` password and admin access (admin = `yes`)
+
+Additional helpful commands and shortcuts may be defined in the future.
+
+This is all completely optional. If you find it difficult to [install `just`](https://github.com/casey/just#installation) or don't find any of this convenient, feel free to run all commands manually.
+
+
+# 2023-01-11
+
+## mautrix-slack support
+
+Thanks to [Cody Neiman](https://github.com/xangelix)'s efforts, the playbook now supports bridging to [Slack](https://slack.com/) via the [mautrix-slack](https://mau.dev/mautrix/slack) bridge. See our [Setting up Mautrix Slack bridging](docs/configuring-playbook-bridge-mautrix-slack.md) documentation page for getting started.
+
+**Note**: this is a new Slack bridge. The playbook still retains Slack bridging via [matrix-appservice-slack](docs/configuring-playbook-bridge-appservice-slack.md) and [mx-puppet-slack](docs/configuring-playbook-bridge-mx-puppet-slack.md). You're free to use the bridge that serves you better, or even all three of them (for different users and use-cases).
+
+
+# 2023-01-10
+
+## ChatGPT support
+
+Thanks to [@bertybuttface](https://github.com/bertybuttface), the playbook can now help you set up [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) - a bot through which you can talk to the [ChatGPT](https://openai.com/blog/chatgpt/) model.
+
+See our [Setting up matrix-bot-chatgpt](docs/configuring-playbook-bot-chatgpt.md) documentation to get started.
+
+
+# 2022-11-30
+
+## matrix-postgres-backup has been replaced by the com.devture.ansible.role.postgres_backup external role
+
+Just like we've [replaced Postgres with an external role](#matrix-postgres-has-been-replaced-by-the-comdevtureansiblerolepostgres-external-role) on 2022-11-28, we're now replacing `matrix-postgres-backup` with an external role - [com.devture.ansible.role.postgres_backup](https://github.com/devture/com.devture.ansible.role.postgres_backup).
+
+You'll need to rename your `matrix_postgres_backup`-prefixed variables such that they use a `devture_postgres_backup` prefix.
+
+
+# 2022-11-28
+
+## matrix-postgres has been replaced by the com.devture.ansible.role.postgres external role
+
+**TLDR**: the tasks that install the integrated Postgres server now live in an external role - [com.devture.ansible.role.postgres](https://github.com/devture/com.devture.ansible.role.postgres). You'll need to run `make roles` to install it, and to also rename your `matrix_postgres`-prefixed variables to use a `devture_postgres` prefix (e.g. `matrix_postgres_connection_password` -> `devture_postgres_connection_password`). All your data will still be there! Some scripts have moved (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`).
+
+The `matrix-postgres` role that has been part of the playbook for a long time has been replaced with the [com.devture.ansible.role.postgres](https://github.com/devture/com.devture.ansible.role.postgres) role. This was done as part of our work to [use external roles for some things](#the-playbook-now-uses-external-roles-for-some-things) for better code re-use and maintainability.
+
+The new role is an upgraded version of the old `matrix-postgres` role with these notable differences:
+
+- it uses different names for its variables (`matrix_postgres` -> `devture_postgres`)
+- when [Vacuuming PostgreSQL](docs/maintenance-postgres.md#vacuuming-postgresql), it will vacuum all your databases, not just the Synapse one
+
+You'll need to run `make roles` to install the new role. You would also need to rename your `matrix_postgres`-prefixed variables to use a `devture_postgres` prefix.
+
+Note: the systemd service still remains the same - `matrix-postgres.service`. Your data will still be in `/matrix/postgres`, etc.
+Postgres-related scripts will be moved to `/matrix/postgres/bin` (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`, etc). Also see [The playbook no longer installs scripts in /usr/local/bin](#the-playbook-no-longer-installs-scripts-in-usrlocalbin).
+
+## The playbook no longer installs scripts to /usr/local/bin
+
+The locations of various scripts installed by the playbook have changed.
+
+The playbook no longer contaminates your `/usr/local/bin` directory.
+All scripts installed by the playbook now live in `bin/` directories under `/matrix`. Some examples are below:
+
+- `/usr/local/bin/matrix-remove-all` -> `/matrix/bin/remove-all`
+- `/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`
+- `/usr/local/bin/matrix-ssl-lets-encrypt-certificates-renew` -> `/matrix/ssl/bin/lets-encrypt-certificates-renew`
+- `/usr/local/bin/matrix-synapse-register-user` -> `/matrix/synapse/bin/register-user`
+
+
 # 2022-11-25
 
 ## 2x-5x performance improvements in playbook runtime
@@ -96,11 +693,11 @@ Various services (like Dimension, etc.) still talk to Synapse via `matrix-nginx-
 
 Until now, [Etherpad](https://etherpad.org/) (which [the playbook could install for you](docs/configuring-playbook-etherpad.md)) required the [Dimension integration manager](docs/configuring-playbook-dimension.md) to also be installed, because Etherpad was hosted on the Dimension domain (at `dimension.DOMAIN/etherpad`).
 
-From now on, Etherpad can be installed in `standalone` mode on `etherpad.DOMAIN` and used even without Dimension. This is much more versatile, so the playbook now defaults to this new mode (`matrix_etherpad_mode: standalone`).
+From now on, Etherpad can be installed in `standalone` mode on `etherpad.DOMAIN` and used even without Dimension. This is much more versatile, so the playbook now defaults to this new mode (`etherpad_mode: standalone`).
 
 If you've already got both Etherpad and Dimension in use you could:
 
-- **either** keep hosting Etherpad under the Dimension domain by adding `matrix_etherpad_mode: dimension` to your `vars.yml` file. All your existing room widgets will continue working at the same URLs and no other changes will be necessary.
+- **either** keep hosting Etherpad under the Dimension domain by adding `etherpad_mode: dimension` to your `vars.yml` file. All your existing room widgets will continue working at the same URLs and no other changes will be necessary.
 
 - **or**, you could change to hosting Etherpad separately on `etherpad.DOMAIN`. You will need to [configure a DNS record](docs/configuring-dns.md) for this new domain. You will also need to reconfigure Dimension to use the new pad URLs (`https://etherpad.DOMAIN/...`) going forward (refer to our [configuring Etherpad documentation](docs/configuring-playbook-etherpad.md)). All your existing room widgets (which still use `https://dimension.DOMAIN/etherpad/...`) will break as Etherpad is not hosted there anymore. You will need to re-add them or to consider not using `standalone` mode
 
@@ -313,7 +910,7 @@ matrix_homeserver_implementation: conduit
 
 Thanks to [MdotAmaan](https://github.com/MdotAmaan)'s efforts, the playbook now supports bridging to [Discord](https://discordapp.com/) via the [mautrix-discord](https://mau.dev/mautrix/discord) bridge. See our [Setting up Mautrix Discord bridging](docs/configuring-playbook-bridge-mautrix-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) and [mx-puppet-discord](docs/configuring-playbook-bridge-mx-puppet-discord.md). You're free too use the bridge that serves you better, or even all three of them (for different users and use-cases).
+**Note**: this is a new Discord bridge. The playbook still retains Discord bridging via [matrix-appservice-discord](docs/configuring-playbook-bridge-appservice-discord.md) and [mx-puppet-discord](docs/configuring-playbook-bridge-mx-puppet-discord.md). You're free to use the bridge that serves you better, or even all three of them (for different users and use-cases).
 
 
 # 2022-07-27
@@ -387,14 +984,14 @@ See our [Setting up the ntfy push notifications server](docs/configuring-playboo
 
 **If you are using the [Hookshot bridge](docs/configuring-playbook-bridge-hookshot.md)**, you may find that:
 1. **Metrics may not be enabled by default anymore**:
-  - If Prometheus is enabled (`matrix_prometheus_enabled: true`), then Hookshot metrics will be enabled automatically (`matrix_hookshot_metrics_enabled: true`). These metrics will be collected from the local (in-container) Prometheus over the container network.
+  - If Prometheus is enabled (`prometheus_enabled: true`), then Hookshot metrics will be enabled automatically (`matrix_hookshot_metrics_enabled: true`). These metrics will be collected from the local (in-container) Prometheus over the container network.
   - **If Prometheus is not enabled** (you are either not using Prometheus or are using an external one), **Hookshot metrics will not be enabled by default anymore**. Feel free to enable them by setting `matrix_hookshot_metrics_enabled: true`. Also, see below.
 2. When metrics are meant to be **consumed by an external Prometheus server**, `matrix_hookshot_metrics_proxying_enabled` needs to be set to `true`, so that metrics would be exposed (proxied) "publicly" on `https://matrix.DOMAIN/metrics/hookshot`. To make use of this, you'll also need to enable the new `https://matrix.DOMAIN/metrics/*` endpoints mentioned above, using `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. Learn more in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation.
 3. **We've changed the URL we're exposing Hookshot metrics at** for external Prometheus servers. Until now, you were advised to consume Hookshot metrics from `https://stats.DOMAIN/hookshot/metrics` (working in conjunction with `matrix_nginx_proxy_proxy_synapse_metrics`). From now on, **this no longer works**. As described above, you need to start consuming metrics from `https://matrix.DOMAIN/metrics/hookshot`.
 
 **If you're using node-exporter** (`matrix_prometheus_node_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_node_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.DOMAIN/metrics/node-exporter`.
 
-**If you're using [postgres-exporter](docs/configuring-playbook-prometheus-postgres.md)** (`matrix_prometheus_postgres_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_postgres_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.DOMAIN/metrics/postgres-exporter`.
+**If you're using [postgres-exporter](docs/configuring-playbook-prometheus-postgres.md)** (`prometheus_postgres_exporter_enabled: true`) and would like to collect its metrics from an external Prometheus server, see `matrix_prometheus_services_proxy_connect_prometheus_postgres_exporter_metrics_proxying_enabled` described in our [Collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) documentation. You will be able to collect its metrics from `https://matrix.DOMAIN/metrics/postgres-exporter`.
 
 **If you're using Synapse** and would like to collect its metrics from an external Prometheus server, you may find that:
 
@@ -415,7 +1012,6 @@ See our [Setting up Go Skype Bridge](docs/configuring-playbook-bridge-go-skype-b
 
 The playbook has supported [mx-puppet-skype](https://github.com/Sorunome/mx-puppet-skype) bridging (see [Setting up MX Puppet Skype bridging](docs/configuring-playbook-bridge-mx-puppet-skype.md)) since [2020-04-09](#2020-04-09), but `mx-puppet-skype` is reportedly broken.
 
-
 # 2022-06-09
 
 ## Running Ansible in a container can now happen on the Matrix server itself
@@ -1085,7 +1681,7 @@ People who have [fine-tuned Jitsi](docs/configuring-playbook-jitsi.md#optional-f
 
 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.
+Additionally, we've recently disabled transcriptions (`jitsi_enable_transcriptions: false`) and recording (`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

README.md

@@ -13,6 +13,15 @@ We run all services in [Docker](https://www.docker.com/) containers (see [the co
 [Installation](docs/README.md) (upgrades) and some maintenance tasks are automated using [Ansible](https://www.ansible.com/) (see [our Ansible guide](docs/ansible.md)).
 
 
+## Self-hosting or SaaS
+
+This Ansible playbook tries to make self-hosting and maintaining a Matrix server fairly easy. Still, running any service smoothly requires knowledge, time and effort.
+
+If you like the [FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) spirit of this Ansible playbook, but prefer to put the responsibility on someone else, you can also [get a managed Matrix server from etke.cc](https://etke.cc/) - a service built on top of this Ansible playbook, which can help you run a Matrix server with ease.
+
+If you like learning and experimentation, but would rather reduce future maintenance effort, you can even go for a hybrid approach - self-hosting manually using this Ansible playbook at first and then transferring server maintenance to etke.cc at a later time.
+
+
 ## Supported services
 
 Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
@@ -27,7 +36,7 @@ You can always re-run the playbook later to add or remove components.
 The homeserver is the backbone of your matrix system. Choose one from the following list.
 
 | Name | Default? | Description | Documentation |
-| ---- | -------- | ----------- | ------------- | 
+| ---- | -------- | ----------- | ------------- |
 | [Synapse](https://github.com/matrix-org/synapse) | ✓ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network | [Link](docs/configuring-playbook-synapse.md) |
 | [Conduit](https://conduit.rs) | x | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements | [Link](docs/configuring-playbook-conduit.md) |
 | [Dendrite](https://github.com/matrix-org/dendrite) | x | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse. | [Link](docs/configuring-playbook-dendrite.md) |
@@ -38,9 +47,10 @@ Web clients for matrix that you can host on your own domains.
 
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
-[Element](https://app.element.io/) | ✓ | Web UI, which is configured to connect to your own Synapse server by default | [Link](docs/configuring-playbook-client-element.md) |
-| [Hydrogen](https://github.com/vector-im/hydrogen-web) | x | Web client | [Link](docs/configuring-playbook-client-hydrogen.md) |
-| [Cinny](https://github.com/ajbura/cinny) |  x | Web client | [Link](docs/configuring-playbook-client-cinny.md) |
+| [Element](https://app.element.io/) | ✓ | Web UI, which is configured to connect to your own Synapse server by default | [Link](docs/configuring-playbook-client-element.md) |
+| [Hydrogen](https://github.com/vector-im/hydrogen-web) | x | Lightweight matrix client with legacy and mobile browser support | [Link](docs/configuring-playbook-client-hydrogen.md) |
+| [Cinny](https://github.com/ajbura/cinny) |  x | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
+| [SchildiChat](https://schildi.chat/) | x | Based on Element, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat.md) |
 
 
 
@@ -52,10 +62,11 @@ Services that run on the server to make the various parts of your installation w
 | ---- | -------- | ----------- | ------------- |
 | [PostgreSQL](https://www.postgresql.org/)| ✓ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
 | [Coturn](https://github.com/coturn/coturn) | ✓ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
-| [nginx](http://nginx.org/) | ✓ | Web server, listening on ports 80 and 443 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md) | [Link](docs/configuring-playbook-nginx.md) |
-| [Let's Encrypt](https://letsencrypt.org/) | ✓ | Free  SSL certificate, which secures the connection to the Synapse server and the Element web UI | [Link](docs/configuring-playbook-ssl-certificates.md) |
-| [ma1sd](https://github.com/ma1uta/ma1sd) | x | Matrix Identity Server | [Link](configuring-playbook-ma1sd.md)
-| [Exim](https://www.exim.org/) | ✓ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | - |
+| [Traefik](https://doc.traefik.io/traefik/) | ✓ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md) | [Link](docs/configuring-playbook-traefik.md) |
+| [nginx](http://nginx.org/) | x | (Deprecated) Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Deprecated in favor of Traefik | [Link](docs/configuring-playbook-nginx.md) |
+| [Let's Encrypt](https://letsencrypt.org/) | ✓ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
+| [ma1sd](https://github.com/ma1uta/ma1sd) | x | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
+| [Exim](https://www.exim.org/) | ✓ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
 | [Dimension](https://github.com/turt2live/matrix-dimension) | x | An open source integrations manager for matrix clients | [Link](docs/configuring-playbook-dimension.md) |
 | [Sygnal](https://github.com/matrix-org/sygnal) | x | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
 | [ntfy](https://ntfy.sh) | x | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
@@ -66,10 +77,10 @@ Services that run on the server to make the various parts of your installation w
 Extend and modify how users are authenticated on your homeserver.
 
 | Name | Default? | Description | Documentation |
-| ---- | -------- | ----------- | ------------- | 
+| ---- | -------- | ----------- | ------------- |
 | [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) (advanced) | x | REST authentication password provider module | [Link](docs/configuring-playbook-rest-auth.md) |
 |[matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) (advanced) | x | Password provider module | [Link](docs/configuring-playbook-shared-secret-auth.md) |
-| [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) (advanced) | x | LDAP Auth password provider module | [Link](configuring-playbook-ldap-auth.md) |
+| [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) (advanced) | x | LDAP Auth password provider module | [Link](docs/configuring-playbook-ldap-auth.md) |
 | [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | x | A proxy that handles Matrix registration requests and forwards them to LDAP. | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
 | [matrix-registration](https://github.com/ZerataX/matrix-registration) | x | A simple python application to have a token based matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
 
@@ -82,6 +93,7 @@ Use alternative file storage to the default `media_store` folder.
 | ---- | -------- | ----------- | ------------- |
 | [Goofys](https://github.com/kahing/goofys) | x | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3-goofys.md) |
 | [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) | x | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3.md) |
+| [matrix-media-repo](https://github.com/turt2live/matrix-media-repo) | x | matrix-media-repo is a highly customizable multi-domain media repository for Matrix. Intended for medium to large deployments, this media repo de-duplicates media while being fully compliant with the specification. | [Link](docs/configuring-playbook-matrix-media-repo.md) |
 
 ### Bridges
 
@@ -89,31 +101,33 @@ Bridges can be used to connect your matrix installation with third-party communi
 
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
-[mautrix-discord](https://github.com/mautrix/discord) | x | Bridge for bridging your Matrix server to [Discord](https://discord.com/) | [Link](docs/configuring-playbook-bridge-mautrix-discord.md) |
-| [mautrix-telegram](https://github.com/mautrix/telegram) | x | Bridge for bridging your Matrix server to [Telegram](https://telegram.org/) | [Link](docs/configuring-playbook-bridge-mautrix-telegram.md) |
-| [mautrix-whatsapp](https://github.com/mautrix/whatsapp) | x | Bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/) | [Link](docs/configuring-playbook-bridge-mautrix-whatsapp.md) |
-| [mautrix-facebook](https://github.com/mautrix/facebook) | x | Bridge for bridging your Matrix server to [Facebook](https://facebook.com/) | [Link](docs/configuring-playbook-bridge-mautrix-facebook.md) |
-| [mautrix-twitter](https://github.com/mautrix/twitter) | x | Bridge for bridging your Matrix server to [Twitter](https://twitter.com/) | [Link](docs/configuring-playbook-bridge-mautrix-twitter.md) |
-| [mautrix-hangouts](https://github.com/mautrix/hangouts) | x | Bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts) | [Link](docs/configuring-playbook-bridge-mautrix-hangouts.md) |
-| [mautrix-googlechat](https://github.com/mautrix/googlechat) | x | Bridge for bridging your Matrix server to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) | [Link](docs/configuring-playbook-bridge-mautrix-googlechat.md) |
-| [mautrix-instagram](https://github.com/mautrix/instagram) | x | Bridge for bridging your Matrix server to [Instagram](https://instagram.com/) | [Link](docs/configuring-playbook-bridge-mautrix-instagram.md) |
-| [mautrix-signal](https://github.com/mautrix/signal) | x | Bridge for bridging your Matrix server to [Signal](https://www.signal.org/) | [Link](docs/configuring-playbook-bridge-mautrix-signal.md) |
-| [beeper-linkedin](https://github.com/beeper/linkedin) | x | Bridge for bridging your Matrix server to [LinkedIn](https://www.linkedin.com/) | [Link](docs/configuring-playbook-bridge-beeper-linkedin.md) |
-| [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) | x | Bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-appservice-irc.md) |
-| [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) | x | Bridge for bridging your Matrix server to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-appservice-discord.md) |
-| [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) | x | Bridge for bridging your Matrix server to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-appservice-slack.md) |
+| [mautrix-discord](https://github.com/mautrix/discord) | x | Bridge to [Discord](https://discord.com/) | [Link](docs/configuring-playbook-bridge-mautrix-discord.md) |
+| [mautrix-slack](https://github.com/mautrix/slack) | x | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-mautrix-slack.md) |
+| [mautrix-telegram](https://github.com/mautrix/telegram) | x | Bridge to [Telegram](https://telegram.org/) | [Link](docs/configuring-playbook-bridge-mautrix-telegram.md) |
+| [mautrix-gmessages](https://github.com/mautrix/gmessages) | x | Bridge to [Google Messages](https://messages.google.com/) | [Link](docs/configuring-playbook-bridge-mautrix-gmessages.md) |
+| [mautrix-whatsapp](https://github.com/mautrix/whatsapp) | x | Bridge to [WhatsApp](https://www.whatsapp.com/) | [Link](docs/configuring-playbook-bridge-mautrix-whatsapp.md) |
+| [mautrix-facebook](https://github.com/mautrix/facebook) | x | Bridge to [Facebook](https://facebook.com/) | [Link](docs/configuring-playbook-bridge-mautrix-facebook.md) |
+| [mautrix-twitter](https://github.com/mautrix/twitter) | x | Bridge to [Twitter](https://twitter.com/) | [Link](docs/configuring-playbook-bridge-mautrix-twitter.md) |
+| [mautrix-hangouts](https://github.com/mautrix/hangouts) | x | Bridge to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts) | [Link](docs/configuring-playbook-bridge-mautrix-hangouts.md) |
+| [mautrix-googlechat](https://github.com/mautrix/googlechat) | x | Bridge to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) | [Link](docs/configuring-playbook-bridge-mautrix-googlechat.md) |
+| [mautrix-instagram](https://github.com/mautrix/instagram) | x | Bridge to [Instagram](https://instagram.com/) | [Link](docs/configuring-playbook-bridge-mautrix-instagram.md) |
+| [mautrix-signal](https://github.com/mautrix/signal) | x | Bridge to [Signal](https://www.signal.org/) | [Link](docs/configuring-playbook-bridge-mautrix-signal.md) |
+| [beeper-linkedin](https://github.com/beeper/linkedin) | x | Bridge to [LinkedIn](https://www.linkedin.com/) | [Link](docs/configuring-playbook-bridge-beeper-linkedin.md) |
+| [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) | x | Bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-appservice-irc.md) |
+| [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) | x | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-appservice-discord.md) |
+| [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) | x | Bridge to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-appservice-slack.md) |
 | [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) | x | Bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.) | [Link](docs/configuring-playbook-bridge-appservice-webhooks.md) |
-| [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) | x | Bridge for bridging Matrix to generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | [Link](docs/configuring-playbook-bridge-hookshot.md) |
-| [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | x | Bridge for bridging your Matrix server to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) |
-| [Heisenbridge](https://github.com/hifi/heisenbridge) | x | Bridge for bridging your Matrix server to IRC bouncer-style | [Link](docs/configuring-playbook-bridge-heisenbridge.md) |
-| [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) | x | Bridge for bridging your Matrix server to [Skype](https://www.skype.com) | [Link](docs/configuring-playbook-bridge-go-skype-bridge.md) |
-| [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) | x | Bridge for bridging your Matrix server to [Slack](https://slack.com) | [Link](docs/configuring-playbook-bridge-mx-puppet-slack.md) |
+| [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) | x | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | [Link](docs/configuring-playbook-bridge-hookshot.md) |
+| [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | x | Bridge to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) |
+| [Heisenbridge](https://github.com/hifi/heisenbridge) | x | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-heisenbridge.md) |
+| [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) | x | Bridge to [Skype](https://www.skype.com) | [Link](docs/configuring-playbook-bridge-go-skype-bridge.md) |
+| [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) | x | Bridge to [Slack](https://slack.com) | [Link](docs/configuring-playbook-bridge-mx-puppet-slack.md) |
 | [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) | x | Bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-instagram.md) |
 | [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) | x | Bridge for Twitter-DMs ([Twitter](https://twitter.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-twitter.md) |
-| [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) | x | Bridge for [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-discord.md) |
-| [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | x | Bridge for [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) |
-| [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) | x | Bridge for [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) |
-| [Email2Matrix](https://github.com/devture/email2matrix) | x | Bridge for relaying email messages to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
+| [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) | x | Bridge to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-discord.md) |
+| [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | x | Bridge to [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) |
+| [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) | x | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) |
+| [Email2Matrix](https://github.com/devture/email2matrix) | x | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
 
 
 ### Bots
@@ -129,7 +143,9 @@ Bots provide various additional functionality to your installation.
 | [Postmoogle](https://gitlab.com/etke.cc/postmoogle) | x | Email to matrix bot | [Link](docs/configuring-playbook-bot-postmoogle.md) |
 | [Go-NEB](https://github.com/matrix-org/go-neb) | x | A multi functional bot written in Go | [Link](docs/configuring-playbook-bot-go-neb.md) |
 | [Mjolnir](https://github.com/matrix-org/mjolnir) | x | A moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
+| [Draupnir](https://github.com/the-draupnir-project/Draupnir) | x | A moderation tool for Matrix (Fork of Mjolnir) | [Link](docs/configuring-playbook-bot-draupnir.md) |
 | [Buscarron](https://gitlab.com/etke.cc/buscarron) | x | Web forms (HTTP POST) to matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
+| [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) | x | ChatGPT from matrix | [Link](docs/configuring-playbook-bot-chatgpt.md) |
 
 ### Administration
 
@@ -141,6 +157,7 @@ Services that help you in administrating and monitoring your matrix installation
 | [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) | x | A web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
 | Metrics and Graphs | x | Consists of the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI | [Link](docs/configuring-playbook-prometheus-grafana.md) |
 | [Borg](https://borgbackup.org) | x | Backups | [Link](docs/configuring-playbook-backup-borg.md) |
+| [Rageshake](https://github.com/matrix-org/rageshake) | x | Bug report server | [Link](docs/configuring-playbook-rageshake.md) |
 
 ### Misc
 
@@ -148,6 +165,8 @@ Various services that don't fit any other category.
 
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
+| [sliding-sync](https://github.com/matrix-org/sliding-sync)| x | Sliding Sync support for clients which require it (e.g. Element X) | [Link](docs/configuring-playbook-sliding-sync-proxy.md) |
+| [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) | x | A cli tool that automatically compresses `state_groups` database table in background. | [Link](docs/configuring-playbook-synapse-auto-compressor.md) |
 | [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | x | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
 | [Matrix Corporal](https://github.com/devture/matrix-corporal) (advanced) | x | Reconciliator and gateway for a managed Matrix server | [Link](docs/configuring-playbook-matrix-corporal.md) |
 | [Etherpad](https://etherpad.org) | x | An open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
@@ -176,6 +195,16 @@ When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up w
 - GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
 
 
-## Services by the community
+## Related
 
-- [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
+You may also be interested in these other Ansible playbooks:
+
+- [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy) - for deploying a [Gitea](https://gitea.io/) git version-control server
+
+- [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy) - for deploying a [Nextcloud](https://nextcloud.com/) server
+
+- [peertube-docker-ansible-deploy](https://github.com/spantaleev/peertube-docker-ansible-deploy) - for deploying a [PeerTube](https://joinpeertube.org/) video-platform server
+
+- [vaultwarden-docker-ansible-deploy](https://github.com/spantaleev/vaultwarden-docker-ansible-deploy) - for deploying a [Vaultwarden](https://github.com/dani-garcia/vaultwarden) password manager server (unofficial [Bitwarden](https://bitwarden.com/) compatible server)
+
+They're all making use of Traefik as their reverse-proxy, so it should be easy to host all these services on the same server. Follow the `docs/configuring-playbook-interoperability.md` documentation in each playbook.

devshell/.gitignore

@@ -0,0 +1 @@
+/.direnv/

devshell/devshell.toml

@@ -0,0 +1,4 @@
+# https://numtide.github.io/devshell
+[[commands]]
+package = "devshell.cli"
+help = "Per project developer environments"

devshell/flake.lock

@@ -0,0 +1,92 @@
+{
+  "nodes": {
+    "devshell": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1667210711,
+        "narHash": "sha256-IoErjXZAkzYWHEpQqwu/DeRNJGFdR7X2OGbkhMqMrpw=",
+        "owner": "numtide",
+        "repo": "devshell",
+        "rev": "96a9dd12b8a447840cc246e17a47b81a4268bba7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "devshell",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "locked": {
+        "lastModified": 1642700792,
+        "narHash": "sha256-XqHrk7hFb+zBvRg6Ghl+AZDq03ov6OshJLiSWOoX5es=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "846b2ae0fc4cc943637d3d1def4454213e203cba",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "flake-utils_2": {
+      "locked": {
+        "lastModified": 1667395993,
+        "narHash": "sha256-nuEHfE/LcWyuSWnS8t12N1wc105Qtau+/OdUAjtQ0rA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "5aed5285a952e0b949eb3ba02c12fa4fcfef535f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1643381941,
+        "narHash": "sha256-pHTwvnN4tTsEKkWlXQ8JMY423epos8wUOhthpwJjtpc=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "5efc8ca954272c4376ac929f4c5ffefcc20551d5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1667969101,
+        "narHash": "sha256-GL53T705HO7Q/KVfbb5STx8AxFs8YgaGY8pvAZC+O7U=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "bbf77421ac51a7c93f5f0f760da99e4dbce614fa",
+        "type": "github"
+      },
+      "original": {
+        "id": "nixpkgs",
+        "type": "indirect"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devshell": "devshell",
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": "nixpkgs_2"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

devshell/flake.nix

@@ -0,0 +1,23 @@
+{
+  description = "virtual environments";
+
+  inputs.devshell.url = "github:numtide/devshell";
+  inputs.flake-utils.url = "github:numtide/flake-utils";
+
+  outputs = { self, flake-utils, devshell, nixpkgs }:
+    flake-utils.lib.eachDefaultSystem (system: {
+      devShell =
+        let pkgs = import nixpkgs {
+          inherit system;
+
+          overlays = [ devshell.overlay ];
+        };
+        in
+        pkgs.devshell.mkShell {
+          imports = [ (pkgs.devshell.importTOML ./devshell.toml) ];
+          devshell.packages = with pkgs; [
+            gnumake
+          ];
+        };
+    });
+}

docs/ansible.md

@@ -9,19 +9,14 @@ If your local computer cannot run Ansible, you can also run Ansible on some serv
 
 ## Supported Ansible versions
 
-Ansible 2.7.1 or newer is required ([last discussion about Ansible versions](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/743)).
-
-Note: Ubuntu 20.04 ships with Ansible 2.9.6 which is a buggy version (see this [bug](https://bugs.launchpad.net/ubuntu/+source/ansible/+bug/1880359)), which can't be used in combination with a host running new systemd (more details in [#517](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/517), [#669](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/669)). If this problem affects you, you can: avoid running Ubuntu 20.04 on your host; run Ansible from another machine targeting your host; or try to upgrade to a newer Ansible version (see below).
-
-
-## Checking your Ansible version
-
-In most cases, you won't need to worry about the Ansible version.
-The playbook will try to detect it and tell you if you're on an unsupported version.
-
 To manually check which version of Ansible you're on, run: `ansible --version`.
 
-If you're on an old version of Ansible, you should [upgrade Ansible to a newer version](#upgrading-ansible) or [use Ansible via Docker](#using-ansible-via-docker).
+For the **best experience**, we recommend getting the **latest version of Ansible available**.
+
+We're not sure what's the minimum version of Ansible that can run this playbook successfully.
+The lowest version that we've confirmed (on 2022-11-26) to be working fine is: `ansible-core` (`2.11.7`) combined with `ansible` (`4.10.0`).
+
+If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
 
 
 ## Upgrading Ansible
@@ -70,7 +65,7 @@ docker run -it --rm \
 -w /work \
 -v `pwd`:/work \
 --entrypoint=/bin/sh \
-docker.io/devture/ansible:2.13.6-r0
+docker.io/devture/ansible:2.14.5-r0-0
 ```
 
 Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container.
@@ -91,7 +86,7 @@ docker run -it --rm \
 -v `pwd`:/work \
 -v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
 --entrypoint=/bin/sh \
-docker.io/devture/ansible:2.13.6-r0
+docker.io/devture/ansible:2.14.5-r0-0
 ```
 
 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

@@ -2,9 +2,11 @@
 
 # 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.
+The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.
 
-## Getting keys
+## ReCaptcha
+
+### Getting keys
 
 Requires a site/secret key pair from:
 
@@ -12,12 +14,39 @@ Requires a site/secret key pair from:
 
 Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option
 
-## Setting ReCaptcha Keys
+### Setting ReCaptcha keys
 
 Once registered as above, set the following values:
 
 ```yaml
+# for Synapse
 matrix_synapse_enable_registration_captcha: true
 matrix_synapse_recaptcha_public_key: 'YOUR_SITE_KEY'
 matrix_synapse_recaptcha_private_key: 'YOUR_SECRET_KEY'
+
+# for Dendrite
+matrix_dendrite_client_api_enable_registration_captcha: true
+matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
+matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
+```
+
+## hCaptcha
+
+### Getting keys
+
+Requires a site/secret key pair from:
+
+<https://dashboard.hcaptcha.com/sites/new>
+
+### Setting hCaptcha keys
+
+```yaml
+matrix_dendrite_client_api_enable_registration_captcha: true
+matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
+matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
+
+matrix_dendrite_client_api_recaptcha_siteverify_api: 'https://hcaptcha.com/siteverify'
+matrix_dendrite_client_api_recaptcha_api_js_url: 'https://js.hcaptcha.com/1/api.js'
+matrix_dendrite_client_api_recaptcha_form_field: 'h-captcha-response'
+matrix_dendrite_client_api_recaptcha_sitekey_class: 'h-captcha'
 ```

docs/configuring-dns.md

@@ -42,6 +42,8 @@ When you're done configuring DNS, proceed to [Configuring the playbook](configur
 | [Etherpad](configuring-playbook-etherpad.md) collaborative text editor                                                  | CNAME | `etherpad`                     | -        | -      | -    | `matrix.<your-domain>`      |
 | [Hydrogen](configuring-playbook-client-hydrogen.md) web client                                                          | CNAME | `hydrogen`                     | -        | -      | -    | `matrix.<your-domain>`      |
 | [Cinny](configuring-playbook-client-cinny.md) web client                                                                | CNAME | `cinny`                        | -        | -      | -    | `matrix.<your-domain>`      |
+| [SchildiChat](configuring-playbook-client-schildichat.md) web client                                                    | CNAME | `schildichat`                  | -        | -      | -    | `matrix.<your-domain>`      |
+| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge                                                    | CNAME | `wsproxy`                      | -        | -      | -    | `matrix.<your-domain>`      |
 | [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot                                                         | CNAME | `buscarron`                    | -        | -      | -    | `matrix.<your-domain>`      |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX    | `matrix`                       | 10       | 0      | -    | `matrix.<your-domain>`      |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge                                                       | TXT   | `matrix`                       | -        | -      | -    | `v=spf1 ip4:<your-ip> -all` |
@@ -75,6 +77,8 @@ The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook c
 
 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 `wsproxy.<your-domain>` subdomain may be necessary, because this playbook could install the [wsproxy](https://github.com/mautrix/wsproxy) web client. The installation of wsproxy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring wsproxy guide](configuring-playbook-bridge-mautrix-wsproxy.md). If you do not wish to set up wsproxy, feel free to skip the `wsproxy.<your-domain>` DNS record.
+
 The `buscarron.<your-domain>` subdomain may be necessary, because this playbook could install the [buscarron](https://gitlab.com/etke.cc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.<your-domain>` DNS record.
 
 ## `_matrix-identity._tcp` SRV record setup

docs/configuring-playbook-backup-borg.md

@@ -6,9 +6,9 @@ That means your daily incremental backups can be stored in a fraction of the spa
 
 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.
+The backup will run based on `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.
+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 `backup_borg_postgresql_enabled` variable.
 
 
 ## Prerequisites
@@ -38,11 +38,11 @@ cat PUBKEY | ssh USER@HOST 'dd of=.ssh/authorized_keys oflag=append conv=notrunc
 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: |
+backup_borg_enabled: true
+backup_borg_location_repositories:
+ - ssh://USER@HOST/./REPO
+backup_borg_storage_encryption_passphrase: "PASSPHRASE"
+backup_borg_ssh_key_private: |
   -----BEGIN OPENSSH PRIVATE KEY-----
   TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
   xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
@@ -58,13 +58,13 @@ where:
 * HOST - SSH host of a provider/server
 * REPO - borg repository name, it will be initialized on backup start, eg: `matrix`, regarding Syntax see [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls)
 * PASSPHRASE - passphrase used for encrypting backups, you may generate it with `pwgen -s 64 1` or use any password manager
-* PRIVATE KEY - the content of the **private** part of the SSH key you created before. The whole key (all of its belonging lines) under `matrix_backup_borg_ssh_key_private` needs to be indented with 2 spaces
+* PRIVATE KEY - the content of the **private** part of the SSH key you created before. The whole key (all of its belonging lines) under `backup_borg_ssh_key_private` needs to be indented with 2 spaces
 
-To backup without encryption, add `matrix_backup_borg_encryption: 'none'` to your vars. This will also enable the `matrix_backup_borg_unknown_unencrypted_repo_access_is_ok` variable.
+To backup without encryption, add `backup_borg_encryption: 'none'` to your vars. This will also enable the `backup_borg_unknown_unencrypted_repo_access_is_ok` variable.
 
-`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.
+`backup_borg_location_source_directories` defines the list of directories to back up: it's set to `{{ matrix_base_data_path }}` by default, which is the base directory for every service's data, such as Synapse, Postgres and the bridges. You might want to exclude certain directories or file patterns from the backup using the `backup_borg_location_exclude_patterns` variable.
 
-Check the `roles/custom/matrix-backup-borg/defaults/main.yml` file for the full list of available options.
+Check the [backup_borg role](https://gitlab.com/etke.cc/roles/backup_borg)'s [defaults/main.yml](https://gitlab.com/etke.cc/roles/backup_borg/-/blob/main/defaults/main.yml) file for the full list of available options.
 
 ## Installing
 

docs/configuring-playbook-bot-buscarron.md

@@ -2,8 +2,32 @@
 
 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
+Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.
+
+
+## Decide on a domain and path
+
+By default, Buscarron is configured to use its own dedicated domain (`buscarron.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+You can override the domain and path like this:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
+# so we won't need to add additional DNS records for Buscarron.
+matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /buscarron subpath
+matrix_bot_buscarron_path_prefix: /buscarron
+```
+
+**NOTE**: When using `matrix-nginx-proxy` instead of Traefik, you won't be able to override the path prefix. You can only override the domain, but that needs to happen using another variable: `matrix_server_fqn_buscarron` (e.g. `matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"`).
+
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
 
 ## Adjusting the playbook configuration
@@ -31,16 +55,6 @@ matrix_bot_buscarron_forms:
 matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
 ```
 
-You will also need to add a DNS record so that buscarron can be accessed.
-By default buscarron will use https://buscarron.DOMAIN so you will need to create an CNAME record for `buscarron`.
-See [Configuring DNS](configuring-dns.md).
-
-If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):
-
-```yaml
-matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"
-```
-
 
 ## Installing
 
@@ -67,4 +81,12 @@ To use the bot, invite the `@bot.buscarron:DOMAIN` to the room you specified in
 </form>
 ```
 
+**NOTE**: to fight against spam, Buscarron is **very aggressive when it comes to banning** and will ban you if:
+
+- if you hit the homepage (HTTP `GET` request to `/`)
+- if you submit a form to the wrong URL (`POST` request to `/non-existing-form`)
+- if `hasemail` is enabled for the form (like in the example above) and you don't submit an `email` field
+
+If you get banned, you'd need to restart the process by running the playbook with `--tags=start` or running `systemctl restart matrix-bot-buscarron` on the server.
+
 You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/buscarron).

docs/configuring-playbook-bot-chatgpt.md

@@ -0,0 +1,69 @@
+# Setting up ChatGPT (optional)
+
+The playbook can install and configure [matrix-chatgpt-bot](https://github.com/matrixgpt/matrix-chatgpt-bot) for you.
+
+Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client!
+
+
+## 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.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+```
+
+
+## 2. Get an access token and create encryption keys
+
+Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+
+To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [element documentation](https://element.io/help#encryption6).
+
+
+## 3. 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_chatgpt_enabled: true
+
+# Obtain a new API key from https://platform.openai.com/account/api-keys
+matrix_bot_chatgpt_openai_api_key: ''
+
+# This is the default username
+# matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt'
+
+# Matrix access token (from bot user above)
+# see: https://webapps.stackexchange.com/questions/131056/how-to-get-an-access-token-for-element-riot-matrix
+matrix_bot_chatgpt_matrix_access_token: ''
+
+# Configuring the system promt used, needed if the bot is used for special tasks.
+# More information: https://github.com/mustvlad/ChatGPT-System-Prompts
+matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.'
+
+```
+
+You will need to get tokens for ChatGPT.
+
+
+## 4. Installing
+
+After configuring the playbook, run the [installation](installing.md) command again:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+```
+
+
+## Usage
+
+To use the bot, invite the `@bot.chatgpt:DOMAIN` to the room you specified in a config, after that start speaking to it, use the prefix if you configured one or mention the bot.
+
+You can also refer to the upstream [documentation](https://github.com/matrixgpt/matrix-chatgpt-bot).

docs/configuring-playbook-bot-draupnir.md

@@ -0,0 +1,110 @@
+# Setting up draupnir (optional)
+
+The playbook can install and configure the [draupnir](https://github.com/the-draupnir-project/Draupnir) moderation bot for you.
+
+See the project's [documentation](https://github.com/the-draupnir-project/Draupnir) to learn what it does and why it might be useful to you.
+
+If your migrating from Mjolnir skip to step 5b.
+
+## 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.draupnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+```
+
+If you would like draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports ([see below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
+
+
+## 2. Get an access token
+
+Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+
+
+## 3. Make sure the account is free from rate limiting
+
+You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step draupnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
+
+If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](/docs/configuring-playbook-synapse-admin.md) or running `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands. 
+
+The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@example:example.com/override_ratelimit` Replace `@example:example.com` with the MXID of your Draupnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Draupnir it self. If you made Draupnir Admin you can just use the Draupnir token.
+
+
+
+## 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.draupnir:DOMAIN` account you created earlier into the room.
+
+
+## 5a. 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_draupnir_enabled: true
+
+matrix_bot_draupnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
+
+matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+```
+
+## 5b. Migrating from Mjolnir (Only required if migrating.)
+
+Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable mjolnir if you're doing migration.
+That is all you need to do due to that Draupnir can complete migration on its own.
+
+## 6. 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/the-draupnir-project/Draupnir) for additional ways to use and configure draupnir. Check out their [quickstart guide](https://github.com/the-draupnir-project/Draupnir/blob/main/docs/moderators.md#quick-usage) for some basic commands you can give to the bot.
+
+You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file.
+
+For example to change draupnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
+
+```yaml
+matrix_bot_draupnir_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_bot_draupnir_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_bot_draupnir_configuration_yaml`.
+  recordIgnoredInvites: true
+```
+
+## Abuse Reports
+
+Draupnir supports two methods to receive reports in the management room.
+
+The first method intercepts the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver.
+While this playbook uses reverse proxies, it does not yet implement this.
+
+The other method polls an synapse admin API endpoint and is hence only available when using synapse and when the Draupnir user is an admin user (see step 1).
+To enable it, set `pollReports: true` in Draupnir's config:
+```yaml
+matrix_bot_draupnir_configuration_extension_yaml: |
+  pollReports: true
+```

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

@@ -24,6 +24,31 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb
 Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
 
 
+## Decide on a domain and path
+
+By default, Go-NEB is configured to use its own dedicated domain (`goneb.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+You can override the domain and path like this:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
+# so we won't need to add additional DNS records for Go-NEB.
+matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /go-neb subpath
+matrix_bot_go_neb_path_prefix: /go-neb
+```
+
+**NOTE**: When using `matrix-nginx-proxy` instead of Traefik, you won't be able to override the path prefix. You can only override the domain, but that needs to happen using another variable: `matrix_server_fqn_go_neb` (e.g. `matrix_server_fqn_go_neb: "mybot.{{ matrix_domain }}"`).
+
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+
 ## Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
@@ -193,9 +218,7 @@ matrix_bot_go_neb_services:
 
 ## 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:
+After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

docs/configuring-playbook-bot-honoroit.md

@@ -14,6 +14,10 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
 ```yaml
 matrix_bot_honoroit_enabled: true
 
+# Uncomment and adjust if you'd like to change the hostname or path
+# matrix_bot_honoroit_hostname: "{{ matrix_server_fqn_matrix }}"
+# matrix_bot_honoroit_path_prefix: /honoroit
+
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_honoroit_login: honoroit
 

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

@@ -2,40 +2,28 @@
 
 The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
 
-The bot allows you to easily **create and manage registration tokens**. It can be used for an invitation-based server,
-where you invite someone by sending them a registration token. They can register as normal but have to provide a valid
-registration token in a final step  of the registration.
+The bot allows you to easily **create and manage registration tokens** aka. invitation codes.
+It can be used for an invitation-based server,
+where you invite someone by sending them a registration token (loook like this: `rbalQ0zkaDSRQCOp`). 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
+## Configuration
 
-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).
-
-For [other bots supported by the playbook](configuring-playbook.md#bots), Matrix bot user accounts are created and put to use automatically. For `matrix-registration-bot`, however, this is not the case - you **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
-
-```
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-registration-bot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
-```
-
-Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
-
-## Obtaining an admin access token
-
-In order to use the bot you need to add an admin user's access token token to the configuration. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
-
-## Adjusting the playbook configuration
-
-Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+To enable the bot, 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"
+
+#By default, the playbook will set use the bot with a username like 
+## this: `@bot.matrix-registration-bot:DOMAIN`.
+# To use a different username, uncomment & adjust the variable.
+# matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot
+
+# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
+matrix_bot_matrix_registration_bot_bot_password: PASSWORD_FOR_THE_BOT
 
 # Enables registration
 matrix_synapse_enable_registration: true
@@ -44,6 +32,7 @@ matrix_synapse_enable_registration: true
 matrix_synapse_registration_requires_token: true
 ```
 
+The bot account will be automatically created.
 
 ## Installing
 
@@ -56,10 +45,16 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
 ## Usage
 
-To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain).
+To use the bot, message `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain).
 
 In this room send `help` and the bot will reply with all options.
 
 You can also refer to the upstream [Usage documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands).
 If you have any questions, or if you need help setting it up, read the [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md)
 or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
+
+To clean the cache (session&encryption data) after you changed the bot's username, changed the login methon form access_token to password etc.. you can use
+
+```bash
+just run-tags bot-matrix-registration-bot-clean-cache
+```

docs/configuring-playbook-bot-mjolnir.md

@@ -29,31 +29,11 @@ Refer to the documentation on [how to obtain an access token](obtaining-access-t
 
 ## 3. Make sure the account is free from rate limiting
 
-You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). This can also be manually done by editing the Synapse database. Manually editing the Synapse database is rarely a good idea. Please ask for help if you are uncomfortable with these steps.
+You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
 
-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.
+If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](/docs/configuring-playbook-synapse-admin.md) or running `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands. 
 
+The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@example:example.com/override_ratelimit` Replace `@example:example.com` with the MXID of your Mjolnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Mjolnir it self. If you made Mjolnir Admin you can just use the Mjolnir token.
 
 ## 4. Create a management room
 

docs/configuring-playbook-bot-postmoogle.md

@@ -4,12 +4,26 @@
 
 The playbook can install and configure [Postmoogle](https://gitlab.com/etke.cc/postmoogle) for you.
 
-It's a bot/bridge you can use to forward emails to Matrix rooms
+It's a bot/bridge you can use to forward emails to Matrix rooms. 
+Postmoogle runs an SMTP email server and allows you to assign mailbox addresses to Matrix rooms.
 
 See the project's [documentation](https://gitlab.com/etke.cc/postmoogle) to learn what it does and why it might be useful to you.
 
+## Prerequisites
 
-## Adjusting the playbook configuration
+### Networking
+
+Open the following ports on your server to be able to receive incoming emails:
+
+  - `25/tcp`: SMTP
+  - `587/tcp`: Submission (TLS-encrypted SMTP)
+
+If you don't open these ports, you will still be able to send emails, but not receive any.
+
+These port numbers are configurable via the `matrix_bot_postmoogle_smtp_host_bind_port` and `matrix_bot_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
+
+
+### Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
@@ -21,9 +35,20 @@ matrix_bot_postmoogle_enabled: true
 
 # Generate a strong password here. Consider generating it with `pwgen -s 64 1`
 matrix_bot_postmoogle_password: PASSWORD_FOR_THE_BOT
+
+# Uncomment to add one or more admins to this bridge:
+#
+# matrix_bot_postmoogle_admins:
+#  - '@yourAdminAccount:domain.com'
+#
+# .. unless you've made yourself an admin of all bridges like this:
+#
+# matrix_admin: '@yourAdminAccount:domain.com'
 ```
 
-You will also need to add several DNS records so that postmoogle can send emails.
+### DNS
+
+You will also need to add several DNS records so that Postmoogle can send emails.
 See [Configuring DNS](configuring-dns.md).
 
 
@@ -51,3 +76,13 @@ Then send `!pm mailbox NAME` to expose this Matrix room as an inbox with the ema
 Send `!pm help` to the room to see the bot's help menu for additional commands.
 
 You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/postmoogle).
+
+### Debug/Logs
+
+As with all other services, you can find their logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-bot-postmoogle`
+
+The default logging level for this bridge is `INFO`, but you can increase it to `DEBUG` with the following additional configuration: 
+
+```yaml
+matrix_bot_postmoogle_loglevel: 'DEBUG'
+```

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

@@ -1,7 +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) and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.   
-- For using as a Bot we are recommend the Appservice Discord bridge (the one being discussed here), because it supports plumbing.  
+**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.
+- For using as a Bot we are recommend the Appservice Discord bridge (the one being discussed here), because it supports plumbing.
 - For personal use we recommend the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge, because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
 
 The playbook can install and configure [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) for you.
@@ -23,8 +23,14 @@ matrix_appservice_discord_enabled: true
 matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
 matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
 ```
+5. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
+```yaml
+matrix_synapse_configuration_extension_yaml: |
+  use_appservice_legacy_authorization: true
+```
+*Note*: This deprecated method is considered insecure.
 
-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.
+6. 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.
 

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

@@ -1,6 +1,6 @@
 # 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.
+**Note**: bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook.
 
 The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
 

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

@@ -26,22 +26,29 @@ you can adjust this in `inventory/host_vars/matrix.<domain-name>/vars.yml` as we
 matrix_appservice_webhooks_log_level: '<log_level>'
 ```
 
-3. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
+3. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
+```yaml
+matrix_synapse_configuration_extension_yaml: |
+  use_appservice_legacy_authorization: true
+```
+*Note*: This deprecated method is considered insecure.
 
-4. If you're using the [Dimension Integration Manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL"  & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively. 
+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. Invite the bridge bot user to your room:
+5. If you're using the [Dimension Integration Manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL"  & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
+
+6. Invite the bridge bot user to your room:
 
     - either with `/invite @_webhook:<domain.name>` (*Note*: Make sure you have administration permissions in your room)
 
     - or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
 
-6. Send a message to the bridge bot in order to receive a private message including the webhook link.
+7. Send a message to the bridge bot in order to receive a private message including the webhook link.
 ```
 !webhook
 ```
 
-7. The JSON body for posting messages will have to look like this:
+8. The JSON body for posting messages will have to look like this:
 ```json
 {
     "text": "Hello world!",

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

@@ -32,14 +32,10 @@ You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/co
 
 ## 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
+If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have to enable Shared Secred 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
 

docs/configuring-playbook-bridge-hookshot.md

@@ -16,7 +16,7 @@ Refer to the [official instructions](https://matrix-org.github.io/matrix-hooksho
 1. Enable the bridge by adding `matrix_hookshot_enabled: true` to your `vars.yml` file
 2. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
 3. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
-4. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below.
+4. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-aux-role) explained below.
 5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
 
 Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
@@ -58,23 +58,23 @@ See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles
 
 The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
 
-### Manage GitHub Private Key with matrix-aux role
+### Manage GitHub Private Key with aux role
 
 The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
 - copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml)).
 - somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
-- use the `matrix-aux` role to copy the file from an arbitrary path on your ansible client to the correct path on the server.
+- use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
 
-To use `matrix-aux`, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add to `matrix-aux` configuration like this:
+To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration:
 ```yaml
-matrix_aux_file_definitions:
+aux_file_definitions:
   - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
     content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
     mode: '0400'
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
 ```
-For more info see the documentation in the [matrix-aux base configuration file](/roles/custom/matrix-aux/defaults/main.yml).
+For more information, see the documentation in the [default configuration of the aux role](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml).
 
 ### Provisioning API
 
@@ -93,4 +93,4 @@ To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This
 
 ### Collision with matrix-appservice-webhooks
 
-If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_user_id_prefix: '_webhooks_'`).
+If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_userIdPrefix: '_webhooks_'`).

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

@@ -0,0 +1,38 @@
+# Setting up Mautrix gmessages (optional)
+
+The playbook can install and configure [mautrix-gmessages](https://github.com/mautrix/gmessages) for you, for bridging to [Google Messages](https://messages.google.com/).
+
+See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/index.html) to learn what it does and why it might be useful to you.
+
+Use the following playbook configuration:
+
+```yaml
+matrix_mautrix_gmessages_enabled: true
+```
+
+## Set up Double Puppeting
+
+If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+
+### Method 1: automatically, by enabling Shared Secret Auth
+
+The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+### Method 2: manually, by asking each user to provide a working access token
+
+**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-gmessages` device some time in the future, as that would break the Double Puppeting feature
+
+
+## Usage
+
+You then need to start a chat with `@gmessagesbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

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

@@ -0,0 +1,75 @@
+# Setting up Mautrix Slack (optional)
+
+**Note**: bridging to [Slack](https://slack.com/) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) bridges supported by the playbook.
+- For using as a Bot we recommend the [Appservice Slack](configuring-playbook-bridge-appservice-slack.md), because it supports plumbing.
+- For personal use with a slack account we recommend the `mautrix-slack` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Slack bridges supported by the playbook.
+
+The playbook can install and configure [mautrix-slack](https://github.com/mautrix/slack) for you.
+
+See the project's [documentation](https://docs.mau.fi/bridges/go/slack/index.html) to learn what it does and why it might be useful to you.
+
+See the [features and roadmap](https://github.com/mautrix/slack/blob/main/ROADMAP.md) for more information.
+
+
+## Prerequisites
+
+For using this bridge, you would need to authenticate by **providing your username and password** (legacy) or by using a **token login**. See more information in the [docs](https://docs.mau.fi/bridges/go/slack/authentication.html).
+
+Note that neither of these methods are officially supported by Slack. [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) uses a Slack bot account which is the only officially supported method for bridging a Slack channel.
+
+
+## Installing
+
+To enable the bridge, add this to your `vars.yml` file:
+
+```yaml
+matrix_mautrix_slack_enabled: true
+```
+
+You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
+
+After adjusting your `vars.yml` file, re-run the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
+
+To make use of the bridge, see [Usage](#usage) below.
+
+
+### Additional configuration
+
+There are some additional options you may wish to configure with the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bridge-mautrix-slack/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_slack_configuration_extension_yaml` variable
+
+
+### Set up Double Puppeting
+
+If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Shared Secret Auth
+
+The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature
+
+
+## Usage
+
+1. Start a chat with `@slackbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+2. If you would like to login to Slack using a token, send the `login-token` command, otherwise, send the `login-password` command. Read [here](https://docs.mau.fi/bridges/go/slack/authentication.html) on how to retrieve your token and cookie token.
+3. The bot should respond with "Successfully logged into <email> for team <workspace>"
+4. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to.
+5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication.

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

@@ -11,6 +11,19 @@ matrix_mautrix_whatsapp_enabled: true
 ``` 
 Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
 
+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_whatsapp_bridge_relay_enabled: true
+```
+
+By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users add this to your `vars.yml` file:
+```yaml
+matrix_mautrix_whatsapp_bridge_relay_admin_only: false
+```
+
+If you want to activate the relay bot in a room, use `!whatsapp set-relay`.
+Use `!whatsapp unset-relay` to deactivate.
+
 ## 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.

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

@@ -0,0 +1,33 @@
+# Setting up Mautrix wsproxy (optional)
+
+The playbook can install and configure [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for you.
+
+See the project's [documentation](https://github.com/mautrix/wsproxy#readme) to learn what it does and why it might be useful to you.
+
+
+## DNS
+
+You need to create a `wsproxy.DOMAIN` DNS record pointing to your Matrix server (a `CNAME` pointing to `matrix.DOMAIN`) to use wsproxy.
+The hostname is configurable via a `matrix_mautrix_wsproxy_hostname` variable.
+
+
+## Configuration
+
+Use the following playbook configuration:
+
+```yaml
+matrix_mautrix_wsproxy_enabled: true
+
+matrix_mautrix_androidsms_appservice_token: 'secret token from bridge'
+matrix_mautrix_androidsms_homeserver_token: 'secret token from bridge'
+matrix_mautrix_imessage_appservice_token: 'secret token from bridge'
+matrix_mautrix_imessage_homeserver_token: 'secret token from bridge'
+matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
+```
+
+Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device.
+
+
+## Usage
+
+Follow the [matrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).

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

@@ -1,8 +1,7 @@
 # Setting up MX Puppet Slack (optional)
 
 **Note**: bridging to [Slack](https://slack.com) can also happen via the
-[matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md)
-bridge supported by the playbook.
+[matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges 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.

docs/configuring-playbook-cactus-comments.md

@@ -24,7 +24,7 @@ matrix_cactus_comments_enabled: true
 # To do this you need to uncomment one of the following lines (depending if you are using synapse or dentrite as a homeserver)
 # If you don't know which one you use: The default is synapse ;)
 # matrix_synapse_allow_guest_access: true
-# matrix_dentrite_allow_guest_access
+# matrix_dentrite_allow_guest_access: true
 ```
 
 ## Installing

docs/configuring-playbook-client-element.md

@@ -32,7 +32,7 @@ Alternatively, **if there is no pre-defined variable** for an Element setting yo
 
 ## Themes
 
-To change the look of Element, you can define your own themes manually by using the `matrix_client_element_settingDefaults_custom_themes` setting.
+To change the look of Element, you can define your own themes manually by using the `matrix_client_element_setting_defaults_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`).
 

docs/configuring-playbook-client-schildichat.md

@@ -0,0 +1,42 @@
+# Configuring SchildiChat (optional)
+
+By default, this playbook does not install the [SchildiChat](https://github.com/SchildiChat/schildichat-desktop) Matrix client web application.
+
+**WARNING**: SchildiChat is based on Element-web, but its releases are lagging behind. As an example (from 2023-08-31), SchildiChat is 10 releases behind (it being based on element-web `v1.11.30`, while element-web is now on `v1.11.40`). Element-web frequently suffers from security issues, so running something based on an ancient Element-web release is **dangerous**. Use SchildiChat at your own risk!
+
+
+## Enabling SchildiChat
+
+If you'd like for the playbook to install SchildiChat, you can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+
+```yaml
+matrix_client_schildichat_enabled: true
+```
+
+
+## Configuring SchildiChat settings
+
+The playbook provides some customization variables you could use to change schildichat's settings.
+
+Their defaults are defined in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml) and they ultimately end up in the generated `/matrix/schildichat/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-schildichat/templates/config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2) template.
+
+**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 schildichat setting you wish to change:
+
+- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of schildichat's various settings that rarely get used.
+
+- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2)) by making use of the `matrix_client_schildichat_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
+
+- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_schildichat_configuration_default` (or `matrix_client_schildichat_configuration`). You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
+
+
+## Themes
+
+To change the look of schildichat, you can define your own themes manually by using the `matrix_client_schildichat_setting_defaults_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_schildichat_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 schildichat instances that you use must have the same theme installed.

docs/configuring-playbook-dimension.md

@@ -3,17 +3,34 @@
 **[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**: Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
+
 **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
+## Decide on a domain and path
 
-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.
+By default, Dimension is configured to use its own dedicated domain (`dimension.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+You can override the domain and path like this:
+
+```yaml
+# Switch to another hostname compared to the default (`dimension.{{ matrix_domain }}`)
+matrix_dimension_hostname: "integrations.{{ matrix_domain }}"
+
+```
+
+While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible right now due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain until this issue is solved.
+
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
 
 
 ## Enable
 
-[Dimension integrations manager](https://dimension.t2bot.io) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
 
 ```yaml
 matrix_dimension_enabled: true
@@ -54,7 +71,7 @@ For more information on how to acquire an access token, visit [https://t2bot.io/
 
 ## Installation
 
-After these variables have been set, please run the following command to re-run setup and to restart Dimension:
+After these variables have been set and you have potentially [adjusted your DNS records](#adjusting-dns-records), please run the following command to re-run setup and to restart Dimension:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

docs/configuring-playbook-etherpad.md

@@ -1,19 +1,41 @@
 # 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) or used as standalone web app.
+[Etherpad](https://etherpad.org) 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) or used as standalone web app.
 
 When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
 
 
-## Prerequisites
+## Decide on a domain and path
 
-Etherpad can be installed in 2 modes:
+By default, Etherpad is configured to use its own dedicated domain (`etherpad.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
 
-- (default) `standalone` mode (`matrix_etherpad_mode: standalone`) - Etherpad will be hosted on `etherpad.<your-domain>` (`matrix_server_fqn_etherpad`), so the DNS record for this domian must be created. See [Configuring your DNS server](configuring-dns.md) on how to set up the `etherpad` DNS record correctly
+You can override the domain and path like this:
 
-- `dimension` mode (`matrix_etherpad_mode: dimension`) - Etherpad will be hosted on `dimension.<your-domain>/etherpad` (`matrix_server_fqn_dimension`). This requires that you **first** configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
+```yaml
+# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
+# so we won't need to add additional DNS records for Etherpad.
+etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
 
-We recomend that you go with the default (`standalone`) mode, which makes Etherpad independent and allows it to be used with or without Dimension.
+# Expose under the /etherpad subpath
+etherpad_path_prefix: /etherpad
+```
+
+**NOTE**: When using the old `matrix-nginx-proxy` reverse-proxy instead of Traefik, you have only 2 choices:
+
+- serving Etherpad at its own dedicated domain:
+  - you need to set the domain using the `matrix_server_fqn_etherpad` variable (not `etherpad_hostname`)
+  - you must use `etherpad_path_prefix: /`
+- serving Etherpad at the [Dimension](configuring-playbook-dimension.md) integration manager's domain (`matrix_server_fqn_dimension`)
+  - you need to have Dimension enabled
+  - you need to add `etherpad_path_prefix: /etherpad` or another prefix (different than `/`)
+  - you need to add `etherpad_nginx_proxy_dimension_integration_enabled: true` to enable this integration
+
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
 
 ## Installing
@@ -21,48 +43,51 @@ We recomend that you go with the default (`standalone`) mode, which makes Etherp
 [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
-
-# Uncomment below if you'd like to install Etherpad on the Dimension domain (not recommended)
-# matrix_etherpad_mode: dimension
+etherpad_enabled: true
 
 # Uncomment below to enable the admin web UI
-# matrix_etherpad_admin_username: admin
-# matrix_etherpad_admin_password: some-password
+# etherpad_admin_username: admin
+# etherpad_admin_password: some-password
 ```
 
-If enabled, the admin web-UI should then be available on `https://etherpad.<your-domain>/admin` (or `https://dimension.<your-domain>/etherpad/admin`, if `matrix_etherpad_mode: dimension`)
+Then, [run the installation process](installing.md) again (e.g. `just install-all`).
 
 
-## Managing / Deleting old pads
+## Usage
+
+The Etherpad UI should be available at `https://etherpad.<your-domain>`, while the admin UI (if enabled) should then be available at `https://etherpad.<your-domain>/admin`.
+
+If you've [decided on another hostname or path-prefix](#decide-on-a-domain-and-path) (e.g. `https://matrix.DOMAIN/etherpad`), adjust these URLs accordingly before usage.
+
+
+### 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://etherpad.<your-domain>/admin/plugins` or `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.
+Then from the plugin manager page (`https://etherpad.<your-domain>/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
 
 
-## How to use Etherpad widgets without an Integration Manager (like Dimension)
+### How to use Etherpad widgets without an Integration Manager (like Dimension)
 
 This is how it works in Element, it might work quite similar with other clients:
 
 To integrate a standalone etherpad in a room, create your pad by visiting `https://etherpad.DOMAIN`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section.
 
 
-## Set Dimension default to the self-hosted Etherpad (optional)
+### Set Dimension default to the self-hosted Etherpad (optional)
 
 If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside 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.
 
 
-### Removing the integrated Etherpad chat
+#### 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. Examples:
-- `https://etherpad.<your-domain>/p/$roomId_$padName?showChat=false` (for the default - `matrix_etherpad_mode: standalone`)
+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.
 
-- `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false` (for `matrix_etherpad_mode: dimension`)
+Example: `https://etherpad.<your-domain>/p/$roomId_$padName?showChat=false`
 
 
-### Known issues
+## 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

@@ -10,7 +10,7 @@ If you'd like to use an external PostgreSQL server that you manage, you can edit
 If you'd like to use an external Postgres server, use a custom `vars.yml` configuration like this:
 
 ```yaml
-matrix_postgres_enabled: false
+devture_postgres_enabled: false
 
 # Rewire Synapse to use your external Postgres server
 matrix_synapse_database_host: "your-postgres-server-hostname"

docs/configuring-playbook-jitsi.md

@@ -9,12 +9,12 @@ The setup done by the playbook is very similar to [docker-jitsi-meet](https://gi
 
 ## Prerequisites
 
-Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record. See [Configuring DNS](configuring-dns.md).
+Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record (unless you've changed `jitsi_hostname`, as described below). See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 You may also need to open the following ports to your server:
 
 - `4443/tcp` - RTP media fallback over TCP
-- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/custom/matrix-jitsi/defaults/main.yml)).
+- `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 [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
 
 
 ## Installation
@@ -22,62 +22,86 @@ You may also need to open the following ports to your server:
 Add this to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
 
 ```yaml
-matrix_jitsi_enabled: true
+jitsi_enabled: true
 
-# Run `bash inventory/scripts/jitsi-generate-passwords.sh` to generate these passwords,
-# or define your own strong passwords manually.
-matrix_jitsi_jicofo_auth_password: ""
-matrix_jitsi_jvb_auth_password: ""
-matrix_jitsi_jibri_recorder_password: ""
-matrix_jitsi_jibri_xmpp_password: ""
+# Uncomment and adjust if you need to use another hostname
+# jitsi_hostname: "jitsi.{{ matrix_domain }}"
+
+# Uncomment and possible adjust if you'd like to host under a subpath
+# jitsi_path_prefix: /jitsi
 ```
 
-
 ## (Optional) Configure Jitsi authentication and guests mode
 
 By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.
 
 If you're fine with such an open Jitsi instance, please skip to [Apply changes](#apply-changes).
 
-If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow this step to enable Jitsi's authentication and guests mode. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms.
+If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow the following steps to enable Jitsi's authentication and optionally guests mode.
+Currently, there are three supported authentication modes: 'internal' (default), 'matrix' and 'ldap'.
+
+**Note:** Authentication is not tested via the playbook's self-checks.
+We therefore recommend that you manually verify if authentication is required by jitsi.
+For this, try to manually create a conference on jitsi.DOMAIN in your browser.
+
+### Authenticate using Jitsi accounts (Auth-Type 'internal')
+The default authentication mechanism is 'internal' auth, which requires jitsi-accounts to be setup and is the recommended setup, as it also works in federated rooms.
+With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join.
+If a registered host is not yet present, guests are put on hold in individual waiting rooms.
 
 Add these lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
 
 ```yaml
-matrix_jitsi_enable_auth: true
-matrix_jitsi_enable_guests: true
-matrix_jitsi_prosody_auth_internal_accounts:
+jitsi_enable_auth: true
+jitsi_enable_guests: true
+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.
+**Caution:** Accounts added here and subsequently 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).
 
+### Authenticate using Matrix OpenID (Auth-Type 'matrix')
 
-### (Optional) LDAP authentication
+**Attention: Probably breaks Jitsi in federated rooms and does not allow sharing conference links with guests.**
 
-The default authentication mode of Jitsi is `internal`, however LDAP is also supported. An example LDAP configuration could be:
+Using this authentication type require a [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service).
+By default, this playbook creates and configures a user-verification-service to run locally, see [configuring-user-verification-service](configuring-playbook-user-verification-service.md).
+
+To enable set this configuration at host level:
 
 ```yaml
-matrix_jitsi_enable_auth: true
-matrix_jitsi_auth_type: ldap
-matrix_jitsi_ldap_url: "ldap://ldap.DOMAIN"
-matrix_jitsi_ldap_base: "OU=People,DC=DOMAIN
-#matrix_jitsi_ldap_binddn: ""
-#matrix_jitsi_ldap_bindpw: ""
-matrix_jitsi_ldap_filter: "uid=%u"
-matrix_jitsi_ldap_auth_method: "bind"
-matrix_jitsi_ldap_version: "3"
-matrix_jitsi_ldap_use_tls: true
-matrix_jitsi_ldap_tls_ciphers: ""
-matrix_jitsi_ldap_tls_check_peer: true
-matrix_jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
-matrix_jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
-matrix_jitsi_ldap_start_tls: false
+jitsi_enable_auth: true
+jitsi_auth_type: matrix
+matrix_user_verification_service_enabled: true
+```
+
+For more information see also [https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification](https://github.com/matrix-org/prosody-mod-auth-matrix-user-verification).
+
+### Authenticate using LDAP (Auth-Type 'ldap')
+
+An example LDAP configuration could be:
+
+```yaml
+jitsi_enable_auth: true
+jitsi_auth_type: ldap
+jitsi_ldap_url: "ldap://ldap.DOMAIN"
+jitsi_ldap_base: "OU=People,DC=DOMAIN"
+#jitsi_ldap_binddn: ""
+#jitsi_ldap_bindpw: ""
+jitsi_ldap_filter: "uid=%u"
+jitsi_ldap_auth_method: "bind"
+jitsi_ldap_version: "3"
+jitsi_ldap_use_tls: true
+jitsi_ldap_tls_ciphers: ""
+jitsi_ldap_tls_check_peer: true
+jitsi_ldap_tls_cacert_file: "/etc/ssl/certs/ca-certificates.crt"
+jitsi_ldap_tls_cacert_dir: "/etc/ssl/certs"
+jitsi_ldap_start_tls: false
 ```
 
 For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
@@ -94,7 +118,7 @@ Here is how to do it in the playbook.
 Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
 
 ```yaml
-matrix_jitsi_jvb_container_extra_arguments:
+jitsi_jvb_container_extra_arguments:
   - '--env "JVB_ADVERTISE_IPS=<Local IP address of the host>"'
 ```
 
@@ -103,7 +127,7 @@ matrix_jitsi_jvb_container_extra_arguments:
 Sample **additional** `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration to save up resources (explained below):
 
 ```yaml
-matrix_jitsi_web_custom_config_extension: |
+jitsi_web_custom_config_extension: |
   config.enableLayerSuspension = true;
 
   config.disableAudioLevels = true;
@@ -111,13 +135,12 @@ matrix_jitsi_web_custom_config_extension: |
   // 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
+jitsi_web_config_resolution_width_ideal_and_max: 480
+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.
 
@@ -127,12 +150,22 @@ Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/
 
 You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
 
+## (Optional) Specify a Max number of participants on a Jitsi conference
+
+The playbook allows a user to set a max number of participants allowed to join a Jitsi conference. By default there is no limit.
+
+In order to set the max number of participants use the following **additional** configuration:
+
+```yaml
+jitsi_prosody_max_participants: 4 # example value
+```
+
 ## (Optional) Additional JVBs
 
 By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)) is deployed on the same host as the Matrix server. To allow more video-conferences to happen at the same time, you may need to provision additional JVB services on other hosts.
 
 There is an ansible playbook that can be run with the following tag:
-` ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
+`ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
 
 For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
 ```
@@ -140,18 +173,18 @@ For this role to work you will need an additional section in the ansible hosts f
 <your jvb hosts> ansible_host=<ip address of the jvb host>
 ```
 
-Each JVB will require a server id to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB.  
-The server id is set with the variable `matrix_jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container. 
+Each JVB will require a server id to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB.
+The server id is set with the variable `jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container.
 This variable can be set via the host file, a parameter to the ansible command or in the `vars.yaml` for the host which will have the additional JVB. For example:
 
 ``` yaml
-matrix_jitsi_jvb_server_id: 'jvb-2'
+jitsi_jvb_server_id: 'jvb-2'
 ```
 
 ``` INI
 [jitsi_jvb_servers]
-jvb-2.example.com ansible_host=192.168.0.2 matrix_jitsi_jvb_server_id=jvb-2
-jvb-3.example.com ansible_host=192.168.0.3 matrix_jitsi_jvb_server_id=jvb-2
+jvb-2.example.com ansible_host=192.168.0.2 jitsi_jvb_server_id=jvb-2
+jvb-3.example.com ansible_host=192.168.0.3 jitsi_jvb_server_id=jvb-2
 ```
 
 Note that the server id `jvb-1` is reserved for the JVB instance running on the Matrix host and therefore should not be used as the id of an additional jvb host.
@@ -159,38 +192,84 @@ Note that the server id `jvb-1` is reserved for the JVB instance running on the
 The additional JVB will also need to expose the colibri web socket port and this can be done with the following variable:
 
 ```yaml
-matrix_jitsi_jvb_container_colibri_ws_host_bind_port: 9090
+jitsi_jvb_container_colibri_ws_host_bind_port: 9090
 ```
 
-The JVB will also need to know where the prosody xmpp server is located, similar to the server id this can be set in the vars for the JVB by using the variable 
-`matrix_jitsi_xmpp_server`. The Jitsi prosody container is deployed on the matrix server by default so the value can be set to the matrix domain. For example:
+The JVB will also need to know where the prosody xmpp server is located, similar to the server id this can be set in the vars for the JVB by using the variable
+`jitsi_xmpp_server`. The Jitsi prosody container is deployed on the matrix server by default so the value can be set to the matrix domain. For example:
 
 ```yaml
-matrix_jitsi_xmpp_server: "{{ matrix_domain }}"
+jitsi_xmpp_server: "{{ matrix_domain }}"
 ```
 
 However, it can also be set the ip address of the matrix server. This can be useful if you wish to use a private ip. For example:
 
 ```yaml
-matrix_jitsi_xmpp_server: "192.168.0.1"
+jitsi_xmpp_server: "192.168.0.1"
 ```
 
-The nginx configuration will also need to be updated in order to deal with the additional JVB servers. This is achieved via its own configuration variable
-`matrix_nginx_proxy_proxy_jitsi_additional_jvbs`, which contains a dictionary of server ids to ip addresses.
+For the JVB to be able to contact the XMPP server, the latter must expose the XMPP port (5222). By default, the Matrix server does not expose the
+port; only the XMPP container exposes it internally inside the host, which means that the first JVB (which runs on the Matrix server) can reach it but
+the additional JVB cannot. The port is exposed by setting `jitsi_prosody_container_jvb_host_bind_port` like this:
 
-For example,
-
-``` yaml
-matrix_nginx_proxy_proxy_jitsi_additional_jvbs:
-   jvb-2: 192.168.0.2
-   jvb-3: 192.168.0.3
+```yaml
+jitsi_prosody_container_jvb_host_bind_port: 5222
 ```
 
+(The default is empty; if it's set then docker forwards the port.)
 
-Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo 
+Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo
 to route conferences too.
 
+To make Traefik reverse-proxy to these additional JVBs (living on other hosts), **you would need to add the following Traefik configuration extension**:
 
+```yaml
+# Traefik proxying for additional JVBs. These can't be configured using Docker
+# labels, like the first JVB is, because they run on different hosts, so we add
+# the necessary configuration to the file provider.
+devture_traefik_provider_configuration_extension_yaml: |
+  http:
+   routers:
+     {% for host in groups['jitsi_jvb_servers'] %}
+
+     additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-router:
+       entryPoints:
+         - "{{ devture_traefik_entrypoint_primary }}"
+       rule: "Host(`{{ jitsi_hostname }}`) && PathPrefix(`/colibri-ws/{{ hostvars[host]['jitsi_jvb_server_id'] }}/`)"
+       service: additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service
+       {% if devture_traefik_entrypoint_primary != 'web' %}
+
+       tls:
+         certResolver: "{{ devture_traefik_certResolver_primary }}"
+
+       {% endif %}
+
+     {% endfor %}
+
+   services:
+     {% for host in groups['jitsi_jvb_servers'] %}
+
+     additional-{{ hostvars[host]['jitsi_jvb_server_id'] }}-service:
+       loadBalancer:
+         servers:
+           - url: "http://{{ host }}:9090/"
+
+     {% endfor %}
+```
+
+## (Optional) Enable Gravatar
+
+In the default Jisti Meet configuration, gravatar.com is enabled as an avatar service. This results in third party request leaking data to gravatar.
+Since element already sends the url of configured Matrix avatars to Jitsi, we disabled gravatar.
+
+To enable Gravatar set:
+
+```yaml
+jitsi_disable_gravatar: false
+```
+
+**Beware:** This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com).
+Besides metadata, this includes the matrix user_id and possibly the room identifier (via `referrer` header).
 
 ## Apply changes
 
@@ -214,7 +293,7 @@ You can use the self-hosted Jitsi server in multiple ways:
 
 ### Rebuilding your Jitsi installation
 
-**If you ever run into any trouble** or **if you change configuration (`matrix_jitsi_*` variables) too much**, we urge you to rebuild your Jitsi setup.
+**If you ever run into any trouble** or **if you change configuration (`jitsi_*` variables) too much**, we urge you to rebuild your Jitsi setup.
 
 We normally don't require such manual intervention for other services, but Jitsi services generate a lot of configuration files on their own.
 
@@ -222,7 +301,6 @@ These files are not all managed by Ansible (at least not yet), so you may someti
 
 To rebuild your Jitsi configuration:
 
-- SSH into the server and do this:
-  - stop all Jitsi services (`systemctl stop matrix-jitsi-*`).
-  - remove all Jitsi configuration & data (`rm -rf /matrix/jitsi`)
-- ask Ansible to set up Jitsi anew and restart services (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-jitsi,start`)
+- ask Ansible to stop all Jitsi services: `just run-tags stop-group --extra-vars=group=jitsi`
+- SSH into the server and do this and remove all Jitsi configuration & data (`rm -rf /matrix/jitsi`)
+- ask Ansible to set up Jitsi anew and restart services (`just install-service jitsi`)

docs/configuring-playbook-ldap-auth.md

@@ -8,7 +8,9 @@ If you decide that you'd like to let this playbook install it for you, you need
 
 ```yaml
 matrix_synapse_ext_password_provider_ldap_enabled: true
-matrix_synapse_ext_password_provider_ldap_uri: "ldap://ldap.mydomain.tld:389"
+matrix_synapse_ext_password_provider_ldap_uri: 
+  - "ldap://ldap-01.mydomain.tld:389"
+  - "ldap://ldap-02.mydomain.tld:389"
 matrix_synapse_ext_password_provider_ldap_start_tls: true
 matrix_synapse_ext_password_provider_ldap_base: "ou=users,dc=example,dc=com"
 matrix_synapse_ext_password_provider_ldap_attributes_uid: "uid"

docs/configuring-playbook-matrix-corporal.md

@@ -91,7 +91,7 @@ matrix_corporal_policy_provider_config: |
   }
 
 # Modify the policy below as you see fit
-matrix_aux_file_definitions:
+aux_file_definitions:
   - dest: "{{ matrix_corporal_config_dir_path }}/policy.json"
     content: |
       {

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

@@ -0,0 +1,106 @@
+# Setting up matrix-media-repo (optional)
+
+[matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/) is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
+
+Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
+
+For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
+
+## Quickstart
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
+```yaml
+matrix_media_repo_enabled: true
+
+# (optional) Turned off by default
+# matrix_media_repo_metrics_enabled: true
+```
+
+The repo is pre-configured for integrating with the Postgres database, NGINX proxy and [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) (if metrics enabled) from this playbook for all the available homeserver roles. When the media repo is enabled, other media store roles should be disabled (if using Synapse with other media store roles).
+
+By default, the media-repo will use the local filesystem for data storage. Additional options include `s3` and `IPFS` (experimental). Access token caching is also enabled by default since the logout endpoints are proxied through the media repo.
+
+## Configuring the media-repo
+
+Additional common configuration options:
+```yaml
+
+# The postgres database pooling options
+
+# The maximum number of connects to hold open. More of these allow for more concurrent
+# processes to happen.
+matrix_media_repo_database_max_connections: 25
+
+# The maximum number of connects to leave idle. More of these reduces the time it takes
+# to serve requests in low-traffic scenarios.
+matrix_media_repo_database_max_idle_connections: 5
+
+# These users have full access to the administrative functions of the media repository.
+# See https://github.com/turt2live/matrix-media-repo/blob/release-v1.2.8/docs/admin.md for information on what these people can do. They must belong to one of the
+# configured homeservers above.
+matrix_media_repo_admins:
+  admins: []
+# admins:
+#   - "@your_username:example.org"
+
+# Datastores are places where media should be persisted. This isn't dedicated for just uploads:
+# thumbnails and other misc data is also stored in these places. The media repo, when looking
+# for a datastore to use, will always use the smallest datastore first.
+matrix_media_repo_datastores:
+  datastores:
+    - type: file
+      enabled: true # Enable this to set up data storage.
+      # Datastores can be split into many areas when handling uploads. Media is still de-duplicated
+      # across all datastores (local content which duplicates remote content will re-use the remote
+      # content's location). This option is useful if your datastore is becoming very large, or if
+      # you want faster storage for a particular kind of media.
+      #
+      # The kinds available are:
+      #   thumbnails    - Used to store thumbnails of media (local and remote).
+      #   remote_media  - Original copies of remote media (servers not configured by this repo).
+      #   local_media   - Original uploads for local media.
+      #   archives      - Archives of content (GDPR and similar requests).
+      forKinds: ["thumbnails", "remote_media", "local_media", "archives"]
+      opts:
+        path: /data/media
+
+    - type: s3
+      enabled: false # Enable this to set up s3 uploads
+      forKinds: ["thumbnails", "remote_media", "local_media", "archives"]
+      opts:
+        # The s3 uploader needs a temporary location to buffer files to reduce memory usage on
+        # small file uploads. If the file size is unknown, the file is written to this location
+        # before being uploaded to s3 (then the file is deleted). If you aren't concerned about
+        # memory usage, set this to an empty string.
+        tempPath: "/tmp/mediarepo_s3_upload"
+        endpoint: sfo2.digitaloceanspaces.com
+        accessKeyId: ""
+        accessSecret: ""
+        ssl: true
+        bucketName: "your-media-bucket"
+        # An optional region for where this S3 endpoint is located. Typically not needed, though
+        # some providers will need this (like Scaleway). Uncomment to use.
+        #region: "sfo2"
+        # An optional storage class for tuning how the media is stored at s3.
+        # See https://aws.amazon.com/s3/storage-classes/ for details; uncomment to use.
+        #storageClass: STANDARD
+
+    # The media repo does support an IPFS datastore, but only if the IPFS feature is enabled. If
+    # the feature is not enabled, this will not work. Note that IPFS support is experimental at
+    # the moment and not recommended for general use.
+    #
+    # NOTE: Everything you upload to IPFS will be publicly accessible, even when the media repo
+    # puts authentication on the download endpoints. Only use this option for cases where you
+    # expect your media to be publicly accessible.
+    - type: ipfs
+      enabled: false # Enable this to use IPFS support
+      forKinds: ["local_media"]
+      # The IPFS datastore currently has no options. It will use the daemon or HTTP API configured
+      # in the IPFS section of your main config.
+      opts: {}
+
+```
+
+Full list of configuration options with documentation can be found in `roles/custom/matrix-media-repo/templates/defaults/main.yml`
+

docs/configuring-playbook-matrix-registration.md

@@ -4,6 +4,8 @@ The playbook can install and configure [matrix-registration](https://github.com/
 
 **WARNING**: this is a poorly maintained and buggy project. It's better to avoid using it.
 
+**WARNING**: this is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md)
+
 > matrix-registration is a simple python application to have a token based matrix registration.
 
 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.

docs/configuring-playbook-mautrix-bridges.md

@@ -32,7 +32,18 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
       '@YOUR_USERNAME:{{ matrix_domain }}': admin
 ```
 
+## encryption
+
 Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+
+**for all bridges with encryption support**:
+
+```yaml
+matrix_bridges_encryption_enabled: true
+```
+
+**Alternatively**, for a specific bridge:
+
 ```yaml
 matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
   bridge:
@@ -41,6 +52,24 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
       default: true
 ```
 
+## relay mode
+
+Relay mode is off by default. If you would like to enable relay mode, add the following to your `vars.yml` file:
+
+**for all bridges with relay mode support**:
+
+```yaml
+matrix_bridges_relay_enabled: true
+```
+
+**Alternatively**, for a specific bridge:
+
+```yaml
+matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
+  bridge:
+    relay:
+      enabled: true
+```
 
 You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
 

docs/configuring-playbook-nginx.md

@@ -1,7 +1,6 @@
 # Configure Nginx (optional, advanced)
 
-By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
-If that's alright, you can skip this.
+**Note**: the playbook is [in the process of moving to Traefik](../CHANGELOG.md#reverse-proxy-configuration-changes-and-initial-traefik-support). Traefik is already the default reverse-proxy for new installations and existing users are also strongly encouraged to switch to Traefik. As such, this **nginx documentation below may be incomplete or misleading**.
 
 
 ## Using Nginx status

docs/configuring-playbook-ntfy.md

@@ -15,17 +15,23 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
 
 ```yaml
 # Enabling it is the only required setting
-matrix_ntfy_enabled: true
+ntfy_enabled: true
 
-# Some other options
-matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
-matrix_ntfy_configuration_extension_yaml: |
-  log_level: DEBUG
+# This is the default hostname.
+# Uncomment the line below and change it, if you'd like.
+# matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
+
+# Uncomment to enable the ntfy web app (disabled by default)
+# ntfy_web_root: app  # defaults to "disable"
+
+# Uncomment and change to inject additional configuration options.
+# ntfy_configuration_extension_yaml: |
+#   log_level: DEBUG
 ```
 
-For a more complete list of variables that you could override, see `roles/custom/matrix-ntfy/defaults/main.yml`.
+For a more complete list of variables that you could override, see the [`defaults/main.yml` file](https://gitlab.com/etke.cc/roles/ntfy/-/blob/main/defaults/main.yml) of the ntfy Ansible role.
 
-For a complete list of ntfy config options that you could put in `matrix_ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
+For a complete list of ntfy config options that you could put in `ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
 
 
 ## Installing
@@ -78,6 +84,12 @@ If the matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choos
 
 If the matrix app doesn't seem to pick it up, try restarting it and try the Troubleshooting section below.
 
+### Web App
+
+ntfy also has a web app to subscribe to and push to topics from the browser. This may be helpful to further troubleshoot UnifiedPush problems or to use ntfy for other purposes. The web app only runs in the browser locally (after downloading the JavaScript).
+
+The web app is disabled in this playbook by default as the expectation is that most users won't use it. You can either use the [official hosted one](https://ntfy.sh/app) (it supports using other public reachable ntfy instances) or host it yourself by setting `ntfy_web_root: "app"` and re-running Ansible.
+
 
 ## Troubleshooting
 

docs/configuring-playbook-own-webserver.md

@@ -1,200 +1,49 @@
-# Using your own webserver, instead of this playbook's nginx proxy (optional, advanced)
+# Using your own webserver, instead of this playbook's Traefik reverse-proxy (optional, advanced)
+
+**Note**: the playbook is [in the process of moving to Traefik](../CHANGELOG.md#reverse-proxy-configuration-changes-and-initial-traefik-support). The **documentation below may be incomplete or misleading**.
 
 By default, this playbook installs its own nginx webserver (called `matrix-nginx-proxy`, in a Docker container) which listens on ports 80 and 443.
 If that's alright, you can skip this.
 
-If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
-and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
+Soon, this default will change and the playbook will install its own [Traefik](https://traefik.io/) reverse-proxy instead.
 
-You should note, however, that the playbook's services work best when you keep using the integrated `matrix-nginx-proxy` webserver.
-For example, disabling `matrix-nginx-proxy` when running a [Synapse worker setup for load-balancing](configuring-playbook-synapse.md#load-balancing-with-workers) (a more advanced, non-default configuration) is likely to cause various troubles (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090)). If you need a such more scalable setup, disabling `matrix-nginx-proxy` will be a bad idea. If yours will be a simple (default, non-worker-load-balancing) deployment, disabling `matrix-nginx-proxy` may be fine.
+## Traefik
 
-There are **2 ways you can go about it**, if you'd like to use your own webserver:
+[Traefik](https://traefik.io/) will be the default reverse-proxy for the playbook in the near future.
 
-- [Method 1: Disabling the integrated nginx reverse-proxy webserver](#method-1-disabling-the-integrated-nginx-reverse-proxy-webserver)
+There are 2 ways to use Traefik with this playbook, as described below.
 
-- [Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy](#method-2-fronting-the-integrated-nginx-reverse-proxy-webserver-with-another-reverse-proxy)
+### Traefik managed by the playbook
 
-
-## Method 1: Disabling the integrated nginx reverse-proxy webserver
-
-This method is about completely disabling the integrated nginx reverse-proxy webserver and replicating its behavior using another webserver.
-For an alternative, make sure to check Method #2 as well.
-
-### Preparation
-
-No matter which external webserver you decide to go with, you'll need to:
-
-1) Make sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group. When using an external nginx webserver, this allows it to read configuration files from `/matrix/nginx-proxy/conf.d`. When using another server, it would make other files, such as `/matrix/static-files/.well-known`, accessible to it.
-
-2) Edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`)
-   - to disable the integrated nginx server:
-
-        ```yaml
-        matrix_nginx_proxy_enabled: false
-        ```
-    - if using an external server on another host, add the `<service>_http_host_bind_port` or `<service>_http_bind_port` variables for the services that will be exposed by the external server on the other host. The actual name of the variable is listed in the `roles/<service>/defaults/vars.yml` file for each service. Most variables follow the `<service>_http_host_bind_port` format.
-
-      These variables will make Docker expose the ports on all network interfaces instead of localhost only.
-      [Keep in mind that there are some security concerns if you simply proxy everything.](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints)
-
-      Here are the variables required for the default configuration (Synapse and Element)
-       ```
-		matrix_synapse_reverse_proxy_companion_container_client_api_host_bind_port: '0.0.0.0:8008'
-		matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port: '0.0.0.0:8048'
-        matrix_client_element_container_http_host_bind_port: "0.0.0.0:8765"
-       ```
-
-3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable SSL certificate retrieval:
+To switch to Traefik now, use configuration like this:
 
 ```yaml
-matrix_ssl_retrieval_method: none
+matrix_playbook_reverse_proxy_type: playbook-managed-traefik
+
+devture_traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
 ```
 
-**Note**: During [installation](installing.md), unless you've disabled SSL certificate management (`matrix_ssl_retrieval_method: none`), the playbook would need 80 to be available, in order to retrieve SSL certificates. **Please manually stop your other webserver while installing**. You can start it back up afterwards.
+This will install Traefik in the place of `matrix-nginx-proxy`. Traefik will manage SSL certificates for all services seamlessly.
 
-### Using your own external nginx webserver
+**Note**: during the transition period, `matrix-nginx-proxy` will still be installed in local-only mode. Do not be alarmed to see `matrix-nginx-proxy` running even when you've chosen Traefik as your reverse-proxy. In the future, we'll be able to run without nginx, but we're not there yet.
 
-Once you've followed the [Preparation](#preparation) guide above, it's time to set up your external nginx server.
-
-Even with `matrix_nginx_proxy_enabled: false`, the playbook still generates some helpful files for you in `/matrix/nginx-proxy/conf.d`.
-Those configuration files are adapted for use with an external web server (one not running in the container network).
-
-You can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your own `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`
-
-Note that if your nginx version is old, it might not like our default choice of SSL protocols (particularly the fact that the brand new `TLSv1.3` protocol is enabled). You can override the protocol list by redefining the `matrix_nginx_proxy_ssl_protocols` variable. Example:
+### Traefik managed by you
 
 ```yaml
-# Custom protocol list (removing `TLSv1.3`) to suit your nginx version.
-matrix_nginx_proxy_ssl_protocols: "TLSv1.2"
+matrix_playbook_reverse_proxy_type: other-traefik-container
+
+matrix_playbook_reverse_proxyable_services_additional_network: your-traefik-network
+
+devture_traefik_certs_dumper_ssl_dir_path: "/path/to/your/traefiks/acme.json/directory"
 ```
 
-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.
+In this mode all roles will still have Traefik labels attached. You will, however, need to configure your Traefik instance and its entrypoints.
 
-### Using your own external Apache webserver
+By default, the playbook congiures services use a `web-secure` (443) and `matrix-federation` (8448) entrypoints, as well as a `default` certificate resolver.
 
-Once you've followed the [Preparation](#preparation) guide above, you can take a look at the [examples/apache](../examples/apache) directory for a sample configuration.
+You need to configure 3 entrypoints for your Traefik server: `web` (TCP port `80`), `web-secure` (TCP port `443`) and `matrix-federation` (TCP port `8448`).
 
-### Using your own external caddy webserver
-
-After following  the [Preparation](#preparation) guide above, you can take a look at the [examples/caddy](../examples/caddy) directory and [examples/caddy2](../examples/caddy2) directory for a sample configuration for Caddy v1 and v2, respectively.
-
-### Using your own HAproxy reverse proxy
-After following  the [Preparation](#preparation) guide above, you can take a look at the [examples/haproxy](../examples/haproxy) directory for a sample configuration. In this case HAproxy is used as a reverse proxy and a simple Nginx container is used to serve statically `.well-known` files.
-
-### Using another external webserver
-
-Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/).
-
-
-## Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy
-
-This method is about leaving the integrated nginx reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
-
-If you wish to use another webserver, the integrated nginx reverse-proxy webserver usually gets in the way because it attempts to fetch SSL certificates and binds to ports 80, 443 and 8448 (if Matrix Federation is enabled).
-
-You can disable such behavior and make the integrated nginx reverse-proxy webserver only serve traffic locally (or over a local network).
-
-You would need some configuration like this:
-
-```yaml
-# Do not retrieve SSL certificates. This shall be managed by another webserver or other means.
-matrix_ssl_retrieval_method: none
-
-# Do not try to serve HTTPS, since we have no SSL certificates.
-# Disabling this also means services will be served on the HTTP port
-# (`matrix_nginx_proxy_container_http_host_bind_port`).
-matrix_nginx_proxy_https_enabled: false
-
-# Do not listen for HTTP on port 80 globally (default), listen on the loopback interface.
-# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
-matrix_nginx_proxy_container_http_host_bind_port: '127.0.0.1:81'
-
-# Likewise, expose the Matrix Federation port on the loopback interface.
-# Since `matrix_nginx_proxy_https_enabled` is set to `false`, this federation port will serve HTTP traffic.
-# If you'd like, you can make it use the local network as well and reverse-proxy from another local machine.
-#
-# You'd most likely need to expose it publicly on port 8448 (8449 was chosen for the local port to prevent overlap).
-matrix_nginx_proxy_container_federation_host_bind_port: '127.0.0.1:8449'
-
-# Coturn relies on SSL certificates that have already been obtained.
-# Since we don't obtain any certificates (`matrix_ssl_retrieval_method: none` above), it won't work by default.
-# An alternative is to tweak some of: `matrix_coturn_tls_enabled`, `matrix_coturn_tls_cert_path` and `matrix_coturn_tls_key_path`.
-matrix_coturn_enabled: false
-
-# Trust the reverse proxy to send the correct `X-Forwarded-Proto` header as it is handling the SSL connection.
-matrix_nginx_proxy_trust_forwarded_proto: true
-
-# Trust and use the other reverse proxy's `X-Forwarded-For` header.
-matrix_nginx_proxy_x_forwarded_for: '$proxy_add_x_forwarded_for'
-```
-
-With this, nginx would still be in use, but it would not bother with anything SSL related or with taking up public ports.
-
-All services would be served locally on `127.0.0.1:81` and `127.0.0.1:8449` (as per the example configuration above).
-
-You can then set up another reverse-proxy server on ports 80/443/8448 for all of the expected domains and make traffic go to these local ports.
-The expected domains vary depending on the services you have enabled (`matrix.DOMAIN` for sure; `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN` are optional).
-
-### Sample configuration for running behind Traefik 2.0
-
-Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.
-
-```yaml
-# Disable generation and retrieval of SSL certs
-matrix_ssl_retrieval_method: none
-
-# Configure Nginx to only use plain HTTP
-matrix_nginx_proxy_https_enabled: false
-
-# Don't bind any HTTP or federation port to the host
-# (Traefik will proxy directly into the containers)
-matrix_nginx_proxy_container_http_host_bind_port: ''
-matrix_nginx_proxy_container_federation_host_bind_port: ''
-
-# Trust the reverse proxy to send the correct `X-Forwarded-Proto` header as it is handling the SSL connection.
-matrix_nginx_proxy_trust_forwarded_proto: true
-
-# Trust and use the other reverse proxy's `X-Forwarded-For` header.
-matrix_nginx_proxy_x_forwarded_for: '$proxy_add_x_forwarded_for'
-
-# Disable Coturn because it needs SSL certs
-# (Clients can, though exposing IP address, use Matrix.org TURN)
-matrix_coturn_enabled: false
-
-# All containers need to be on the same Docker network as Traefik
-# (This network should already exist and Traefik should be using this network)
-matrix_docker_network: 'traefik'
-
-matrix_nginx_proxy_container_extra_arguments:
-  # May be unnecessary depending on Traefik config, but can't hurt
-  - '--label "traefik.enable=true"'
-
-  # The Nginx proxy container will receive traffic from these subdomains
-  - '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`{{ matrix_server_fqn_matrix }}`,`{{ matrix_server_fqn_element }}`,`{{ matrix_server_fqn_dimension }}`,`{{ matrix_server_fqn_jitsi }}`)"'
-  # (The 'web-secure' entrypoint must bind to port 443 in Traefik config)
-  - '--label "traefik.http.routers.matrix-nginx-proxy.entrypoints=web-secure"'
-  # (The 'default' certificate resolver must be defined in Traefik config)
-  - '--label "traefik.http.routers.matrix-nginx-proxy.tls.certResolver=default"'
-  # Traefik requires that we declare which service this router is using
-  - '--label "traefik.http.routers.matrix-nginx-proxy.service=matrix-nginx-proxy"'
-  # The Nginx proxy container uses port 8080 internally
-  - '--label "traefik.http.services.matrix-nginx-proxy.loadbalancer.server.port=8080"'
-
-  # Federation
-  - '--label "traefik.http.routers.matrix-nginx-proxy-federation.rule=Host(`{{ matrix_server_fqn_matrix }}`)"'
-  # (The 'federation' entrypoint must bind to port 8448 in Traefik config)
-  - '--label "traefik.http.routers.matrix-nginx-proxy-federation.entrypoints=federation"'
-  # (The 'default' certificate resolver must be defined in Traefik config)
-  - '--label "traefik.http.routers.matrix-nginx-proxy-federation.tls.certResolver=default"'
-  # Traefik requires that we declare which service this router is using
-  - '--label "traefik.http.routers.matrix-nginx-proxy-federation.service=matrix-nginx-proxy-federation"'
-  # The Nginx proxy container uses port `matrix_nginx_proxy_proxy_matrix_federation_port (8448) internally
-  - '--label "traefik.http.services.matrix-nginx-proxy-federation.loadbalancer.server.port={{ matrix_nginx_proxy_proxy_matrix_federation_port }}"'
-  - '--label "traefik.http.services.matrix-nginx-proxy-federation.loadbalancer.server.scheme={{ "https" if matrix_nginx_proxy_https_enabled else "http" }}"'
-```
-
-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.
+Below is some configuration for running Traefik yourself, although we recommend using [Traefik managed by the playbook](#traefik-managed-by-the-playbook).
 
 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:
 
@@ -224,7 +73,7 @@ version: "3.3"
 services:
 
   traefik:
-    image: "traefik:v2.3"
+    image: "docker.io/traefik:v2.9.6"
     restart: always
     container_name: "traefik"
     networks:
@@ -250,3 +99,128 @@ networks:
   traefik:
     external: true
 ```
+
+## Another webserver
+
+If you don't wish to use Traefik or `matrix-nginx-proxy`, you can also use your own webserver.
+
+Doing this is possible, but requires manual work.
+
+There are 2 ways to go about it:
+
+- (recommended) [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) - using a playbook-managed reverse-proxy (either `matrix-nginx-proxy` or Traefik), disabling SSL termination for it, exposing this reverse-proxy on a few local ports (e.g. `127.0.0.1:81`, etc.) and forwarding traffic from your own webserver to those few ports
+
+- (difficult) [Using no reverse-proxy on the Matrix side at all](#using-no-reverse-proxy-on-the-matrix-side-at-all) disabling all playbook-managed reverse-proxies (no `matrix-nginx-proxy`, no Traefik)
+
+
+### Fronting the integrated reverse-proxy webserver with another reverse-proxy
+
+This method is about leaving the integrated reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
+
+If you wish to use another webserver, the integrated reverse-proxy webserver usually gets in the way because it attempts to fetch SSL certificates and binds to ports 80, 443 and 8448 (if Matrix Federation is enabled).
+
+You can disable such behavior and make the integrated reverse-proxy webserver only serve traffic locally (or over a local network).
+
+This is the recommended way for using another reverse-proxy, because the integrated one would act as a black box and wire all Matrix services correctly. You would only need to reverse-proxy a few individual domains and ports over to it.
+
+To front Traefik with another reverse-proxy, you would need some configuration like this:
+
+```yaml
+matrix_playbook_reverse_proxy_type: playbook-managed-traefik
+
+# Ensure that public urls use https
+matrix_playbook_ssl_enabled: true
+
+# Disable the web-secure (port 443) endpoint, which also disables SSL certificate retrieval
+devture_traefik_config_entrypoint_web_secure_enabled: false
+
+# If your reverse-proxy runs on another machine, consider using `0.0.0.0:81`, just `81` or `SOME_IP_ADDRESS_OF_THIS_MACHINE:81`
+devture_traefik_container_web_host_bind_port: '127.0.0.1:81'
+
+# We bind to `127.0.0.1` by default (see above), so trusting `X-Forwarded-*` headers from
+# a reverse-proxy running on the local machine is safe enough.
+devture_traefik_config_entrypoint_web_forwardedHeaders_insecure: true
+
+# Or, if you're publishing the port (`devture_traefik_container_web_host_bind_port` above) to a public network interfaces:
+# - remove the `devture_traefik_config_entrypoint_web_forwardedHeaders_insecure` variable definition above
+# - uncomment and adjust the line below
+# devture_traefik_config_entrypoint_web_forwardedHeaders_trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
+
+# Likewise (to `devture_traefik_container_web_host_bind_port` above),
+# if your reverse-proxy runs on another machine, consider changing the `host_bind_port` setting below.
+devture_traefik_additional_entrypoints_auto:
+  - name: matrix-federation
+    port: 8449
+    host_bind_port: '127.0.0.1:8449'
+    config: {}
+    # If your reverse-proxy runs on another machine, remove the config above and use this config instead:
+    # config:
+    #   forwardedHeaders:
+    #     insecure: true
+    #     # trustedIPs: ['IP-ADDRESS-OF-YOUR-REVERSE-PROXY']
+```
+
+For an example where the playbook's Traefik reverse-proxy is fronted by another reverse-proxy running on the same server, see [Nginx reverse-proxy fronting the playbook's Traefik](../examples/nginx/README.md) or [Caddy reverse-proxy fronting the playbook's Traefik](../examples/caddy2/README.md).
+
+
+### Using no reverse-proxy on the Matrix side at all
+
+Instead of [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), you can also go another way -- completely disabling the playbook-managed reverse-proxy. You would then need to reverse-proxy from your own webserver directly to Matrix services.
+
+This is more difficult, as you would need to handle the configuration for each service manually. Enabling additional services would come with extra manual work you need to do.
+
+If your webserver is on the same machine, sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group. When using an external nginx webserver, this allows it to read configuration files from `/matrix/nginx-proxy/conf.d`. When using another server, it would make other files, such as `/matrix/static-files/.well-known`, accessible to it.
+
+#### Using your own nginx reverse-proxy running on the same machine
+
+**WARNING**: this type of setup is not maintained and will be removed in the future. We recommend that you go for [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instead.
+
+If you'll be using `nginx` running on the same machine (not in a container), you can make the playbook help you generate configuration for `nginx` with this configuration:
+
+```yaml
+matrix_playbook_reverse_proxy_type: other-nginx-non-container
+
+# If you want https configured in /matrix/nginx-proxy/conf.d/
+matrix_nginx_proxy_https_enabled: true
+
+# If you will manage SSL certificates yourself, uncomment the line below
+# matrix_ssl_retrieval_method: none
+
+# If you're using an old nginx version, consider using a custom protocol list
+# (removing `TLSv1.3` that is enabled by default) to suit your nginx version.
+# matrix_nginx_proxy_ssl_protocols: "TLSv1.2"
+```
+
+You can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your own `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`
+
+#### Using your own reverse-proxy running on the same machine or elsewhere
+
+**WARNING**: this is difficult to set up, likely not very well supported and will be removed in the future. We recommend that you go for [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instead.
+
+To reverse-proxy manually for each service, use configuration like this:
+
+```yaml
+# If your reverse-proxy runs on the same machine:
+matrix_playbook_reverse_proxy_type: other-on-same-host
+
+# Or, if it runs on another machine:
+# matrix_playbook_reverse_proxy_type: other-on-another-host
+
+# Or, optionally customize the network interface prefix (note the trailing `:` character).
+# For other-on-same-host, the interface defaults to `127.0.0.1:`.
+# For other-on-another-host, the interface defaults to `0.0.0.0:`.
+# matrix_playbook_service_host_bind_interface_prefix: '192.168.30.4:'
+```
+
+With this configuration, each service will be exposed on a custom port. Example:
+
+- Synapse will be exposed on port `8008`
+- [Grafana](configuring-playbook-prometheus-grafana.md) will be exposed on port `3000`
+- [synapse-admin](configuring-playbook-synapse-admin.md) will be exposed on port `8766`
+
+You can capture traffic for these services and forward it to their port.
+Some of these services are configured with certain default expecations with regard to hostname, path, etc., so it's not completely arbitrary where you can host them (unless you change the defaults).
+
+For each new playbook service that you enable, you'll need special handling.
+
+The [`examples/`](../examples/) directory contains examples for various servers: Caddy, Apache, HAproxy, Nginx, etc.

docs/configuring-playbook-postgres-backup.md

@@ -1,6 +1,6 @@
 # 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.
+The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you via the [com.devture.ansible.role.postgres_backup](https://github.com/devture/com.devture.ansible.role.postgres_backup) Ansible role.
 
 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.
 
@@ -10,7 +10,7 @@ For a more complete backup solution (one that includes not only Postgres, but al
 Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:
 
 ```yaml
-matrix_postgres_backup_enabled: true
+devture_postgres_backup_enabled: true
 ```
 
 Refer to the table below for additional configuration variables and their default values.
@@ -18,12 +18,13 @@ Refer to the table below for additional configuration variables and their defaul
 
 | 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|
+|`devture_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|
+|`devture_postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
+|`devture_postgres_backup_keep_days`|`7`|Number of daily backups to keep|
+|`devture_postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
+|`devture_postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
+|`devture_postgres_backup_base_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Base path for postgres-backup. Also see `devture_postgres_backup_data_path` |
+|`devture_postgres_backup_data_path` | `"{{ devture_postgres_backup_base_path }}/data"` | Storage path for postgres-backup database backups |
 
 
 ## Installing

docs/configuring-playbook-prometheus-grafana.md

@@ -7,24 +7,27 @@ You can enable this with the following settings in your configuration file (`inv
 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
+prometheus_enabled: true
 
 # You can remove this, if unnecessary.
-matrix_prometheus_node_exporter_enabled: true
+prometheus_node_exporter_enabled: true
 
 # You can remove this, if unnecessary.
-matrix_prometheus_postgres_exporter_enabled: true
+prometheus_postgres_exporter_enabled: true
 
-matrix_grafana_enabled: true
+# You can remove this, if unnecessary.
+matrix_prometheus_nginxlog_exporter_enabled: true
 
-matrix_grafana_anonymous_access: false
+grafana_enabled: true
+
+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"
+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"
+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>`.
@@ -36,24 +39,25 @@ The retention policy of Prometheus metrics is [15 days by default](https://prome
 
 Name | Description
 -----|----------
-`matrix_prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
-`matrix_prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
-`matrix_prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
-`matrix_grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
-`matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
-`matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
+`prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
+`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
+`prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
+`matrix_prometheus_nginxlog_exporter_enabled`|[NGINX Log Exporter](configuring-playbook-prometheus-nginxlog.md) is an addon of sorts to expose NGINX logs to Prometheus.
+`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
+`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.
+`grafana_default_admin_user`<br>`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.
+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 `prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
 
 
 ## Collecting metrics to an external Prometheus server
 
-**If the integrated Prometheus server is enabled** (`matrix_prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".
+**If the integrated Prometheus server is enabled** (`prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".
 
 When you'd like **to collect metrics from an external Prometheus server**, you need to expose service metrics outside of the container network.
 
@@ -70,14 +74,16 @@ Name | Description
 `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_raw_content`|Set this to the Basic Authentication credentials (raw `htpasswd` file content) used to protect `/metrics/*`. This htpasswd-file needs to be generated with the `htpasswd` tool and can include multiple username/password pairs. If you only need one credential, use `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_username` and `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password` instead.
 `matrix_synapse_metrics_enabled`|Set this to `true` to make Synapse expose metrics (locally, on the container network)
 `matrix_synapse_metrics_proxying_enabled`|Set this to `true` to expose Synapse's metrics on `https://matrix.DOMAIN/metrics/synapse/main-process` and `https://matrix.DOMAIN/metrics/synapse/worker/TYPE-ID` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`). Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`).
-`matrix_prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network)
-`matrix_prometheus_node_exporter_metrics_proxying_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
-`matrix_prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
-`matrix_prometheus_postgres_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
+`prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network)
+`matrix_prometheus_services_proxy_connect_prometheus_node_exporter_metrics_proxying_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
+`prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
+`matrix_prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [NGINX Log exporter](configuring-playbook-prometheus-nginxlog.md) (locally, on the container network)
+`matrix_prometheus_services_proxy_connect_prometheus_postgres_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
 `matrix_bridge_hookshot_metrics_enabled`|Set this to `true` to make [Hookshot](configuring-playbook-bridge-hookshot.md) expose metrics (locally, on the container network)
 `matrix_bridge_hookshot_metrics_proxying_enabled`|Set this to `true` to expose the [Hookshot](configuring-playbook-bridge-hookshot.md) metrics on `https://matrix.DOMAIN/metrics/hookshot` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
 `matrix_SERVICE_metrics_proxying_enabled`|Various other services/roles may provide similar `_metrics_enabled` and `_metrics_proxying_enabled` variables for exposing their metrics. Refer to each role for details. Only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`
 `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks`|Add nginx `location` blocks to this list if you'd like to expose additional exporters manually (see below)
+`matrix_media_repo_metrics_enabled`|Set this to `true` to make media-repo expose metrics (locally, on the container network)
 
 Example for how to make use of `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks` for exposing additional metrics locations:
 ```nginx

docs/configuring-playbook-prometheus-nginxlog.md

@@ -0,0 +1,59 @@
+# Enabling metrics and graphs for NginX logs (optional)
+
+It can be useful to have some (visual) insight into NignX logs.
+
+This adds [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) to your matrix deployment.
+It will provide a prometheus 'metrics' endpoint exposing data from both the `matrix-nginx-proxy` and `matrix-synapse-reverse-proxy-companion` logs and automatically aggregates the data with prometheus.
+Optionally it visualizes the data, if [`matrix-grafana`](configuring-playbook-prometheus-grafana.md) is enabled, by means of a dedicated Grafana dashboard named `NGINX PROXY`
+
+You can enable this role by adding the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+
+```yaml
+matrix_prometheus_nginxlog_exporter_enabled: true
+
+# required depency
+prometheus_enabled: true
+
+# optional for visualization
+grafana_enabled: true
+```
+
+x | Prerequisites | Variable | Description
+|:--:|:--:|:--:|:--|
+**REQUIRED** | `matrix-prometheus`| `prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
+_Optional_ | [`matrix-grafana`](configuring-playbook-prometheus-grafana.md) | [`grafana_enabled`](configuring-playbook-prometheus-grafana.md)|[Grafana](https://grafana.com) is the visual component. It shows (on the `stats.<your-domain>` subdomain) graphs that we're interested in. When enabled the `NGINX PROXY` dashboard is automatically added.
+
+## Docker Image Compatibility
+
+At the moment of writing only images for `amd64` and `arm64` architectures are available
+
+The playbook currently does not support building an image.
+You can however use a custom-build image by setting
+```yaml
+matrix_prometheus_nginxlog_exporter_docker_image_arch_check_enabled: false
+matrix_prometheus_nginxlog_exporter_docker_image: path/to/docker/image:tag
+```
+
+## Security and privacy
+
+Metrics and resulting graphs can contain a lot of information. NginX logs contain information like IP address, URLs, UserAgents and more. This information can reveal usage patterns and could be considered Personally Identifiable Information (PII). Think about this before enabling (anonymous) access.
+Please make sure you change the default Grafana password.
+
+## Save metrics on an external Prometheus server
+
+The playbook will automatically integrate the metrics into the Prometheus server provided with this playbook. You can choose to save data on an external Prometheus instance.
+
+The metrics of this role will be exposed on `https://matrix.DOMAIN/metrics/nginxlog` when setting
+```yaml
+matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled: true
+
+# required dependency
+matrix_nginx_proxy_proxy_matrix_metrics_enabled: true
+```
+The playbook can provide a single endpoint (`https://matrix.DOMAIN/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/nginxlog`, etc). To enable this `/metrics/*` feature, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled`.
+
+The following variables may be of interest:
+
+Name | Description
+-----|----------
+`matrix_nginx_proxy_proxy_matrix_metrics_enabled`|Set this to `true` to enable metrics exposure for various services on `https://matrix.DOMAIN/metrics/*`. Refer to the individual `matrix_SERVICE_metrics_proxying_enabled` variables below for exposing metrics for each individual service.

docs/configuring-playbook-prometheus-postgres.md

@@ -6,17 +6,17 @@ You can enable this with the following settings in your configuration file (`inv
 
 
 ```yaml
-matrix_prometheus_postgres_exporter_enabled: true
+prometheus_postgres_exporter_enabled: true
 ```
 
 ## What does it do?
 
 Name | Description
 -----|----------
-`matrix_prometheus_postgres_exporter_enabled`|Enable the postgres prometheus exporter. This sets up the docker container, connects it to the database and adds a 'job' to the prometheus config which tells prometheus about this new exporter. The default is 'false'
-`matrix_prometheus_postgres_exporter_database_username`| The 'username' for the user that the exporter uses to connect to the database. The default is 'matrix_prometheus_postgres_exporter'
-`matrix_prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
-`matrix_prometheus_postgres_exporter_metrics_proxying_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
+`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'
+`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'
+`prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
+`matrix_prometheus_services_proxy_connect_prometheus_postgres_exporter_metrics_proxying_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
 
 
 ## More information

docs/configuring-playbook-rageshake.md

@@ -0,0 +1,65 @@
+# Setting up Rageshake (optional)
+
+The playbook can install and configure the [rageshake](https://github.com/matrix-org/rageshake) bug report server for you.
+
+This is useful if you're developing your own applications and would like to collect bug reports for them.
+
+
+## Decide on a domain and path
+
+By default, Rageshake is configured to use its own dedicated domain (`rageshake.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+You can override the domain and path like this:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
+# so we won't need to add additional DNS records for Rageshake.
+matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /rageshake subpath
+matrix_rageshake_path_prefix: /rageshake
+```
+
+**NOTE**: When using `matrix-nginx-proxy` instead of Traefik, you won't be able to override the path prefix. You can only override the domain, but that needs to happen using another variable: `matrix_server_fqn_rageshake` (e.g. `matrix_server_fqn_rageshake: "some-domain.{{ matrix_domain }}"`).
+
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Rageshake domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+
+## Enabling the Rageshake service
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+matrix_rageshake_enabled: true
+```
+
+Rageshake has various options which don't have dedicated Ansible variables. You can see the full list of options in the [`rageshake.sample.yaml` file](https://github.com/matrix-org/rageshake/blob/master/rageshake.sample.yaml).
+
+To set these, you can make use of the  `matrix_rageshake_configuration_extension_yaml` variable like this:
+
+```yaml
+matrix_rageshake_configuration_extension_yaml: |
+  github_token: secrettoken
+
+  github_project_mappings:
+     my-app: octocat/HelloWorld
+```
+
+
+## Installing
+
+After configuring the playbook, run the [installation](installing.md) command again:
+
+```
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+
+## Usage
+
+Refer to the [rageshake documentation](https://github.com/matrix-org/rageshake) for available APIs, etc.

docs/configuring-playbook-s3.md

@@ -5,11 +5,13 @@ If that's alright, you can skip this.
 
 As an alternative to storing media files on the local filesystem, you can store them on [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object store.
 
+You can do this either by sticking to Synapse's media repository and making that use S3 (read below for this method), or by switching to an external media storage implementation like [matrix-media-repo](configuring-playbook-matrix-media-repo.md).
+
 First, [choose an Object Storage provider](#choosing-an-object-storage-provider).
 
 Then, [create the S3 bucket](#bucket-creation-and-security-configuration).
 
-Finally, [set up S3 storage for Synapse](#setting-up) (with [Goofys](configuring-playbook-s3-goofys.md) or [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md)).
+Finally, [set up S3 storage for Synapse](#setting-up) (with [Goofys](configuring-playbook-s3-goofys.md), [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md), or use s3 datastore with the [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html)).
 
 
 ## Choosing an Object Storage provider
@@ -105,3 +107,4 @@ To set up Synapse to store files in S3, follow the instructions for the method o
 
 - using [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) (recommended)
 - using [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md)
+- using [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html)

docs/configuring-playbook-sliding-sync-proxy.md

@@ -0,0 +1,63 @@
+# Setting up Sliding Sync Proxy (optional)
+
+The playbook can install and configure [sliding-sync](https://github.com/matrix-org/sliding-sync) proxy for you.
+
+Sliding Sync is an implementation of [MSC3575](https://github.com/matrix-org/matrix-spec-proposals/blob/kegan/sync-v3/proposals/3575-sync.md) and a prerequisite for running the new (**still beta**) Element X clients ([Element X iOS](https://github.com/vector-im/element-x-ios) and [Element X Android](https://github.com/vector-im/element-x-android)).
+
+See the project's [documentation](https://github.com/matrix-org/sliding-sync) to learn more.
+
+Element X iOS is [available on TestFlight](https://testflight.apple.com/join/uZbeZCOi).
+
+Element X Android is [available on the Github Releases page](https://github.com/vector-im/element-x-android/releases).
+
+**NOTE**: The Sliding Sync proxy **only works with the Traefik reverse-proxy**. If you have an old server installation (from the time `matrix-nginx-proxy` was our default reverse-proxy - `matrix_playbook_reverse_proxy_type: playbook-managed-nginx`), you won't be able to use Sliding Sync.
+
+**NOTE**: The sliding-sync proxy is **not required** when using the **Conduit homeserver**. Starting from version `0.6.0` Conduit has native support for some sliding sync features. If there are issues with the native implementation, you might have a better experience when enabling the sliding-sync proxy anyway.
+
+## Decide on a domain and path
+
+By default, the Sliding Sync proxy is configured to be served on the Matrix domain (`matrix.DOMAIN`, controlled by `matrix_server_fqn_matrix`), under the `/sliding-sync` path.
+
+This makes it easy to set it up, **without** having to [adjust your DNS records](#adjusting-dns-records).
+
+If you'd like to run the Sliding Sync proxy on another hostname or path, use the `matrix_sliding_sync_hostname` and `matrix_sliding_sync_path_prefix` variables.
+
+
+## Adjusting DNS records
+
+If you've changed the default hostame, **you may need to adjust your DNS** records.
+
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
+```yaml
+matrix_sliding_sync_enabled: true
+```
+
+
+## Installing
+
+After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again: `just install-all`.
+
+### External databases
+
+Please note that, if your setup utilizes an external database, you must also establish configuration for the sliding sync proxy. Alter the defaults below to suit your configuration:
+
+```yaml
+matrix_sliding_sync_database_username: 'matrix_sliding_sync'
+matrix_sliding_sync_database_password: ''
+matrix_sliding_sync_database_hostname: ''
+matrix_sliding_sync_database_port: 5432
+matrix_sliding_sync_database_name: 'matrix_sliding_sync'
+```
+
+## Usage
+
+You **don't need to do anything special** to make use of the Sliding Sync Proxy.
+Simply open your client which supports Sliding Sync (like Element X) and log in.
+
+When the Sliding Sync proxy is [installed](#installing), your `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc3575.proxy` section and `url` property are added there and made to point to your Sliding Sync proxy's base URL (e.g. `https://matrix.DOMAIN/sliding-sync`).
+
+This allows clients which support Sliding Sync to detect the Sliding Sync Proxy's URL and make use of it.

docs/configuring-playbook-ssl-certificates.md

@@ -1,112 +1,100 @@
 # Adjusting SSL certificate retrieval (optional, advanced)
 
-By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (`matrix.<your-domain>` and possibly `element.<your-domain>`)
+By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (e.g. `matrix.<your-domain>` and others)
 
-Those certificates are used when configuring the nginx reverse proxy installed by this playbook.
-They can also be used for configuring [your own webserver](configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook.
+This guide is about using the integrated Traefik server and doesn't apply if you're using [your own webserver](configuring-playbook-own-webserver.md).
 
-If you need to retrieve certificates for other domains (e.g. your base domain) or more control over certificate retrieval, read below.
 
-Things discussed in this document:
+## Using staging Let's Encrypt certificates instead of real ones
 
-- [Using self-signed SSL certificates](#using-self-signed-ssl-certificates), if you can't use Let's Encrypt or just need a test setup
+For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
 
-- [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
+You can do this with the following configuration:
 
-- [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
+```yaml
+devture_traefik_config_certificatesResolvers_acme_use_staging: true
+```
 
-- [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
+
+## Disabling SSL termination
+
+For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://`.
+
+You can do this with the following configuration:
+
+```yaml
+devture_traefik_config_entrypoint_web_secure_enabled: false
+```
 
 
 ## Using self-signed SSL certificates
 
-For private deployments (not publicly accessible from the internet), you may not be able to use Let's Encrypt certificates.
+If you'd like to use your own SSL certificates, instead of the default (SSL certificates obtained automatically via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) from [Let's Encrypt](https://letsencrypt.org/)):
 
-If self-signed certificates are alright with you, you can ask the playbook to generate such for you with the following configuration:
-
-```yaml
-matrix_ssl_retrieval_method: self-signed
-```
-
-If you get a `Cannot reach homeserver` error in Element, you will have to visit `https://matrix.<your-domain>` in your browser and agree to the certificate exception before you can login.
+- generate your self-signed certificate files
+- follow the [Using your own SSL certificates](#using-your-own-ssl-certificates) documentation below
 
 
 ## Using your own SSL certificates
 
-If you'd like to manage SSL certificates by yourself and have the playbook use your certificate files, you can use the following configuration:
+To use your own SSL certificates with Traefik, you need to:
+
+- disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support
+- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
+- register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/)
+- put the SSL files on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
 
 ```yaml
-matrix_ssl_retrieval_method: manually-managed
-```
-
-With such a configuration, the playbook would expect you to drop the SSL certificate files in the directory specified by `matrix_ssl_config_dir_path` (`/matrix/ssl/config` by default) obeying the following hierarchy:
-
-- `<matrix_ssl_config_dir_path>/live/<domain>/fullchain.pem`
-- `<matrix_ssl_config_dir_path>/live/<domain>/privkey.pem`
-- `<matrix_ssl_config_dir_path>/live/<domain>/chain.pem`
-
-where `<domain>` refers to the domains that you need (usually `matrix.<your-domain>` and `element.<your-domain>`).
-
-
-## Not bothering with SSL certificates
-
-If you're [using an external web server](configuring-playbook-own-webserver.md) which is not nginx, or you would otherwise want to manage its certificates without this playbook getting in the way, you can completely disable SSL certificate management with the following configuration:
-
-```yaml
-matrix_ssl_retrieval_method: none
-```
-
-With such a configuration, no certificates will be retrieved at all. You're free to manage them however you want.
-
-
-## Obtaining SSL certificates for additional domains
-
-The playbook tries to be smart about the certificates it will obtain for you.
-
-By default, it obtains certificates for:
-- `matrix.<your-domain>` (`matrix_server_fqn_matrix`)
-- possibly for `element.<your-domain>`, unless you have disabled the [Element client component](configuring-playbook-client-element.md) using `matrix_client_element_enabled: false`
-- possibly for `riot.<your-domain>`, if you have explicitly enabled Riot to Element redirection (for background compatibility) using `matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`
-- possibly for `hydrogen.<your-domain>`, if you have explicitly [set up Hydrogen client](configuring-playbook-client-hydrogen.md).
-- possibly for `cinny.<your-domain>`, if you have explicitly [set up Cinny client](configuring-playbook-client-cinny.md).
-- possibly for `dimension.<your-domain>`, if you have explicitly [set up Dimension](configuring-playbook-dimension.md).
-- possibly for `goneb.<your-domain>`, if you have explicitly [set up Go-NEB bot](configuring-playbook-bot-go-neb.md).
-- possibly for `jitsi.<your-domain>`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md).
-- possibly for `stats.<your-domain>`, if you have explicitly [set up Grafana](configuring-playbook-prometheus-grafana.md).
-- possibly for `sygnal.<your-domain>`, if you have explicitly [set up Sygnal](configuring-playbook-sygnal.md).
-- possibly for `ntfy.<your-domain>`, if you have explicitly [set up ntfy](configuring-playbook-ntfy.md).
-- possibly for your base domain (`<your-domain>`), if you have explicitly configured [Serving the base domain](configuring-playbook-base-domain-serving.md)
-
-If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.
-To do that, simply define your own custom configuration like this:
-
-```yaml
-# In this example, we retrieve 2 extra certificates,
-# one for the base domain (in the `matrix_domain` variable) and one for a hardcoded domain.
-# Adding any other additional domains (hosted on the same machine) is possible.
-matrix_ssl_additional_domains_to_obtain_certificates_for:
-  - '{{ matrix_domain }}'
-  - 'another.domain.example.com'
-```
-
-After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should:
-
-- make sure the web server occupying port 80 is stopped. If you are using matrix-nginx-proxy server (which is the default for this playbook), you need to stop it temporarily by running `systemctl stop matrix-nginx-proxy` on the server.
-
-- re-run the SSL part of the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-ssl,start`
-
-The certificate files would be made available in `/matrix/ssl/config/live/<your-other-domain>/...`.
-
-For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal.
-
-See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-domain.conf`
-Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.
-
-
-## Specify the SSL private key algorithm
-
-If you'd like to [specify the private key type](https://eff-certbot.readthedocs.io/en/stable/using.html#using-ecdsa-keys) used with Let's Encrypt, define your own custom configuration like this:
-
-```yaml
-matrix_ssl_lets_encrypt_key_type: ecdsa
+# Disable ACME / Let's Encrypt support.
+devture_traefik_config_certificatesResolvers_acme_enabled: false
+
+# Disabling ACME support (above) automatically disables the creation of the SSL directory.
+# Force-enable it here, because we'll add our certificate files there.
+devture_traefik_ssl_dir_enabled: true
+
+# Tell Traefik to load our custom configuration file (certificates.yml).
+# The file is created below, in `aux_file_definitions`.
+# The `/config/..` path is an in-container path, not a path on the host (like `/matrix/traefik/config`). Do not change it!
+devture_traefik_configuration_extension_yaml: |
+  providers:
+    file:
+      filename: /config/certificates.yml
+      watch: true
+
+# Use the aux role to create our custom files on the server.
+# If you'd like to do this manually, you remove this `aux_file_definitions` variable.
+aux_file_definitions:
+  # Create the privkey.pem file on the server by
+  # uploading a file from the computer where Ansible is running.
+  - dest: "{{ devture_traefik_ssl_dir_path }}/privkey.pem"
+    src: /path/on/your/Ansible/computer/to/privkey.pem
+	# Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline.
+	# Note the indentation level.
+	# content: |
+	#   FILE CONTENT
+	#   HERE
+
+  # Create the cert.pem file on the server
+  # uploading a file from the computer where Ansible is running.
+  - dest: "{{ devture_traefik_ssl_dir_path }}/cert.pem"
+    src: /path/on/your/Ansible/computer/to/cert.pem
+	# Alternatively, comment out `src` above and uncomment the lines below to provide the certificate content inline.
+	# Note the indentation level.
+	# content: |
+	#   FILE CONTENT
+	#   HERE
+
+  # Create the custom Traefik configuration.
+  # The `/ssl/..` paths below are in-container paths, not paths on the host (/`matrix/traefik/ssl/..`). Do not change them!
+  - dest: "{{ devture_traefik_config_dir_path }}/certificates.yml"
+    content: |
+      tls:
+        certificates:
+          - certFile: /ssl/cert.pem
+            keyFile: /ssl/privkey.pem
+        stores:
+          default:
+            defaultCertificate:
+              certFile: /ssl/cert.pem
+              keyFile: /ssl/privkey.pem
 ```

docs/configuring-playbook-sygnal.md

@@ -11,6 +11,31 @@ See the project's [documentation](https://github.com/matrix-org/sygnal) to learn
 This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves.
 
 
+## Decide on a domain and path
+
+By default, Sygnal is configured to use its own dedicated domain (`sygnal.DOMAIN`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+You can override the domain and path like this:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.DOMAIN`),
+# so we won't need to add additional DNS records for Sygnal.
+matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /sygnal subpath
+matrix_sygnal_path_prefix: /sygnal
+```
+
+**NOTE**: When using `matrix-nginx-proxy` instead of Traefik, you won't be able to override the path prefix. You can only override the domain, but that needs to happen using another variable: `matrix_server_fqn_sygnal` (e.g. `matrix_server_fqn_sygnal: "push.{{ matrix_domain }}"`).
+
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Sygnal domain to the Matrix server.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+
 ## Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
@@ -30,7 +55,7 @@ matrix_sygnal_apps:
     api_key: your_api_key_for_gcm
     # .. more configuration ..
 
-matrix_aux_file_definitions:
+aux_file_definitions:
   - dest: "{{ matrix_sygnal_data_path }}/my_key.p8"
     content: |
       some
@@ -48,16 +73,14 @@ Configuring [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/) is easi
 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/custom/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`.
+- makes use of the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) (and its `aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See [`defaults/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml) of the `aux` role 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 `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:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
@@ -66,6 +89,6 @@ 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.
+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 to your Sygnal URL endpoint (e.g. `https://sygnal.DOMAIN`).
 
 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

@@ -15,7 +15,7 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
 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`).
+**Note**: Synapse Admin requires Synapse's [Admin APIs](https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/index.html) 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
@@ -35,34 +35,6 @@ To use Synapse Admin, you need to have [registered at least one administrator ac
 
 The Homeserver URL to use on Synapse Admin's login page is: `https://matrix.DOMAIN`
 
-### Sample configuration for running behind Traefik 2.0
-
-Below is a sample configuration for using this playbook with a [Traefik](https://traefik.io/) 2.0 reverse proxy.
-
-This an extension to Traefik config sample in [own-webserver-documentation](./configuring-playbook-own-webserver.md).
-
-```yaml
-# Don't bind any HTTP or federation port to the host
-# (Traefik will proxy directly into the containers)
-matrix_synapse_admin_container_http_host_bind_port: ""
-
-matrix_synapse_admin_container_extra_arguments:
-    # May be unnecessary depending on Traefik config, but can't hurt
-    - '--label "traefik.enable=true"'
-
-    # The Synapse Admin container will only receive traffic from this subdomain and path
-    - '--label "traefik.http.routers.matrix-synapse-admin.rule=(Host(`{{ matrix_server_fqn_matrix }}`) && Path(`{{matrix_synapse_admin_public_endpoint}}`))"'
-
-    # (Define your entrypoint)
-    - '--label "traefik.http.routers.matrix-synapse-admin.entrypoints=web-secure"'
-
-    # (The 'default' certificate resolver must be defined in Traefik config)
-    - '--label "traefik.http.routers.matrix-synapse-admin.tls.certResolver=default"'
-
-    # The Synapse Admin container uses port 80 by default
-    - '--label "traefik.http.services.matrix-synapse-admin.loadbalancer.server.port=80"'
-```
-
 ### Sample configuration for running behind Caddy v2
 
 Below is a sample configuration for using this playbook with a [Caddy](https://caddyserver.com/v2) 2.0 reverse proxy (non-default configuration where `matrix-nginx-proxy` is disabled - `matrix_nginx_proxy_enabled: false`).

docs/configuring-playbook-synapse-auto-compressor.md

@@ -0,0 +1,36 @@
+# Setting up synapse_auto_compressor
+
+The playbook can install and configure [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) for you.
+
+It's a CLI tool that automatically compresses Synapse's `state_groups` database table in the background.
+
+See the project's [documentation](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) 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_auto_compressor_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_auto_compressor` will run automatically every day at `00:00:00` (as defined in `matrix_synapse_auto_compressor_calendar` by default).
+
+## Manually start the tool
+
+For testing your setup it can be helpful to not wait until 00:00. If you want to run the tool immediately, log onto the server
+and run `systemctl start matrix-synapse-auto-compressor`. Running this command will not return control to your terminal until the compression run is done, which may take a long time.
+Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

docs/configuring-playbook-synapse-s3-storage-provider.md

@@ -3,8 +3,6 @@
 If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
 you can use the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) media provider module for Synapse.
 
-**`synapse-s3-storage-provider` support is very new and still relatively untested. Using it may cause data loss.**
-
 An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).
 
 
@@ -28,17 +26,27 @@ While you will need some local disk space around, it's only to accommodate usage
 
 ## Installing
 
-After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure Goofys in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
 
 ```yaml
 matrix_synapse_ext_synapse_s3_storage_provider_enabled: true
+
 matrix_synapse_ext_synapse_s3_storage_provider_config_bucket: your-bucket-name
 matrix_synapse_ext_synapse_s3_storage_provider_config_region_name: some-region-name # e.g. eu-central-1
-matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url: https://.. # delete this whole line for Amazon S3
-matrix_synapse_ext_synapse_s3_storage_provider_config_access_key_id: access-key-goes-here
-matrix_synapse_ext_synapse_s3_storage_provider_config_secret_access_key: secret-key-goes-here
+matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url: https://s3.REGION_NAME.amazonaws.com # adjust this
 matrix_synapse_ext_synapse_s3_storage_provider_config_storage_class: STANDARD # or STANDARD_IA, etc.
 
+# Authentication Method 1 - (access key id + secret)
+# This works on all providers (AWS and other compatible systems).
+# Uncomment the variables below to use it.
+# matrix_synapse_ext_synapse_s3_storage_provider_config_access_key_id: access-key-goes-here
+# matrix_synapse_ext_synapse_s3_storage_provider_config_secret_access_key: secret-key-goes-here
+
+# Authentication Method 2 - EC2 instance profile which grants permission to access S3
+# This only works on AWS when your server is hosted on an EC2 instance with the correct instance profile set.
+# Uncomment the variable below to use it.
+# matrix_synapse_ext_synapse_s3_storage_provider_config_ec2_instance_profile: true
+
 # For additional advanced settings, take a look at `roles/custom/matrix-synapse/defaults/main.yml`
 ```
 
@@ -62,26 +70,26 @@ Migrating your existing data can happen in multiple ways:
 
 Instead of using `s3_media_upload` directly, which is very slow and painful for an initial data migration, we recommend [using another tool in combination with `s3_media_upload`](#using-another-tool-in-combination-with-s3_media_upload).
 
-To copy your existing files, SSH into the server and run `/usr/local/bin/matrix-synapse-s3-storage-provider-shell`.
+To copy your existing files, SSH into the server and run `/matrix/synapse/ext/s3-storage-provider/bin/shell`.
 
 This launches a Synapse container, which has access to the local media store, Postgres database, S3 store and has some convenient environment variables configured for you to use (`MEDIA_PATH`, `BUCKET`, `ENDPOINT`, `UPDATE_DB_DAYS`, etc).
 
 Then use the following commands (`$` values come from environment variables - they're **not placeholders** that you need to substitute):
 
-- `s3_media_upload update-db $UPDATE_DB_DURATION` - create a local SQLite database (`cache.db`) with a list of media repository files (from the `synapse` Postgres database) eligible for operating on
+1. `s3_media_upload update-db $UPDATE_DB_DURATION` - create a local SQLite database (`cache.db`) with a list of media repository files (from the `synapse` Postgres database) eligible for operating on
   - `$UPDATE_DB_DURATION` is influenced by the `matrix_synapse_ext_synapse_s3_storage_provider_update_db_day_count` variable (defaults to `0`)
   - `$UPDATE_DB_DURATION` defaults to `0d` (0 days), which means **include files which haven't been accessed for more than 0 days** (that is, **all files will be included**).
-- `s3_media_upload check-deleted $MEDIA_PATH` - check whether files in the local cache still exist in the local media repository directory
-- `s3_media_upload upload $MEDIA_PATH $BUCKET --delete --storage-class $STORAGE_CLASS --endpoint-url $ENDPOINT` - uploads locally-stored files to S3 and deletes them from the local media repository directory
+2. `s3_media_upload check-deleted $MEDIA_PATH` - check whether files in the local cache still exist in the local media repository directory
+3. `s3_media_upload upload $MEDIA_PATH $BUCKET --delete --storage-class $STORAGE_CLASS --endpoint-url $ENDPOINT` - uploads locally-stored files to S3 and deletes them from the local media repository directory
 
 The `s3_media_upload upload` command may take a lot of time to complete.
 
-Instead of running the above commands manually in the shell, you can also run the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` script which will run the same commands automatically. We demonstrate how to do it manually, because:
+Instead of running the above commands manually in the shell, you can also run the `/matrix/synapse/ext/s3-storage-provider/bin/migrate` script which will run the same commands automatically. We demonstrate how to do it manually, because:
 
 - it's what the upstream project demonstrates and it teaches you how to use the `s3_media_upload` tool
 - allows you to check and verify the output of each command, to catch mistakes
 - includes progress bars and detailed output for each command
-- allows you to easily interrupt slow-running commands, etc. (the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` starts a container without interactive TTY support, so `Ctrl+C` may not work and you and require killing via `docker kill ..`)
+- allows you to easily interrupt slow-running commands, etc. (the `/matrix/synapse/ext/s3-storage-provider/bin/migrate` starts a container without interactive TTY support, so `Ctrl+C` may not work and you and require killing via `docker kill ..`)
 
 ### Using another tool in combination with `s3_media_upload`
 
@@ -93,13 +101,29 @@ To migrate your existing local data to S3, we recommend to:
 
 #### Copying data to Amazon S3
 
-Generally, you need to use the `aws s3` tool.
+To copy to AWS S3, start a container on the Matrix server like this:
 
-This documentation section could use an improvement. Ideally, we'd come up with a guide like the one used in [Copying data to Backblaze B2](#copying-data-to-backblaze-b2) - running `aws s3` in a container, etc.
+```sh
+docker run -it --rm \
+-w /work \
+--env-file=/matrix/synapse/ext/s3-storage-provider/env \
+--mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
+--entrypoint=/bin/sh \
+docker.io/amazon/aws-cli:2.9.16 \
+-c 'aws s3 sync /work/. s3://$BUCKET/'
+```
+
+#### Copying data to an S3 alternative using the aws-s3 tool
+
+To copy to a provider other than AWS S3 (e.g. Wasabi, Digital Ocean Spaces, etc.), you can use the command for [Copying data to Amazon S3](#copying-data-to-amazon-s3) with an added `--endpoint-url=$ENDPOINT` argument.
+
+Add this argument to the command **as-is** (`$ENDPOINT` is an environment variable corresponding to `matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url`, so you don't need to touch it). Make sure to add the argument **before** the final quote (`'`) of the command.
 
 #### Copying data to Backblaze B2
 
-To copy to Backblaze B2, start a container like this:
+You can copy files to Backblaze B2 either by following the [Copying data to an S3 alternative using the aws-s3 tool](#copying-data-to-an-s3-alternative-using-the-aws-s3-tool) or by using the B2-specific [b2 command-line tool](https://www.backblaze.com/b2/docs/quick_command_line.html) as described below.
+
+To copy the data using the `b2` tool, start a container on the Matrix server like this:
 
 ```sh
 docker run -it --rm \
@@ -109,7 +133,7 @@ docker run -it --rm \
 --env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
 --mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
 --entrypoint=/bin/sh \
-tianon/backblaze-b2:3.6.0 \
+docker.io/tianon/backblaze-b2:3.6.0 \
 -c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET && b2 sync /work b2://$B2_BUCKET_NAME --skipNewer'
 ```
 
@@ -119,7 +143,7 @@ As described in [How it works?](#how-it-works) above, when new media is uploaded
 
 By default, we periodically ensure that all local files are uploaded to S3 and are then removed from the local filesystem. This is done automatically using:
 
-- the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` script
+- the `/matrix/synapse/ext/s3-storage-provider/bin/migrate` script
 - .. invoked via the `matrix-synapse-s3-storage-provider-migrate.service` service
 - .. triggered by the `matrix-synapse-s3-storage-provider-migrate.timer` timer, every day at 05:00
 

docs/configuring-playbook-synapse.md

@@ -34,15 +34,7 @@ We support a few configuration presets (`matrix_synapse_workers_preset: one-of-e
 
 If you'd like more customization power, you can start with one of the presets and tweak various `matrix_synapse_workers_*_count` variables manually.
 
-If you increase worker counts too much, you may need to increase the maximum number of Postgres connections too (example):
-
-```yaml
-matrix_postgres_process_extra_arguments: [
-  "-c 'max_connections=200'"
-]
-```
-
-**NOTE**: Disabling `matrix-nginx-proxy` (`matrix_nginx_proxy_enabled: false`) (that is, [using your own other webserver](configuring-playbook-own-webserver.md) when running a Synapse worker setup is likely to cause various troubles (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090)).
+When Synapse workers are enabled, the integrated [Postgres database is tuned](maintenance-postgres.md#tuning-postgresql), so that the maximum number of Postgres connections are increased from `200` to `500`. If you need to decrease or increase the number of maximum Postgres connections further, use the `devture_postgres_max_connections` variable.
 
 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-*'`.
 
@@ -56,21 +48,73 @@ Certain Synapse administration tasks (managing users and rooms, etc.) can be per
 
 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)).
 
+This example configuration is for [keycloak](https://www.keycloak.org/), an opensource Identity Provider maintained by Red Hat.
+
+For more detailed documentation on available options and how to setup keycloak, see the [Synapse documentation on OpenID Connect with keycloak](https://github.com/matrix-org/synapse/blob/develop/docs/openid.md#keycloak).
+
 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 %}"
+matrix_synapse_configuration_extension_yaml: |
+  oidc_providers:
+    - idp_id: keycloak
+      idp_name: "My KeyCloak server"
+      issuer: "https://url.ix/auth/realms/{realm_name}"
+      client_id: "matrix"
+      client_secret: "{{ vault_synapse_keycloak }}"
+      scopes: ["openid", "profile"]
+      user_mapping_provider:
+        config:
+          localpart_template: "{% raw %}{{ user.preferred_username }}{% endraw %}"
+          display_name_template: "{% raw %}{{ user.name }}{% endraw %}"
+          email_template: "{% raw %}{{ user.email }}{% endraw %}"
+      allow_existing_users: true # Optional
+      backchannel_logout_enabled: true # Optional
 ```
 
+
+## Customizing templates
+
+[Templates](https://github.com/matrix-org/synapse/blob/develop/docs/templates.md) are used by Synapse for showing **certain web pages** handled by the server, as well as for **email notifications**.
+
+This playbook allows you to customize the default templates (see the [`synapse/res/templates` directory](https://github.com/matrix-org/synapse/tree/develop/synapse/res/templates)).
+
+If template customization is enabled, the playbook will build a custom container image based on the official one.
+
+Your custom templates need to live in a public or private git repository. This repository will be cloned during Synapse image customization (during the playbook run).
+
+To enable template customizations, use a configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) like this:
+
+```yaml
+# If you'd like to ensure that the customized image is built each time the playbook runs, enable this.
+# Otherwise, the customized image will only be rebuilt whenever the Synapse version changes (once every ~2 weeks).
+# matrix_synapse_docker_image_customized_build_nocache: true
+
+matrix_synapse_container_image_customizations_templates_enabled: true
+
+# Our templates live in a templates/ directory within the repository.
+# If they're at the root path, delete this line.
+matrix_synapse_container_image_customizations_templates_in_container_template_files_relative_path: templates
+
+matrix_synapse_container_image_customizations_templates_git_repository_url: git@github.com:organization/repository.git
+matrix_synapse_container_image_customizations_templates_git_repository_branch: main
+
+matrix_synapse_container_image_customizations_templates_git_repository_keyscan_enabled: true
+matrix_synapse_container_image_customizations_templates_git_repository_keyscan_hostname: github.com
+
+# If your git repository is public, do not define the private key (remove the variable).
+matrix_synapse_container_image_customizations_templates_git_repository_ssh_private_key: |
+  -----BEGIN OPENSSH PRIVATE KEY-----
+  ....
+  -----END OPENSSH PRIVATE KEY-----
+```
+
+As mentioned in Synapse's Templates documentation, Synapse will fall back to its own templates if a template is not found in that directory.
+Due to this, it's recommended to only store and maintain template files in your repository if you need to make custom changes. Other files (which you don't need to change), should not be duplicated, so that you don't need to worry about getting out-of-sync with the original Synapse templates.
+
+
+## Monitoring Synapse Metrics with Prometheus and Grafana
+
+This playbook allows you to enable Synapse metrics, which can provide insight into the performance and activity of Synapse.
+
+To enable Synapse metrics see [`configuring-playbook-prometheus-grafana.md`](./configuring-playbook-prometheus-grafana.md)

docs/configuring-playbook-traefik.md

@@ -0,0 +1,50 @@
+# Configure Traefik (optional, advanced)
+
+By default, this playbook installs and manages a [Traefik](https://doc.traefik.io/traefik/) reverse-proxy server, powered by the [com.devture.ansible.role.traefik](https://github.com/devture/com.devture.ansible.role.traefik) Ansible role.
+
+This Ansible role support various configuration options. Feel free to consult its `default/main.yml` variables file.
+
+
+## Adjusting SSL certificate retrieval
+
+See the dedicated [Adjusting SSL certificate retrieval](configuring-playbook-ssl-certificates.md) documentation page.
+
+## Increase logging verbosity
+
+```yaml
+devture_traefik_config_log_level: DEBUG
+```
+
+## Disable access logs
+
+This will disable access logging.
+
+```yaml
+devture_traefik_config_accessLog_enabled: false
+```
+
+## Enable Traefik Dashboard
+
+This will enable a Traefik [Dashboard](https://doc.traefik.io/traefik/operations/dashboard/) UI at `https://matrix.DOMAIN/dashboard/` (note the trailing `/`).
+
+```yaml
+devture_traefik_dashboard_enabled: true
+devture_traefik_dashboard_hostname: "{{ matrix_server_fqn_matrix }}"
+devture_traefik_dashboard_basicauth_enabled: true
+devture_traefik_dashboard_basicauth_user: YOUR_USERNAME_HERE
+devture_traefik_dashboard_basicauth_password: YOUR_PASSWORD_HERE
+```
+
+**WARNING**: enabling the dashboard on a hostname you use for something else (like `matrix_server_fqn_matrix` in the configuration above) may cause conflicts. Enabling the Traefik Dashboard makes Traefik capture all `/dashboard` and `/api` requests and forward them to itself. If any of the services hosted on the same hostname requires any of these 2 URL prefixes, you will experience problems. So far, we're not aware of any playbook services which occupy these endpoints and are likely to cause conflicts.
+
+## Additional configuration
+
+Use the `devture_traefik_configuration_extension_yaml` variable provided by the Traefik Ansible role to override or inject additional settings, even when no dedicated variable exists.
+
+```yaml
+# This is a contrived example.
+# You can enable and secure the Dashboard using dedicated variables. See above.
+devture_traefik_configuration_extension_yaml: |
+  api:
+    dashboard: true
+```

docs/configuring-playbook-turn.md

@@ -15,6 +15,24 @@ matrix_coturn_enabled: false
 
 In that case, Synapse would not point to any Coturn servers and audio/video call functionality may fail.
 
+## Manually defining your public IP
+
+In the `hosts` file we explicitly ask for your server's external IP address when defining `ansible_host`, because the same value is used for configuring Coturn.
+
+If you'd rather use a local IP for `ansible_host`, make sure to set up `matrix_coturn_turn_external_ip_address` replacing `YOUR_PUBLIC_IP` with the pubic IP used by the server.
+
+```yaml
+matrix_coturn_turn_external_ip_address: "YOUR_PUBLIC_IP"
+```
+
+If you'd like to rely on external IP address auto-detection (not recommended unless you need it), set `matrix_coturn_turn_external_ip_address` to an empty value. The playbook will automatically contact an [EchoIP](https://github.com/mpolden/echoip)-compatible service (`https://ifconfig.co/json` by default) to determine your server's IP address. This API endpoint is configurable via the `matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_url` variable.
+
+If your server has multiple external IP addresses, the Coturn role offers a different variable for specifying them:
+
+```yaml
+# Note: matrix_coturn_turn_external_ip_addresses is different than matrix_coturn_turn_external_ip_address
+matrix_coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']
+```
 
 ## Using your own external Coturn server
 
@@ -36,7 +54,10 @@ If you have or want to enable [Jitsi](configuring-playbook-jitsi.md), you might
 If you do not do it, Jitsi will fall back to an upstream service.
 
 ```yaml
-matrix_jitsi_web_stun_servers:
+jitsi_web_stun_servers:
 - stun:HOSTNAME_OR_IP:PORT
 ```
 You can put multiple host/port combinations if you like.
+
+## Further variables and configuration options
+To see all the available configuration options, check roles/custom/matrix-coturn/defaults/main.yml

docs/configuring-playbook-user-verification-service.md

@@ -0,0 +1,125 @@
+# Setting up Matrix User Verification Service (optional)
+
+**[Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (hereafter: UVS) 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.
+
+Currently, the main purpose of this role is to allow Jitsi to authenticate matrix users and check if they are authorized to join a conference. Please refer to the documentation of the [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) to understand how it works.
+
+**Note**: enabling Matrix User Verification Service, 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.
+
+If the Jitsi server is also configured by this playbook, all plugging of variables and secrets is handled in `group_vars/matrix_servers`.
+
+__Some general concepts of UVS may be helpful to understand the rest, so here they are:__
+
+UVS can be used to verify two claims: 
+
+* (A) Whether a given OpenID token is valid for a given server and
+* (B) whether a user is member of a given room and the corresponding PowerLevel
+
+Verifying an OpenID token id done by finding the corresponding Homeserver via  '.well-known/matrix/server' for the given domain.
+The configured `matrix_user_verification_service_uvs_homeserver_url` does **not** factor into this.
+By default, this playbook only checks against `matrix_server_fqn_matrix`.
+Therefore, the request will be made against the public openid API for `matrix_server_fqn_matrix`.
+
+Verifying RoomMembership and PowerLevel is done against `matrix_user_verification_service_uvs_homeserver_url` which is by default done via the docker network.
+UVS will verify the validity of the token beforehand though.
+
+## Prerequisites
+
+In order to use UVS, an admin token for the configured homeserver must be supplied. For now this means configuring Synapse and creating the token before installing UVS.
+
+## Enable
+
+[Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) installation is disabled by default.
+You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+
+```yaml
+matrix_user_verification_service_enabled: true
+```
+
+## Configuration
+
+The only required configuration variable is `matrix_user_verification_service_uvs_access_token` (see below).
+
+For a list of all configuration options see the role defaults [`roles/matrix-user-verification-service/defaults/main.yml`](../roles/custom/matrix-user-verification-service/defaults/main.yml).
+But be aware of all the plugging happening in `group_vars/matrix_servers`.
+
+In the default configuration, the UVS Server is only reachable via the docker network, which is fine if e.g. Jitsi is also running in a container on the host.
+However, it is possible to expose UVS via setting `matrix_user_verification_service_container_http_host_bind_port`.
+
+### Access token
+
+The Synapse Access Token is used to verify RoomMembership and PowerLevel against `matrix_user_verification_service_uvs_homeserver_url`.
+
+We recommend that you create a dedicated Matrix user for uvs (`uvs` is a good username).
+Follow our [Registering users](registering-users.md) guide to register a user with administration privileges.
+
+You are required to specify an access token (belonging to this new user) for UVS to work.
+To get an access token for the UVS user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
+
+**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
+
+```yaml
+matrix_user_verification_service_uvs_access_token: "YOUR ACCESS TOKEN HERE"
+```
+
+### (Optional) Custom Auth Token
+
+It is possible to set an API Auth Token to restrict access to the UVS. If this is enabled, anyone making a request to UVS must provide it via the header "Authorization: Bearer TOKEN"
+
+By default, the token will be derived from `matrix_homeserver_generic_secret_key` in `group_vars/matrix_servers`.
+To set your own Token, simply put the following in your host_vars.
+
+```yaml
+matrix_user_verification_service_uvs_auth_token: "TOKEN"
+```
+
+In case Jitsi is also managed by this playbook and 'matrix' authentication in Jitsi is enabled, this collection will automatically configure Jitsi to use the configured auth token.
+
+###  (Optional) Disable Auth
+Authorization is enabled by default. To disable set
+
+```yaml
+matrix_user_verification_service_uvs_require_auth: false
+```
+
+in your host_vars.
+
+### (Optional) Federation
+
+In theory (however currently untested), UVS can handle federation. Simply set:
+
+```yaml
+matrix_user_verification_service_uvs_pin_openid_verify_server_name: false
+```
+
+in your host_vars.
+
+This will instruct UVS to verify the OpenID token against any domain given in a request. 
+Homeserver discovery is done via '.well-known/matrix/server' of the given domain.
+
+## Installation
+
+After these variables have been set, please run the following command to re-run setup and to restart UVS:
+
+```
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-user-verification-service,start
+```
+
+## Logging
+
+The configuration variable `UVS_LOG_LEVEL` can be set to: 
+- warning
+- info
+- debug
+
+## TLS Certificate Checking
+If the matrix Homeserver does not provide a valid TLS certificate, UVS will fail with the following error message:
+
+> message: 'No response received: [object Object]',
+
+This also applies to self-signed and let's encrypt staging certificates.
+
+To disable certificate validation altogether (INSECURE! Not suitable for production use!) set: `NODE_TLS_REJECT_UNAUTHORIZED=0`
+
+Alternatively, it is possible to inject your own CA certificates into the container by mounting a PEM file with additional trusted CAs into the container and pointing the `NODE_EXTRA_CA_CERTS` environment variable to it.

docs/configuring-playbook.md

@@ -12,7 +12,7 @@ You can then follow these steps inside the playbook directory:
 
 1. copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
 
-1. edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at the various `roles/ROLE_NAME_HERE/defaults/main.yml` files and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.
+1. edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at the various `roles/*/ROLE_NAME_HERE/defaults/main.yml` files and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.
 
 1. copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
 
@@ -30,7 +30,7 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 ### Additional useful services
 
-- [Setting up the Dimension Integration Manager](configuring-playbook-dimension.md) (optional, but recommended; after [installing](installing.md))
+- [Setting up the Dimension Integration Manager](configuring-playbook-dimension.md) (optional; [unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299); after [installing](installing.md))
 
 - [Setting up the Jitsi video-conferencing platform](configuring-playbook-jitsi.md) (optional)
 
@@ -51,6 +51,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Configuring Element](configuring-playbook-client-element.md) (optional)
 
+- [Storing Matrix media files using matrix-media-repo](configuring-playbook-matrix-media-repo.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)
@@ -59,9 +61,11 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Serving your base domain using this playbook's nginx server](configuring-playbook-base-domain-serving.md) (optional)
 
-- [Configure Nginx](configuring-playbook-nginx.md) (optional, advanced)
+- [Configure the Traefik reverse-proxy](configuring-playbook-traefik.md) (optional, advanced)
 
-- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced)
+- (Deprecated) [Configure the Nginx reverse-proxy](configuring-playbook-nginx.md) (optional, advanced)
+
+- [Using your own webserver, instead of this playbook's default reverse-proxy](configuring-playbook-own-webserver.md) (optional, advanced)
 
 - [Adjusting TURN server configuration](configuring-playbook-turn.md) (optional, advanced)
 
@@ -78,6 +82,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Cinny](configuring-playbook-client-cinny.md) - a web client focusing primarily on simple, elegant and secure interface (optional)
 
+- [Setting up SchildiChat](configuring-playbook-client-schildichat.md) - a web client based on [Element](https://element.io/) with some extras and tweaks (optional)
+
 
 ### Authentication and user-related
 
@@ -99,6 +105,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced)
 
+- [Matrix User Verification Service](configuring-playbook-user-verification-service.md) (optional, advanced)
+
 
 ### Bridging other networks
 
@@ -106,6 +114,10 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional)
 
+- [Setting up Mautrix Slack bridging](configuring-playbook-bridge-mautrix-slack.md) (optional)
+
+- [Setting up Mautrix Google Messages bridging](configuring-playbook-bridge-mautrix-gmessages.md) (optional)
+
 - [Setting up Mautrix Whatsapp bridging](configuring-playbook-bridge-mautrix-whatsapp.md) (optional)
 
 - [Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md) (optional)
@@ -120,6 +132,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Mautrix Signal bridging](configuring-playbook-bridge-mautrix-signal.md) (optional)
 
+- [Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage](configuring-playbook-bridge-mautrix-wsproxy.md) (optional)
+
 - [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional)
 
 - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional)
@@ -161,6 +175,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 ### Bots
 
+- [Setting up matrix-bot-chatgpt](configuring-playbook-bot-chatgpt.md) - a bot through which you can talk to the [ChatGPT](https://openai.com/blog/chatgpt/) model(optional)
+
 - [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)
@@ -173,6 +189,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Mjolnir](configuring-playbook-bot-mjolnir.md) - a moderation tool/bot (optional)
 
+- [Setting up Draupnir](configuring-playbook-bot-draupnir.md) - a moderation tool/bot, forked from Mjolnir and maintained by its former leader developer (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)
 
 
@@ -185,8 +203,14 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 ### Other specialized services
 
+- [Setting up synapse-auto-compressor](configuring-playbook-synapse-auto-compressor.md) for compressing the database on Synapse homeservers (optional)
+
+- [Setting up the Sliding Sync Proxy](configuring-playbook-sliding-sync-proxy.md) for clients which require Sliding Sync support (like Element X) (optional)
+
 - [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional)
 
 - [Setting up the ntfy push notifications server](configuring-playbook-ntfy.md) (optional)
 
 - [Setting up a Cactus Comments server](configuring-playbook-cactus-comments.md) - a federated comment system built on Matrix (optional)
+
+- [Setting up the Rageshake bug report server](configuring-playbook-rageshake.md) (optional)

docs/container-images.md

@@ -46,6 +46,8 @@ These services are not part of our default installation, but can be enabled by [
 
 - [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/gmessages](https://mau.dev/mautrix/gmessages/container_registry) - the [mautrix-gmessages](https://github.com/mautrix/gmessages) bridge to [Google Messages](https://messages.google.com/) (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)

docs/faq.md

@@ -125,7 +125,7 @@ This is similar to the [EMnify/matrix-synapse-auto-deploy](https://github.com/EM
 
 - 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 **doesn't necessarily take over** ports 80 and 443. By default, it sets up [Traefik](https://doc.traefik.io/traefik/) 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))
 
@@ -262,7 +262,7 @@ matrix_server_fqn_element: "element.YOUR_BASE_DOMAIN"
 # 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).
+# This is where you access Jitsi (if enabled via `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"
@@ -317,12 +317,12 @@ If you've installed [Jitsi](configuring-playbook-jitsi.md) (not installed by def
 Yes, we can stop installing Docker ourselves. Just use this in your `vars.yml` file:
 
 ```yaml
-matrix_playbook_docker_installation_enabled: true
+matrix_playbook_docker_installation_enabled: false
 ```
 
 ### 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).
+By default, we install a webserver for you ([Traefik](https://doc.traefik.io/traefik/)), but you can also use [your own webserver](configuring-playbook-own-webserver.md).
 
 ### How is the effective configuration determined?
 
@@ -336,12 +336,14 @@ Configuration variables are defined in multiple places in this playbook and are
 
 ### What configuration variables are available?
 
-You can discover the variables you can override in each role (`role/matrix*/defaults/main.yml`).
+You can discover the variables you can override in each role (`roles/*/*/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).
 
+**Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`).
+
 ### 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.
@@ -352,7 +354,9 @@ See [What configuration variables are available?](#what-configuration-variables-
 
 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.
+Check each role's `roles/*/*/defaults/main.yml` for the corresponding variable and an example for how use it.
+
+**Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`).
 
 
 ## Installation
@@ -461,15 +465,8 @@ After verifying that everything still works after the Postgres upgrade, you can
 
 ### 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).
+SSL certificates are managed automatically by the [Traefik](https://doc.traefik.io/traefik/) reverse-proxy server.
 
-If you're having trouble with SSL certificate renewal, you can inspect the renewal logs using:
+If you're having trouble with SSL certificate renewal, check the Traefik logs (`journalctl -fu matrix-traefik`).
 
-- `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.
+If you're [using your own webserver](configuring-playbook-own-webserver.md) instead of the integrated one (Traefik), you should investigate in another way.

docs/howto-server-delegation.md

@@ -49,6 +49,7 @@ To use DNS SRV record validation, you need to:
 
 - 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.
 
+For more details on [how to configure the playbook to work with SRV delegation](howto-srv-server-delegation.md)
 
 ### Obtaining certificates
 

docs/howto-srv-server-delegation.md

@@ -0,0 +1,206 @@
+# Server Delegation via a DNS SRV record (advanced)
+
+**Reminder** : unless you are affected by the [Downsides of well-known-based Server Delegation](howto-server-delegation.md#downsides-of-well-known-based-server-delegation), we suggest you **stay on the simple/default path**: [Server Delegation](howto-server-delegation.md) by [configuring well-known files](configuring-well-known.md) at the base domain. 
+
+This guide is about configuring Server Delegation using DNS SRV records (for the [Traefik](https://doc.traefik.io/traefik/) webserver). This method has special requirements when it comes to SSL certificates, so various changes are required.
+
+## Prerequisites
+
+SRV delegation while still using the playbook provided Traefik to get / renew the certificate requires a wildcard certificate.
+
+To obtain / renew one from [Let's Encrypt](https://letsencrypt.org/), one needs to use a [DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) method instead of the default [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge).
+
+This means that this is **limited to the list of DNS providers supported by Traefik**, unless you bring in your own certificate.
+
+The up-to-date list can be accessed on [traefik's documentation](https://doc.traefik.io/traefik/https/acme/#providers)
+
+## The changes
+
+### Federation Endpoint
+
+```yaml
+# To serve the federation from any domain, as long as the path match
+matrix_nginx_proxy_container_labels_traefik_proxy_matrix_federation_rule: PathPrefix(`/_matrix`)
+```
+
+This is because with SRV federation, some servers / tools (one of which being the federation tester) try to access the federation API using the resolved IP address instead of the domain name (or they are not using SNI). This change will make Traefik route all traffic for which the path match this rule go to the federation endpoint.
+
+### Tell Traefik which certificate to serve for the federation endpoint
+
+Now that the federation endpoint is not bound to a domain anymore we need to explicitely tell Traefik to use a wildcard certificate in addition to one containing the base name.
+
+This is because the matrix specification expects the federation endpoint to be served using a certificate comatible with the base domain, however, the other resources on the endpoint still need a valid certificate to work.
+
+```yaml
+# To let Traefik know which domains' certificates to serve
+matrix_nginx_proxy_container_labels_additional_labels: |
+  traefik.http.routers.matrix-nginx-proxy-matrix-federation.tls.domains.main="example.com"
+  traefik.http.routers.matrix-nginx-proxy-matrix-federation.tls.domains.sans="*.example.com"
+```
+
+### Configure the DNS-01 challenge for let's encrypt
+
+Since we're now requesting a wildcard certificate, we need to change the ACME challenge method. To request a wildcard certificate from Let's Encrypt we are required to use the DNS-01 challenge.
+
+This will need 3 changes:
+1. Add a new certificate resolver that works with DNS-01
+2. Configure the resolver to allow access to the DNS zone to configure the records to answer the challenge (refer to [Traefik's documentation](https://doc.traefik.io/traefik/https/acme/#providers) to know which environment variables to set)
+3. Tell the playbook to use the new resolver as default
+
+We cannot just disable the default resolver as that would disable SSL in quite a few places in the playbook.
+
+```yaml
+# 1. Add a new ACME configuration without having to disable the default one, since it would have a wide range of side effects
+devture_traefik_configuration_extension_yaml: |
+  certificatesResolvers:
+    dns:
+      acme:
+        # To use a staging endpoint for testing purposes, uncomment the line below.
+        # caServer: https://acme-staging-v02.api.letsencrypt.org/directory
+        email: {{ devture_traefik_config_certificatesResolvers_acme_email | to_json }}
+        dnsChallenge:
+          provider: cloudflare
+          resolvers: 
+            - "1.1.1.1:53"
+            - "8.8.8.8:53"
+        storage: {{ devture_traefik_config_certificatesResolvers_acme_storage | to_json }}
+
+# 2. Configure the environment variables needed by Rraefik to automate the ACME DNS Challenge (example for Cloudflare)
+devture_traefik_environment_variables: |
+  CF_API_EMAIL=redacted
+  CF_ZONE_API_TOKEN=redacted
+  CF_DNS_API_TOKEN=redacted
+  LEGO_DISABLE_CNAME_SUPPORT=true
+
+# 3. Instruct the playbook to use the new ACME configuration
+devture_traefik_certResolver_primary: dns
+```
+
+## Adjust Coturn's configuration
+
+The last step is to alter the generated Coturn configuration.
+
+By default, Coturn is configured to wait on the certificate for the `matrix.` subdomain using an [instantiated systemd service](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Service%20Templates) using the domain name as the parameter for this service. However, we need to serve the wildcard certificate, which is incompatible with systemd, it will try to expand the `*`, which will break and prevent Coturn from starting.
+
+We also need to indicate to Coturn where the wildcard certificate is.
+
+**⚠ WARNING ⚠** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`).
+
+This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the Coturn service is setup to restart periodically.
+
+```yaml
+# Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
+matrix_coturn_systemd_required_services_list: ['docker.service']
+
+# This changes the path of the loaded certificate, while maintaining the original functionality, we're now loading the wildcard certificate.
+matrix_coturn_container_additional_volumes: |
+  {{
+    (
+      [
+       {
+         'src': (matrix_ssl_config_dir_path + '/live/*.' + matrix_domain + '/fullchain.pem'),
+         'dst': '/fullchain.pem',
+         'options': 'ro',
+       },
+       {
+         'src': (matrix_ssl_config_dir_path + '/live/*.' + matrix_domain + '/privkey.pem'),
+         'dst': '/privkey.pem',
+         'options': 'ro',
+       },
+      ] if matrix_playbook_reverse_proxy_type in ['playbook-managed-nginx', 'other-nginx-non-container'] and matrix_coturn_tls_enabled else []
+    )
+    +
+    (
+      [
+       {
+         'src': (devture_traefik_certs_dumper_dumped_certificates_dir_path +  '/*.' + matrix_domain + '/certificate.crt'),
+         'dst': '/certificate.crt',
+         'options': 'ro',
+       },
+       {
+         'src': (devture_traefik_certs_dumper_dumped_certificates_dir_path +  '/*.' + matrix_domain + '/privatekey.key'),
+         'dst': '/privatekey.key',
+         'options': 'ro',
+       },
+      ] if matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] and devture_traefik_certs_dumper_enabled and matrix_coturn_tls_enabled else []
+    )
+  }}
+```
+
+## Full example of a working configuration
+
+```yaml
+# Choosing the reverse proxy implementation
+matrix_playbook_reverse_proxy_type: playbook-managed-traefik
+devture_traefik_config_certificatesResolvers_acme_email: redacted@example.com
+
+# To serve the federation from any domain, as long as the path match
+matrix_nginx_proxy_container_labels_traefik_proxy_matrix_federation_rule: PathPrefix(`/_matrix`)
+
+# To let Traefik know which domains' certificates to serve
+matrix_nginx_proxy_container_labels_additional_labels: |
+  traefik.http.routers.matrix-nginx-proxy-matrix-federation.tls.domains.main="example.com"
+  traefik.http.routers.matrix-nginx-proxy-matrix-federation.tls.domains.sans="*.example.com"
+
+# Add a new ACME configuration without having to disable the default one, since it would have a wide range of side effects
+devture_traefik_configuration_extension_yaml: |
+  certificatesResolvers:
+    dns:
+      acme:
+        # To use a staging endpoint for testing purposes, uncomment the line below.
+        # caServer: https://acme-staging-v02.api.letsencrypt.org/directory
+        email: {{ devture_traefik_config_certificatesResolvers_acme_email | to_json }}
+        dnsChallenge:
+          provider: cloudflare
+          resolvers: 
+            - "1.1.1.1:53"
+            - "8.8.8.8:53"
+        storage: {{ devture_traefik_config_certificatesResolvers_acme_storage | to_json }}
+
+# Instruct thep laybook to use the new ACME configuration
+devture_traefik_certResolver_primary: "dns"
+
+# Configure the environment variables needed by Traefik to automate the ACME DNS Challenge (example for Cloudflare)
+devture_traefik_environment_variables: |
+  CF_API_EMAIL=redacted
+  CF_ZONE_API_TOKEN=redacted
+  CF_DNS_API_TOKEN=redacted
+  LEGO_DISABLE_CNAME_SUPPORT=true
+
+# Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart Coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
+matrix_coturn_systemd_required_services_list: ['docker.service']
+
+# This changes the path of the loaded certificate, while maintaining the original functionality, we're now loading the wildcard certificate.
+matrix_coturn_container_additional_volumes: |
+  {{
+    (
+      [
+       {
+         'src': (matrix_ssl_config_dir_path + '/live/*.' + matrix_domain + '/fullchain.pem'),
+         'dst': '/fullchain.pem',
+         'options': 'ro',
+       },
+       {
+         'src': (matrix_ssl_config_dir_path + '/live/*.' + matrix_domain + '/privkey.pem'),
+         'dst': '/privkey.pem',
+         'options': 'ro',
+       },
+      ] if matrix_playbook_reverse_proxy_type in ['playbook-managed-nginx', 'other-nginx-non-container'] and matrix_coturn_tls_enabled else []
+    )
+    +
+    (
+      [
+       {
+         'src': (devture_traefik_certs_dumper_dumped_certificates_dir_path +  '/*.' + matrix_domain + '/certificate.crt'),
+         'dst': '/certificate.crt',
+         'options': 'ro',
+       },
+       {
+         'src': (devture_traefik_certs_dumper_dumped_certificates_dir_path +  '/*.' + matrix_domain + '/privatekey.key'),
+         'dst': '/privatekey.key',
+         'options': 'ro',
+       },
+      ] if matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] and devture_traefik_certs_dumper_enabled and matrix_coturn_tls_enabled else []
+    )
+  }}
+```

docs/importing-postgres.md

@@ -20,19 +20,19 @@ Before doing the actual import, **you need to upload your Postgres dump file to
 
 ## Importing
 
-To import, run this command (make sure to replace `<server-path-to-postgres-dump.sql>` with a file path on your server):
+To import, run this command (make sure to replace `SERVER_PATH_TO_POSTGRES_DUMP_FILE` with a file path on your server):
 
 ```sh
-ansible-playbook -i inventory/hosts setup.yml \
---extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql> postgres_default_import_database=matrix' \
---tags=import-postgres
+just run-tags import-postgres \
+--extra-vars=server_path_postgres_dump=SERVER_PATH_TO_POSTGRES_DUMP_FILE \
+--extra-vars=postgres_default_import_database=matrix
 ```
 
 **Notes**:
 
-- `<server-path-to-postgres-dump.sql>` must be a file path to a Postgres dump file on the server (not on your local machine!)
+- `SERVER_PATH_TO_POSTGRES_DUMP_FILE` must be a file path to a Postgres dump file on the server (not on your local machine!)
 - `postgres_default_import_database` defaults to `matrix`, which is useful for importing multiple databases (for dumps made with `pg_dumpall`). If you're importing a single database (e.g. `synapse`), consider changing `postgres_default_import_database` accordingly
-
+- after importing a large database, it's a good idea to run [an `ANALYZE` operation](https://www.postgresql.org/docs/current/sql-analyze.html) to make Postgres rebuild its database statistics and optimize its query planner. You can easily do this via the playbook by running `just run-tags run-postgres-vacuum -e postgres_vacuum_preset=analyze` (see [Vacuuming PostgreSQL](maintenance-postgres.md#vacuuming-postgresql) for more details).
 
 ## Troubleshooting
 
@@ -86,7 +86,7 @@ In this case you can use the command suggested in the import task to clear the d
 # 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.
+Now on your local machine run `just run-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.
 ```
@@ -97,9 +97,9 @@ Once the database is clear and the ownership of the tables has been fixed in the
 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"
+/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:15.0-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`
+To open psql terminal run `/matrix/postgres/bin/cli`

docs/importing-synapse-sqlite.md

@@ -3,24 +3,28 @@
 Run this if you'd like to import your database from a previous default installation of Synapse.
 (don't forget to import your `media_store` files as well - see [the importing-synapse-media-store guide](importing-synapse-media-store.md)).
 
-While this playbook always sets up PostgreSQL, by default a Synapse installation would run
-using an SQLite database.
+While this playbook only supports running Synapse in combination with PostgreSQL, a Synapse instance installed manually usually defaults to using an SQLite database.
 
-If you have such a Synapse setup and wish to migrate it here (and over to PostgreSQL), this command is for you.
+If you have such a Synapse setup and wish to migrate it to one managed by the playbook (and over to PostgreSQL), this documentation page is for you.
 
 
 ## Prerequisites
 
-Before doing the actual import, **you need to upload your SQLite database file to the server** (any path is okay).
+Before doing the actual import:
 
+- **ensure you have NOT started Synapse yet**. That is, make sure you have followed the [Installing step](installing.md), but haven't run the playbook's `start` tag yet. If you had started your new Synapse instance, it may have already initialized your Postgres database and importing onto it may not work. In such cases, you may need to clean up the `synapse` database first.
+- **ensure you have uploaded your SQLite database file to the server** (any path is okay)
+- if you're using the integrated Postgres server (**by default, you are** using it, unless you've explicitly switched to [Using an external PostgreSQL server](configuring-playbook-external-postgres.md)), **make sure Postgres is started** by running `just start-group postgres`
 
 ## Importing
 
 Run this command (make sure to replace `<server-path-to-homeserver.db>` with a file path on your server):
 
-	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_homeserver_db=<server-path-to-homeserver.db>' --tags=import-synapse-sqlite-db
+```sh
+just run-tags import-synapse-sqlite-db --extra-vars=server_path_homeserver_db=<server-path-to-homeserver.db>
+```
 
 **Notes**:
 
-- `<server-path-to-homeserver.db>` must be a file path to a `homeserver.db` **file on the server** (not on your local machine!).
+- `<server-path-to-homeserver.db>` must be replaced with 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

@@ -2,7 +2,7 @@
 
 If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure.
 
-**Before installing** and each time you update the playbook in the future, you will need to update the Ansible roles in this playbook by running `make roles`. `make roles` is a shortcut (a `roles` target defined in [`Makefile`](Makefile) and executed by the [`make`](https://www.gnu.org/software/make/) utility) which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles. If you don't have `make`, you can also manually run the `roles` commands seen in the `Makefile`.
+**Before installing** and each time you update the playbook in the future, you will need to update the Ansible roles in this playbook by running `just roles`. `just roles` is a shortcut (a `roles` target defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`.
 
 
 ## Playbook tags introduction
@@ -17,7 +17,7 @@ Here are some playbook tags that you should be familiar with:
 
 - `install-all` - like `setup-all`, but skips uninstallation tasks. Useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove components, you'd need to run `setup-all` though, or these components will still remain installed
 
-- `setup-SERVICE` (e.g. `setup-bot-postmoogle`) - runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (`roles/*/main.yml`). Running per-component setup tasks is **not recommended**, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, setting up the [mautrix-telegram bridge](configuring-playbook-bridge-mautrix-telegram.md), in addition to the `setup-mautrix-telegram` tag, requires database changes (the `setup-postgres` tag) as well as reverse-proxy changes (the `setup-nginx-proxy` tag).
+- `setup-SERVICE` (e.g. `setup-bot-postmoogle`) - runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (`roles/**/tasks/main.yml`). Running per-component setup tasks is **not recommended**, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, setting up the [mautrix-telegram bridge](configuring-playbook-bridge-mautrix-telegram.md), in addition to the `setup-mautrix-telegram` tag, requires database changes (the `setup-postgres` tag) as well as reverse-proxy changes (the `setup-nginx-proxy` tag).
 
 - `install-SERVICE` (e.g. `install-bot-postmoogle`) - like `setup-SERVICE`, but skips uninstallation tasks. See `install-all` above for additional information.
 
@@ -57,7 +57,7 @@ Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-t
 If you will be importing data into your newly created Matrix server, install it, but **do not** start its services just yet.
 Starting its services or messing with its database now will affect your data import later on.
 
-To do the installation **without** starting services, run only the `setup-all` tag:
+To do the installation **without** starting services, run only the `install-all` tag:
 
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=install-all
@@ -88,6 +88,8 @@ Feel free to **re-run the setup command any time** you think something is off wi
 
 Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [Playbook tags introduction](#playbook-tags-introduction)
 
+A way to invoke these `ansible-playbook` commands with less typing in the future is to use [just](https://github.com/casey/just) to run them: `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information.
+
 
 ## 3. Finalize the installation
 

docs/maintenance-migrating.md

@@ -5,7 +5,7 @@
 # Migrating to new server
 
 1. Prepare by lowering DNS TTL for your domains (`matrix.DOMAIN`, etc.), so that DNS record changes (step 4 below) would happen faster, leading to less downtime
-2. Stop all services on the old server and make sure they won't be starting again. Execute this on the old server: `systemctl disable --now matrix*`
+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*` (you might have to cd to /etc/systemd/system/ first)
 3. Copy directory `/matrix` from the old server to the new server. Make sure to preserve ownership and permissions (use `cp -p` or `rsync -ar`)!
 4. Make sure your DNS records are adjusted to point to the new server's IP address
 5. Remove old server from the `inventory/hosts` file and add new server.

docs/maintenance-postgres.md

@@ -16,7 +16,7 @@ Table of contents:
 
 ## Getting a database terminal
 
-You can use the `/usr/local/bin/matrix-postgres-cli` tool to get interactive terminal access ([psql](https://www.postgresql.org/docs/11/app-psql.html)) to the PostgreSQL server.
+You can use the `/matrix/postgres/bin/cli` tool to get interactive terminal access ([psql](https://www.postgresql.org/docs/11/app-psql.html)) to the PostgreSQL server.
 
 If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above tool will not be available.
 
@@ -34,17 +34,22 @@ 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.
+Deleting lots data from Postgres does not make it release disk space, until you perform a [`VACUUM` operation](https://www.postgresql.org/docs/current/sql-vacuum.html).
 
-To perform a `FULL` Postgres [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html), run the playbook with `--tags=run-postgres-vacuum`.
+You can run different `VACUUM` operations via the playbook, with the default preset being `vacuum-complete`:
 
-Example:
+- (default) `vacuum-complete`: stops all services temporarily and runs `VACUUM FULL VERBOSE ANALYZE`.
+- `vacuum-full`: stops all services temporarily and runs `VACUUM FULL VERBOSE`
+- `vacuum`: runs `VACUUM VERBOSE` without stopping any services
+- `vacuum-analyze` runs `VACUUM VERBOSE ANALYZE` without stopping any services
+- `analyze` runs `ANALYZE VERBOSE` without stopping any services (this is just [ANALYZE](https://www.postgresql.org/docs/current/sql-analyze.html) without doing a vacuum, so it's faster)
 
-```bash
-ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-vacuum,start
-```
+**Note**: for the `vacuum-complete` and `vacuum-full` presets, you'll need plenty of available disk space in your Postgres data directory (usually `/matrix/postgres/data`). These presets also stop all services (e.g. Synapse, etc.) while the vacuum operation is running.
 
-**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`).
+Example playbook invocations:
+
+- `just run-tags run-postgres-vacuum`: runs the default `vacuum-complete` preset and restarts all services
+- `just run-tags run-postgres-vacuum -e postgres_vacuum_preset=analyze`: runs the `analyze` preset with all services remaining operational at all times
 
 
 ## Backing up PostgreSQL
@@ -78,9 +83,11 @@ Upgrades must be performed manually.
 
 This playbook can upgrade your existing Postgres setup with the following command:
 
-	ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres
+```sh
+just run-tags upgrade-postgres
+```
 
-**Warning: If you're using Borg Backup keep in mind that there is no official Postgres 15 support yet.**
+**Warning: If you're using Borg Backup keep in mind that there is no official Postgres 16 support yet.**
 
 **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"`
@@ -99,63 +106,15 @@ Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
 
 ## 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.
+PostgreSQL can be [tuned](https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server) to make it run faster. This is done by passing extra arguments to the Postgres process.
 
-**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`)
+The [Postgres Ansible role](https://github.com/devture/com.devture.ansible.role.postgres) **already does some tuning by default**, which matches the [tuning logic](https://github.com/le0pard/pgtune/blob/master/src/features/configuration/configurationSlice.js) done by websites like https://pgtune.leopard.in.ua/.
+You can manually influence some of the tuning variables . These parameters (variables) are injected via the `devture_postgres_postgres_process_extra_arguments_auto` variable.
 
-### Here are some examples:
+Most users should be fine with the automatically-done tuning. However, you may wish to:
 
-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.
+- **adjust the automatically-deterimned tuning parameters manually**: change the values for the tuning variables defined in the Postgres role's [default configuration file](https://github.com/devture/com.devture.ansible.role.postgres/blob/main/defaults/main.yml) (see `devture_postgres_max_connections`, `devture_postgres_data_storage` etc). These variables are ultimately passed to Postgres via a `devture_postgres_postgres_process_extra_arguments_auto` variable
 
-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",
-]
-```
+- **turn automatically-performed tuning off**: override it like this: `devture_postgres_postgres_process_extra_arguments_auto: []`
 
-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",
-]
-```
+- **add additional tuning parameters**: define your additional Postgres configuration parameters in `devture_postgres_postgres_process_extra_arguments_custom`. See `devture_postgres_postgres_process_extra_arguments_auto` defined in the Postgres role's [default configuration file](https://github.com/devture/com.devture.ansible.role.postgres/blob/main/defaults/main.yml) for inspiration

docs/maintenance-synapse.md

@@ -29,7 +29,9 @@ After deleting data, you may wish to run a [`FULL` Postgres `VACUUM`](./maintena
 
 [rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state) can be used to optimize some `_state` tables used by Synapse. If your server participates in large rooms this is the most effective way to reduce the size of your database.
 
-This tool should be safe to use (even when Synapse is running), but it's always a good idea to [make Postgres backups](./maintenance-postgres.md#backing-up-postgresql) first.
+**Note**: besides running the `rust-synapse-compress-state` tool manually, you can also enable its `synapse-auto-compressor` tool by [Setting up synapse-auto-compressor](configuring-playbook-synapse-auto-compressor.md). The automatic tool will run on a schedule every day and you won't have to compress state manually ever again.
+
+`rust-synapse-compress-state` 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:
 
@@ -70,8 +72,10 @@ You should then be able to browse the adminer database administration GUI at htt
 
 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.
 
+If you have enough compute resources (CPU & RAM), you can make Synapse better use of them by [enabling load-balancing with workers](configuring-playbook-synapse.md#load-balancing-with-workers).
+
 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).
+[Tuning your PostgreSQL database](maintenance-postgres.md#tuning-postgresql) could also improve Synapse performance. The playbook tunes the integrated Postgres database automatically, but based on your needs you may wish to adjust tuning variables manually. If you're using an [external Postgres database](configuring-playbook-external-postgres.md), you will aslo need to tune Postgres manually.
 
 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/maintenance-upgrading-services.md

@@ -10,8 +10,8 @@ To upgrade services:
 
 - take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of
 
-- download the upstream Ansible roles used by the playbook by running `make roles`
+- download the upstream Ansible roles used by the playbook by running `just roles`
 
-- re-run the [playbook setup](installing.md) and restart all serivces: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start`
+- re-run the [playbook setup](installing.md) and restart all services: `just setup-all`
 
 **Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).

docs/prerequisites.md

@@ -20,9 +20,11 @@ If your distro runs within an [LXC container](https://linuxcontainers.org/), you
 
 - 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.
 
+- the [passlib](https://passlib.readthedocs.io/en/stable/index.html) Python library installed on the computer you run Ansible. On most distros, you need to install some `python-passlib` or `py3-passlib` package, etc.
+
 - [`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.
 
-- [`make`](https://www.gnu.org/software/make/) for running `make roles`, etc. (see [`Makefile`](../Makefile)), although you can also run these commands manually (without `make`)
+- [`just`](https://github.com/casey/just) for running `just roles`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually
 
 - 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).
 

docs/registering-users.md

@@ -9,21 +9,29 @@ Table of contents:
 	- [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)
+	- [Adding/Removing Administrator privileges to an existing Synapse user](#addingremoving-administrator-privileges-to-an-existing-synapse-user)
 
 
 ## Registering users manually
 
 You can do it via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
 
+```sh
+just register-user <your-username> <your-password> <admin access: yes or no>
+
+# Example: `just register-user john secret-password yes`
 ```
+
+**or** by invoking `ansible-playbook` manually:
+
+```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user
 ```
 
 **or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
 
-```
-/usr/local/bin/matrix-synapse-register-user <your-username> <your-password> <admin access: 0 or 1>
+```sh
+/matrix/synapse/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
 ```
 
 **Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:<your-domain>` identifier.
@@ -58,13 +66,24 @@ 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
+## Adding/Removing Administrator privileges to an existing Synapse user
 
-The script `/usr/local/bin/matrix-change-user-admin-status` may be used to change a user's admin privileges.
-
-* log on to your server with ssh
-* execute with the username and 0/1 (0 = non-admin | 1 = admin)
+To change the admin privileges for a user, you need to run an SQL query like this against the `synapse` database:
 
+```sql
+UPDATE users SET admin=ADMIN_VALUE WHERE name = '@USER:DOMAIN'
 ```
-/usr/local/bin/matrix-change-user-admin-status <username> <0/1>
-```
+
+where:
+
+- `ADMIN_VALUE` being either `0` (regular user) or `1` (admin)
+- `USER` and `DOMAIN` pointing to a valid user on your server
+
+If you're using the integrated Postgres server and not an [external Postgres server](configuring-playbook-external-postgres.md), you can launch a Postgres into the `synapse` database by:
+
+- running `/matrix/postgres/bin/cli` - to launch [`psql`](https://www.postgresql.org/docs/current/app-psql.html)
+- running `\c synapse` - to change to the `synapse` database
+
+You can then proceed to run the query above.
+
+**Note**: directly modifying the raw data of Synapse (or any other software) could cause the software to break. You've been warned!

docs/self-building.md

@@ -32,6 +32,7 @@ Possibly outdated list of roles where self-building the Docker image is currentl
 - `matrix-bridge-mautrix-googlechat`
 - `matrix-bridge-mautrix-telegram`
 - `matrix-bridge-mautrix-signal`
+- `matrix-bridge-mautrix-gmessages`
 - `matrix-bridge-mautrix-whatsapp`
 - `matrix-bridge-mx-puppet-steam`
 - `matrix-bot-mjolnir`

docs/uninstalling.md

@@ -12,7 +12,7 @@
 
 ## Uninstalling using a script
 
-Installing places a `/usr/local/bin/matrix-remove-all` script on the server.
+Installing places a `/matrix/bin/remove-all` script on the server.
 
 You can run it to to have it uninstall things for you automatically (see below). **Use with caution!**
 
@@ -25,8 +25,6 @@ If you prefer to uninstall manually, run these commands (most are meant to be ex
 
 - 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 (`docker system prune -a`) or just delete them all (`docker rmi $(docker images -aq)`)
 
 - delete the Docker networks: `docker network rm matrix matrix-coturn` (might have been deleted already if you ran the `docker system prune` command)

docs/updating-users-passwords.md

@@ -1,6 +1,6 @@
 # Updating users passwords
 
-## Option 1 (if you are using the default matrix-postgres container):
+## Option 1 (if you are using the integrated Postgres database):
 
 You can reset a user's password via the Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
 
@@ -36,7 +36,7 @@ Use the Synapse User Admin API as described here: https://github.com/matrix-org/
 
 This requires an [access token](obtaining-access-tokens.md) 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 learn how to switch it now by reading about it in [Adding/Removing Administrator privileges to an existing Synapse user](registering-users.md#addingremoving-administrator-privileges-to-an-existing-synapse-user).
 
 ### Example:
 To set @user:domain.com's password to `correct_horse_battery_staple` you could use this curl command:

examples/apache/matrix-synapse.conf

@@ -37,6 +37,7 @@
 	# Keep some URIs free for different proxy/location
 	ProxyPassMatch ^/.well-known/matrix/client !
 	ProxyPassMatch ^/.well-known/matrix/server !
+	ProxyPassMatch ^/.well-known/matrix/support !
 	ProxyPassMatch ^/_matrix/identity !
 	ProxyPassMatch ^/_matrix/client/r0/user_directory/search !
 
@@ -46,11 +47,11 @@
 	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
@@ -64,6 +65,7 @@
 		Header always set Content-Type "application/json"
 		Header always set Access-Control-Allow-Origin "*"
 	</Location>
+
 	# Map /.well-known/matrix/server for server discovery
 	Alias /.well-known/matrix/server /matrix/static-files/.well-known/matrix/server
 	<Files "/matrix/static-files/.well-known/matrix/server">
@@ -72,6 +74,16 @@
 	<Location "/.well-known/matrix/server">
 		Header always set Content-Type "application/json"
 	</Location>
+
+	# Map /.well-known/matrix/support for support discovery
+	Alias /.well-known/matrix/support /matrix/static-files/.well-known/matrix/support
+	<Files "/matrix/static-files/.well-known/matrix/support">
+		Require all granted
+	</Files>
+	<Location "/.well-known/matrix/support">
+		Header always set Content-Type "application/json"
+	</Location>
+
 	<Directory /matrix/static-files/.well-known/matrix/>
 		AllowOverride All
 		# Apache 2.4:

examples/caddy2/Caddyfile

@@ -1,112 +1,10 @@
-(cors) {
-	@cors_preflight method OPTIONS
-
-	handle @cors_preflight {
-		header Access-Control-Allow-Origin "{args.0}"
-		header Access-Control-Allow-Methods "HEAD, GET, POST, PUT, PATCH, DELETE"
-		header Access-Control-Allow-Headers "Content-Type, Authorization"
-		header Access-Control-Max-Age "3600"
-	}
-}
-
-
-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
-  }
-  
-  # If you have other well-knowns already handled by your base domain, you can replace the above block by this one, along with the replacement suggested in the base domain
-  #handle @wellknown {
-  #  # .well-known is handled by base domain
-  #  reverse_proxy https://DOMAIN.tld {
-  #  header_up Host {http.reverse_proxy.upstream.hostport}
-  #}
+matrix.example.tld {
 
   handle {
         encode zstd gzip
 
-        reverse_proxy localhost:8008  {
+        reverse_proxy localhost:81  {
                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}
@@ -114,13 +12,12 @@ matrix.DOMAIN.tld {
   }
 }
 
-matrix.DOMAIN.tld:8448 {
+matrix.example.tld:8448 {
     handle {
         encode zstd gzip
 
-        reverse_proxy 127.0.0.1:8048 {
+        reverse_proxy 127.0.0.1:8449 {
                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}
@@ -128,142 +25,16 @@ matrix.DOMAIN.tld:8448 {
     }
 }
 
-element.DOMAIN.tld {
 
-      # creates letsencrypt certificate
-      # tls your@email.com
-
-      import cors https://*.DOMAIN.tld
-
-      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"
-                # If using integrations that add frames to Element, such as Dimension and its integrations running on the same domain, it can be a good idea to limit sources allowed to be rendered
-                # Content-Security-Policy frame-src https://*.DOMAIN.tld
-                # 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
-#
-#      import cors https://*.DOMAIN.tld
-#
-#      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"
-#          # Only allow same base domain to render this website in a frame; Can be removed if the client (Element for example) is hosted on another domain (clickjacking protection)
-#          Content-Security-Policy frame-ancestors https://*.DOMAIN.tld
-#          # 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
-#
-#  import cors https://*.DOMAIN.tld
-#
-#  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"
-
-#        # Only allow same base domain to render this website in a frame; Can be removed if the client (Element for example) is hosted on another domain
-#        Content-Security-Policy frame-ancestors https://*.DOMAIN.tld
-#
-#        # 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 {
+example.tld {
 # 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}
-#        }
-#    }
-#    # If you have other well-knowns already handled by your base domain, you can replace the above block by this one, along with the replacement suggested in the matrix subdomain
-#      # handle /.well-known/* {
-#	#	encode zstd gzip
-#	#	header Cache-Control max-age=14400
-#	#	header Content-Type application/json
-#	#	header Access-Control-Allow-Origin *
-#	#}
-#
-#    # Configration for the base domain goes here
-#   # handle {
-#   #    header -Server
-#   #     encode zstd gzip
-#   #    reverse_proxy localhost:4020
-#   # }
-#}
+    @wellknown {
+        path /.well-known/matrix/*
+    }
+
+    handle @wellknown {
+        reverse_proxy https://matrix.example.tld {
+            header_up Host {http.reverse_proxy.upstream.hostport}
+        }
+    }
+}

examples/caddy2/Caddyfile.deprecated

@@ -0,0 +1,269 @@
+(cors) {
+	@cors_preflight method OPTIONS
+
+	handle @cors_preflight {
+		header Access-Control-Allow-Origin "{args.0}"
+		header Access-Control-Allow-Methods "HEAD, GET, POST, PUT, PATCH, DELETE"
+		header Access-Control-Allow-Headers "Content-Type, Authorization"
+		header Access-Control-Max-Age "3600"
+	}
+}
+
+
+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
+  }
+  
+  # If you have other well-knowns already handled by your base domain, you can replace the above block by this one, along with the replacement suggested in the base domain
+  #handle @wellknown {
+  #  # .well-known is handled by base domain
+  #  reverse_proxy https://DOMAIN.tld {
+  #  header_up Host {http.reverse_proxy.upstream.hostport}
+  #}
+
+  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
+
+      import cors https://*.DOMAIN.tld
+
+      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"
+                # If using integrations that add frames to Element, such as Dimension and its integrations running on the same domain, it can be a good idea to limit sources allowed to be rendered
+                # Content-Security-Policy frame-src https://*.DOMAIN.tld
+                # 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
+#
+#      import cors https://*.DOMAIN.tld
+#
+#      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"
+#          # Only allow same base domain to render this website in a frame; Can be removed if the client (Element for example) is hosted on another domain (clickjacking protection)
+#          Content-Security-Policy frame-ancestors https://*.DOMAIN.tld
+#          # 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
+#
+#  import cors https://*.DOMAIN.tld
+#
+#  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"
+
+#        # Only allow same base domain to render this website in a frame; Can be removed if the client (Element for example) is hosted on another domain
+#        Content-Security-Policy frame-ancestors https://*.DOMAIN.tld
+#
+#        # 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}
+#        }
+#    }
+#    # If you have other well-knowns already handled by your base domain, you can replace the above block by this one, along with the replacement suggested in the matrix subdomain
+#      # handle /.well-known/* {
+#	#	encode zstd gzip
+#	#	header Cache-Control max-age=14400
+#	#	header Content-Type application/json
+#	#	header Access-Control-Allow-Origin *
+#	#}
+#
+#    # Configration for the base domain goes here
+#   # handle {
+#   #    header -Server
+#   #     encode zstd gzip
+#   #    reverse_proxy localhost:4020
+#   # }
+#}

examples/caddy2/README.md

@@ -1,12 +1,20 @@
-# Caddyfile
+# Caddy reverse-proxy fronting the playbook's integrated Traefik reverse-proxy
 
-This directory contains sample files that show you how to do reverse-proxying using Caddy2.
+This directory contains a sample config that shows you how to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver with your own [Caddy](https://caddyserver.com/) reverse-proxy.
 
-## 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 |
+## Prerequisite configuration
+
+To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
+
+
+## Using the Caddyfile
+
+You can either just use the [Caddyfile](Caddyfile) directly or append its content to your own Caddyfile.
+In both cases make sure to replace all the `example.tld` domains with your own domain.
+
+This example does  not include additional services like element, but you should be able copy the first block and replace the matrix subdomain with the additional services subdomain. I have not tested this though.
+
+# Caddyfile.deprecated
+
+This can be used as a [Caddy](https://caddyserver.com/) reverse-proxy without intermediary playbook managed reverse proxy. However, this setup is not supported by the playbook anymore. Instead [front the integrated reverse-proxy webserver with another reverse-proxy](../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) as described above.

examples/hosts

@@ -2,7 +2,9 @@
 # If you'd rather use a local IP here, make sure to set up `matrix_coturn_turn_external_ip_address`.
 #
 # To connect using a non-root user (and elevate to root with sudo later),
-# replace `ansible_ssh_user=root` with something like this: `ansible_ssh_user=username become=true become_user=root`
+# replace `ansible_ssh_user=root` with something like this: `ansible_ssh_user=username become=true become_user=root`.
+# If sudo requires a password, either add `become_password=PASSWORD_HERE` to the host line
+# or tell Ansible to ask you for the password interactively by adding a `--ask-become-pass` (`-K`) flag to all `ansible-playbook` (or `just`) commands.
 #
 # For improved Ansible performance, SSH pipelining is enabled by default in `ansible.cfg`.
 # If this causes SSH connection troubles, disable it by adding `ansible_ssh_pipelining=False`

examples/nginx/README.md

@@ -0,0 +1,17 @@
+# Nginx reverse-proxy fronting the playbook's integrated Traefik reverse-proxy
+
+This directory contains a sample config that shows you how to use the [nginx](https://nginx.org/) webserver to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver with another reverse-proxy.
+
+
+## Prerequisite configuration
+
+To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
+
+
+## Using the nginx configuration
+
+Copy the [matrix.conf](matrix.conf) file to your nginx server's filesystem, modify it to your needs and include it in your nginx configuration (e.g. `include /path/to/matrix.conf;`).
+
+This configuration **disables SSL certificate retrieval**, so you will **need to obtain SSL certificates manually** (e.g. by using [certbot](https://certbot.eff.org/)) and set the appropriate path in `matrix.conf`. In the example nginx configuration, a single certificate is used for all subdomains (`matrix.DOMAIN`, `element.DOMAIN`, etc.). For your setup, may wish to change this and use separate `server` blocks and separate certificate files for each host.
+
+Also note that your copy of the `matrix.conf` file has to be adapted to whatever services you are using. For example, remove `element.domain.com` from the `server_name` list if you don't use [Element](../../docs/configuring-playbook-client-element.md) web client or add `dimension.domain.com` to it if you do use the [Dimension](../../docs/configuring-playbook-dimension.md) integration manager.

examples/nginx/matrix.conf

@@ -0,0 +1,96 @@
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+
+    # TODO: add/remove services and their subdomains if you use/don't use them
+    # this example is using hosting something on the base domain and an element web client, so example.com and element.example.com are listed in addition to matrix.example.com
+    # if you don't use those, you can remove them
+    # if you use e.g. dimension on dimension.example.com, add dimension.example.com to the server_name list
+    server_name example.com matrix.example.com element.example.com;
+
+    location / {
+        # note: do not add a path (even a single /) after the port in `proxy_pass`,
+        # otherwise, nginx will canonicalise the URI and cause signature verification
+        # errors.
+        proxy_pass http://localhost:81;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+
+        access_log /var/log/nginx/matrix.access.log;
+        error_log /var/log/nginx/matrix.error.log;
+
+        # Nginx by default only allows file uploads up to 1M in size
+        # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
+        client_max_body_size 50M;
+    }
+
+    # TODO: adapt the path to your ssl certificate for the domains listed on server_name
+    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
+    # TODO: adapt the path to your ssl certificate for the domains listed on server_name
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
+    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
+}
+
+# settings for matrix federation
+server {
+    # For the federation port
+    listen 8448 ssl http2 default_server;
+    listen [::]:8448 ssl http2 default_server;
+
+    server_name matrix.example.com;
+
+    location / {
+        proxy_pass http://localhost:8449;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Host $host;
+
+        access_log /var/log/nginx/matrix.access.log;
+        error_log /var/log/nginx/matrix.error.log;
+
+        # Nginx by default only allows file uploads up to 1M in size
+        # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
+        client_max_body_size 50M;
+    }
+    # TODO: adapt the path to your ssl certificate for the domains listed on server_name
+    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
+    # TODO: adapt the path to your ssl certificate for the domains listed on server_name
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
+    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
+}
+
+# ensure using https
+# TODO: remove server blocks that you don't use / add server blocks for domains you do use
+server {
+    if ($host = example.com) {
+        return 301 https://$host$request_uri;
+    } # managed by Certbot
+
+    server_name example.com;
+    listen 80;
+    return 404; # managed by Certbot
+}
+
+server {
+    if ($host = matrix.example.com) {
+        return 301 https://$host$request_uri;
+    } # managed by Certbot
+
+    server_name matrix.example.com;
+    listen 80;
+    return 404; # managed by Certbot
+}
+
+server {
+    if ($host = element.example.com) {
+        return 301 https://$host$request_uri;
+    } # managed by Certbot
+
+    server_name element.example.com;
+    listen 80;
+    return 404; # managed by Certbot
+}

examples/vars.yml

@@ -21,6 +21,11 @@ matrix_homeserver_implementation: synapse
 # You can put any string here, but generating a strong one is preferred (e.g. `pwgen -s 64 1`).
 matrix_homeserver_generic_secret_key: ''
 
+# By default, the playbook manages its own Traefik (https://doc.traefik.io/traefik/) reverse-proxy server.
+# It will retrieve SSL certificates for you on-demand and forward requests to all other components.
+# For alternatives, see `docs/configuring-playbook-own-webserver.md`.
+matrix_playbook_reverse_proxy_type: playbook-managed-traefik
+
 # This is something which is provided to Let's Encrypt when retrieving SSL certificates for domains.
 #
 # In case SSL renewal fails at some point, you'll also get an email notification there.
@@ -29,10 +34,26 @@ matrix_homeserver_generic_secret_key: ''
 # you won't be required to define this variable (see `docs/configuring-playbook-ssl-certificates.md`).
 #
 # Example value: someone@example.com
-matrix_ssl_lets_encrypt_support_email: ''
+devture_traefik_config_certificatesResolvers_acme_email: ''
 
 # A Postgres password to use for the superuser Postgres user (called `matrix` by default).
 #
 # The playbook creates additional Postgres users and databases (one for each enabled service)
 # using this superuser account.
-matrix_postgres_connection_password: ''
+devture_postgres_connection_password: ''
+
+# By default, we configure Coturn's external IP address using the value specified for `ansible_host` in your `inventory/hosts` file.
+# If this value is an external IP address, you can skip this section.
+#
+# If `ansible_host` is not the server's external IP address, you have 2 choices:
+# 1. Uncomment the line below, to allow IP address auto-detection to happen (more on this below)
+# 2. Uncomment and adjust the line below to specify an IP address manually
+#
+# By default, auto-detection will be attempted using the `https://ifconfig.co/json` API.
+# Default values for this are specified in `matrix_coturn_turn_external_ip_address_auto_detection_*` variables in the Coturn role
+# (see `roles/custom/matrix-coturn/defaults/main.yml`).
+#
+# If your server has multiple IP addresses, you may define them in another variable which allows a list of addresses.
+# Example: `matrix_coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']`
+#
+# matrix_coturn_turn_external_ip_address: ''

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1683777345,
+        "narHash": "sha256-V2p/A4RpEGqEZussOnHYMU6XglxBJGCODdzoyvcwig8=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "635a306fc8ede2e34cb3dd0d6d0a5d49362150ed",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,20 @@
+{
+  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
+
+  outputs = { self, nixpkgs, ... }:
+    let
+      pkgs = import nixpkgs { system = "x86_64-linux"; };
+    in
+    {
+      devShell.x86_64-linux = pkgs.mkShell {
+        buildInputs = with pkgs; [
+          just
+          python311Packages.ansible-core
+          python311Packages.ansible-lint
+          python311Packages.passlib
+        ];
+        LC_ALL = "C.UTF-8";
+        LC_CTYPE = "C.UTF-8";
+      };
+    };
+}

group_vars/jitsi_jvb_servers

@@ -0,0 +1,11 @@
+jitsi_architecture: "{{ matrix_architecture }}"
+jitsi_hostname: "{{ matrix_server_fqn_jitsi }}"
+jitsi_uid: "{{ matrix_user_uid }}"
+jitsi_gid: "{{ matrix_user_gid }}"
+
+devture_systemd_service_manager_services_list_auto: |
+  {{
+    ([{'name': (jitsi_identifier + '-jvb.service'), 'priority': 4100, 'groups': ['matrix', 'jitsi', 'jitsi-jvb']}] if jitsi_enabled else [])
+  }}
+
+matrix_playbook_docker_installation_enabled: true

inventory/scripts/jitsi-generate-passwords.sh

@@ -1,24 +0,0 @@
-#!/usr/bin/env bash
-# This is a bash script for generating strong passwords for the Jitsi role in this ansible project:
-# https://github.com/spantaleev/matrix-docker-ansible-deploy
-
-function generatePassword() {
-    openssl rand -hex 16
-}
-
-echo "# If this script fails, it's likely because you don't have the openssl tool installed."
-echo "# Install it before using this script, or simply create your own passwords manually."
-
-echo ""
-
-JICOFO_AUTH_PASSWORD=$(generatePassword)
-JVB_AUTH_PASSWORD=$(generatePassword)
-JIBRI_RECORDER_PASSWORD=$(generatePassword)
-JIBRI_XMPP_PASSWORD=$(generatePassword)
-
-echo "# Paste these variables into your inventory/host_vars/matrix.DOMAIN/vars.yml file:"
-echo ""
-echo "matrix_jitsi_jicofo_auth_password: $JICOFO_AUTH_PASSWORD"
-echo "matrix_jitsi_jvb_auth_password: $JVB_AUTH_PASSWORD"
-echo "matrix_jitsi_jibri_recorder_password: $JIBRI_RECORDER_PASSWORD"
-echo "matrix_jitsi_jibri_xmpp_password: $JIBRI_XMPP_PASSWORD"

jitsi_jvb.yml

@@ -0,0 +1,35 @@
+---
+- name: "Set up additional Jitsi JVB servers"
+  hosts: "jitsi_jvb_servers"
+  become: true
+
+  roles:
+    - role: galaxy/com.devture.ansible.role.playbook_help
+    - role: galaxy/com.devture.ansible.role.systemd_docker_base
+
+    - when: matrix_playbook_docker_installation_enabled | bool
+      role: galaxy/geerlingguy.docker
+      vars:
+        docker_install_compose: false
+      tags:
+        - setup-docker
+        - setup-all
+        - setup-additional-jitsi-jvb
+        - install-docker
+        - install-all
+
+    - when: devture_docker_sdk_for_python_installation_enabled | bool
+      role: galaxy/com.devture.ansible.role.docker_sdk_for_python
+      tags:
+        - setup-docker
+        - setup-all
+        - setup-additional-jitsi-jvb
+        - install-docker
+        - install-all
+
+    - custom/matrix-base
+    - galaxy/jitsi
+    - custom/matrix-common-after
+
+    - when: devture_systemd_service_manager_enabled | bool
+      role: galaxy/com.devture.ansible.role.systemd_service_manager

justfile

@@ -0,0 +1,60 @@
+# Shows help
+default:
+    @just --list --justfile {{ justfile() }}
+
+# Pulls external Ansible roles
+roles:
+    #!/usr/bin/env sh
+    if [ -x "$(command -v agru)" ]; then
+    	agru
+    else
+    	rm -rf roles/galaxy
+    	ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force
+    fi
+
+# Updates requirements.yml if there are any new tags available. Requires agru
+update:
+    @agru -u
+
+# Runs ansible-lint against all roles in the playbook
+lint:
+    ansible-lint
+
+# Runs the playbook with --tags=install-all,ensure-matrix-users-created,start and optional arguments
+install-all *extra_args: (run-tags "install-all,ensure-matrix-users-created,start" extra_args)
+
+# Runs installation tasks for a single service
+install-service service *extra_args:
+    just --justfile {{ justfile() }} run \
+    --tags=install-{{ service }},start-group \
+    --extra-vars=group={{ service }} \
+    --extra-vars=devture_systemd_service_manager_service_restart_mode=one-by-one {{ extra_args }}
+
+# Runs the playbook with --tags=setup-all,ensure-matrix-users-created,start and optional arguments
+setup-all *extra_args: (run-tags "setup-all,ensure-matrix-users-created,start" extra_args)
+
+# Runs the playbook with the given list of arguments
+run +extra_args:
+    ansible-playbook -i inventory/hosts setup.yml {{ extra_args }}
+
+# Runs the playbook with the given list of comma-separated tags and optional arguments
+run-tags tags *extra_args:
+    just --justfile {{ justfile() }} run --tags={{ tags }} {{ extra_args }}
+
+# Runs the playbook in user-registration mode
+register-user username password admin_yes_or_no *extra_args:
+    ansible-playbook -i inventory/hosts setup.yml --tags=register-user --extra-vars="username={{ username }} password={{ password }} admin={{ admin_yes_or_no }}" {{ extra_args }}
+
+# Starts all services
+start-all *extra_args: (run-tags "start-all" extra_args)
+
+# Starts a specific service group
+start-group group *extra_args:
+    @just --justfile {{ justfile() }} run-tags start-group --extra-vars="group={{ group }}" {{ extra_args }}
+
+# Stops all services
+stop-all *extra_args: (run-tags "stop-all" extra_args)
+
+# Stops a specific service group
+stop-group group *extra_args:
+    @just --justfile {{ justfile() }} run-tags stop-group --extra-vars="group={{ group }}" {{ extra_args }}

playbooks/jitsi_jvb.yml

@@ -1,12 +0,0 @@
----
-- name: "Set up additional Jitsi JVB servers"
-  hosts: "jitsi_jvb_servers"
-  become: true
-
-  roles:
-    - role: galaxy/com.devture.ansible.role.playbook_help
-    - role: galaxy/com.devture.ansible.role.systemd_docker_base
-
-    - custom/matrix-base
-    - custom/matrix-jitsi
-    - custom/matrix-common-after

playbooks/matrix.yml

@@ -1,113 +0,0 @@
----
-- name: "Set up a Matrix server"
-  hosts: "{{ target if target is defined else 'matrix_servers' }}"
-  become: true
-
-  roles:
-    # Most of the roles below are not distributed with the playbook, but downloaded separately using `ansible-galaxy` via the `make roles` command (see `Makefile`).
-    - role: galaxy/com.devture.ansible.role.playbook_help
-
-    - role: galaxy/com.devture.ansible.role.systemd_docker_base
-
-    - role: custom/matrix_playbook_migration
-
-    - when: matrix_playbook_docker_installation_enabled | bool
-      role: galaxy/geerlingguy.docker
-      vars:
-        docker_install_compose: false
-      tags:
-        - setup-docker
-        - setup-all
-
-    - when: devture_docker_sdk_for_python_installation_enabled | bool
-      role: galaxy/com.devture.ansible.role.docker_sdk_for_python
-      tags:
-        - setup-docker
-        - setup-all
-
-    - when: devture_timesync_installation_enabled | bool
-      role: galaxy/com.devture.ansible.role.timesync
-      tags:
-        - setup-timesync
-        - setup-all
-
-    - custom/matrix-base
-    - custom/matrix-dynamic-dns
-    - custom/matrix-mailer
-    - custom/matrix-postgres
-    - custom/matrix-redis
-    - custom/matrix-corporal
-    - custom/matrix-bridge-appservice-discord
-    - custom/matrix-bridge-appservice-slack
-    - custom/matrix-bridge-appservice-webhooks
-    - custom/matrix-bridge-appservice-irc
-    - custom/matrix-bridge-appservice-kakaotalk
-    - custom/matrix-bridge-beeper-linkedin
-    - custom/matrix-bridge-go-skype-bridge
-    - custom/matrix-bridge-mautrix-facebook
-    - custom/matrix-bridge-mautrix-twitter
-    - custom/matrix-bridge-mautrix-hangouts
-    - custom/matrix-bridge-mautrix-googlechat
-    - custom/matrix-bridge-mautrix-instagram
-    - custom/matrix-bridge-mautrix-signal
-    - custom/matrix-bridge-mautrix-telegram
-    - custom/matrix-bridge-mautrix-whatsapp
-    - custom/matrix-bridge-mautrix-discord
-    - custom/matrix-bridge-mx-puppet-discord
-    - custom/matrix-bridge-mx-puppet-groupme
-    - custom/matrix-bridge-mx-puppet-steam
-    - custom/matrix-bridge-mx-puppet-slack
-    - custom/matrix-bridge-mx-puppet-twitter
-    - custom/matrix-bridge-mx-puppet-instagram
-    - custom/matrix-bridge-sms
-    - custom/matrix-bridge-heisenbridge
-    - custom/matrix-bridge-hookshot
-    - custom/matrix-bot-matrix-reminder-bot
-    - custom/matrix-bot-matrix-registration-bot
-    - custom/matrix-bot-maubot
-    - custom/matrix-bot-buscarron
-    - custom/matrix-bot-honoroit
-    - custom/matrix-bot-postmoogle
-    - custom/matrix-bot-go-neb
-    - custom/matrix-bot-mjolnir
-    - custom/matrix-cactus-comments
-    - custom/matrix-synapse
-    - custom/matrix-synapse-reverse-proxy-companion
-    - custom/matrix-dendrite
-    - custom/matrix-conduit
-    - custom/matrix-synapse-admin
-    - custom/matrix-prometheus-node-exporter
-    - custom/matrix-prometheus-postgres-exporter
-    - custom/matrix-prometheus
-    - custom/matrix-grafana
-    - custom/matrix-registration
-    - custom/matrix-client-element
-    - custom/matrix-client-hydrogen
-    - custom/matrix-client-cinny
-    - custom/matrix-jitsi
-    - custom/matrix-ldap-registration-proxy
-    - custom/matrix-ma1sd
-    - custom/matrix-dimension
-    - custom/matrix-etherpad
-    - custom/matrix-email2matrix
-    - custom/matrix-sygnal
-    - custom/matrix-ntfy
-    - custom/matrix-nginx-proxy
-    - custom/matrix-coturn
-    - custom/matrix-aux
-    - custom/matrix-postgres-backup
-    - custom/matrix-backup-borg
-    - custom/matrix-user-creator
-    - custom/matrix-common-after
-
-    - when: devture_systemd_service_manager_enabled | bool
-      role: galaxy/com.devture.ansible.role.systemd_service_manager
-
-    # This is pretty much last, because we want it to better serve as a "last known good configuration".
-    # See: https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2217#issuecomment-1301487601
-    - when: devture_playbook_state_preserver_enabled | bool
-      role: galaxy/com.devture.ansible.role.playbook_state_preserver
-      tags:
-        - setup-all
-
-    - role: galaxy/com.devture.ansible.role.playbook_runtime_messages