meta: move inventory structure to be more usable

Fix #2720.

.github/workflows/matrix.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Check out
         uses: actions/checkout@v4
       - name: Run yamllint
-        uses: frenck/action-yamllint@v1.4.2
+        uses: frenck/action-yamllint@v1.5.0
   ansible-lint:
     name: ansible-lint
     runs-on: ubuntu-latest

.gitignore

@@ -3,7 +3,7 @@
 .DS_Store
 .python-version
 .idea/
-flake.lock
+.direnv/
 
 # ignore roles pulled by ansible-galaxy
 /roles/galaxy/*

CHANGELOG.md

@@ -1,3 +1,353 @@
+# 2024-03-26
+
+## (Backward Compatibility Break) The playbook now defaults to KeyDB, instead of Redis
+
+**TLDR**: if the playbook used installed Redis as a dependency for you before, it will now replace it with [KeyDB](https://docs.keydb.dev/) (a drop-in alternative) due to [Redis having changed its license](https://redis.com/blog/redis-adopts-dual-source-available-licensing/).
+
+Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook now uses [KeyDB](https://docs.keydb.dev/) (a drop-in alternative for Redis), instead of [Redis](https://redis.io/).
+
+The playbook used to install Redis (and now installs KeyDB in its place) if services have a need for it ([enabling worker support for Synapse](docs/configuring-playbook-synapse.md#load-balancing-with-workers), [enabling Hookshot encryption](docs/configuring-playbook-bridge-hookshot.md#end-to-bridge-encryption), etc.) or if you explicitly enabled the service (`redis_enabled: true` or `keydb_enabled: true`).
+
+This change is provoked by the fact that [Redis is now "source available"](https://redis.com/blog/redis-adopts-dual-source-available-licensing/). According to the Limitations of [the new license](https://redis.com/legal/rsalv2-agreement/) (as best as we understand them, given that we're not lawyers), using Redis in the playbook (even in a commercial FOSS service like [etke.cc](https://etke.cc/)) does not violate the new Redis license. That said, we'd rather neither risk it, nor endorse shady licenses and products that pretend to be free-software. Another high-quality alternative to Redis seems to be [Dragonfly](https://www.dragonflydb.io/), but the [Dragonfly license](https://github.com/dragonflydb/dragonfly?tab=License-1-ov-file#readme) is no better than Redis's.
+
+Next time your run the playbook (via the `setup-all` tag), **Redis will be automatically uninstalled and replaced with KeyDB**. Some Synapse downtime may occur while the switch happens.
+
+Users on `arm32` should be aware that there's **neither a prebuilt `arm32` container image for KeyDB**, nor the KeyDB role supports self-building yet. Users on this architecture likely don't run Synapse with workers, etc., so they're likely in no need of KeyDB (or Redis). If Redis is necessary in an `arm32` deployment, disabling KeyDB and making the playbook fall back to Redis is possible (see below).
+
+**The playbook still supports Redis** and you can keep using Redis (for now) if you'd like, by adding this additional configuration to your `vars.yml` file:
+
+```yml
+# Explicitly disable KeyDB, which will auto-enable Redis
+# if the playbook requires it as a dependency for its operation.
+keydb_enabled: false
+```
+
+
+
+# 2024-03-24
+
+## Initial work on IPv6 support
+
+Thanks to [Tilo Spannagel](https://github.com/tilosp), the playbook can now enable IPv6 for container networks for various components (roles) via [the `devture_systemd_docker_base_ipv6_enabled` variable](https://github.com/devture/com.devture.ansible.role.systemd_docker_base/blob/c11a526bb8e318b42eb52055056377bb31154f13/defaults/main.yml#L14-L31).
+
+It should be noted that:
+
+- Matrix roles (`roles/custom/matrix-*`) respect this variable, but external roles (those defined in `requirements.yml` and installed via `just roles`) do not respect it yet. Additional work is necessary
+- changing the variable subsequently may not change existing container networks. Refer to [these instructions](https://github.com/devture/com.devture.ansible.role.systemd_docker_base/blob/c11a526bb8e318b42eb52055056377bb31154f13/defaults/main.yml#L26-L30)
+- this is all very new and untested
+
+## Pantalaimon support
+
+Thanks to [Julian Foad](https://matrix.to/#/@julian:foad.me.uk), the playbook can now install the [Pantalaimon](https://github.com/matrix-org/pantalaimon) E2EE aware proxy daemon for you. It's already possible to integrate it with [Draupnir](docs/configuring-playbook-bot-draupnir.md) to allow it to work in E2EE rooms - see our Draupnir docs for details.
+
+See our [Setting up Pantalaimon](docs/configuring-playbook-pantalaimon.md) documentation to get started.
+
+
+# 2024-03-05
+
+## Support for Draupnir-for-all
+
+Thanks to [FSG-Cat](https://github.com/FSG-Cat), the playbook can now install [Draupnir for all](./docs/configuring-playbook-appservice-draupnir-for-all.md) (aka multi-instance Draupnir running in appservice mode).
+
+This is an alternative to [running Draupnir in bot mode](./docs/configuring-playbook-bot-draupnir.md), which is still supported by the playbook.
+
+The documentation page for [Draupnir for all](./docs/configuring-playbook-appservice-draupnir-for-all.md) contains more information on how to install it.
+
+
+# 2024-02-19
+
+## Support for bridging to Facebook/Messenger via the new mautrix-meta bridge
+
+The [mautrix-facebook](./docs/configuring-playbook-bridge-mautrix-facebook.md) and [mautrix-instagram](./docs/configuring-playbook-bridge-mautrix-instagram.md) bridges are being [superseded by a new bridge](https://github.com/mautrix/facebook/issues/332) - the [mautrix-meta](https://github.com/mautrix/meta) bridge.
+
+The playbook now supports the new mautrix-meta bridge - a single bridge, which can run in different modes and bridge to Messenger (via [Facebook](https://facebook.com/), Facebook over [Tor](https://www.torproject.org/) or via [Messenger](https://messenger.com/)) and [Instagram](https://instagram.com/). The playbook makes this bridge available via 2 separate Ansible roles, allowing you to easily run 2 instances of mautrix-meta, for bridging to both services at the same time.
+
+If you're using mautrix-facebook or mautrix-instagram right now, **you can still continue using the old bridges, but may wish to change to the new bridge implementations**. See:
+
+- [Setting up Instagram bridging via Mautrix Meta](docs/configuring-playbook-bridge-mautrix-meta-instagram.md)
+
+- [Setting up Messenger bridging via Mautrix Meta](docs/configuring-playbook-bridge-mautrix-meta-messenger.md)
+
+The documentation pages contain more information on how to migrate.
+
+
+# 2024-02-14
+
+## Much larger Synapse caches and cache auto-tuning enabled by default
+
+Thanks to [FSG-Cat](https://github.com/FSG-Cat), the playbook now uses much larger caches and enables Synapse's [cache auto-tuning functionality](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#caches-and-associated-values).
+This work and the default values used by the playbook are inspired by [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/deployment/synapse.html).
+
+The playbook has always used a very conservative cache factor (`matrix_synapse_caches_global_factor`) value of `0.5`, which may be OK for small and underactive deployments, but is not ideal for larger servers. Paradoxically, a small global cache factor value [does not necessarily decrease RAM usage as a whole](https://github.com/matrix-org/synapse/issues/3939).
+
+The playbook now uses **a 20x larger cache factor** (currently `10`), adjusts a few other cache-related variables, and **enables cache auto-tuning** via the following variables:
+
+- `matrix_synapse_cache_autotuning_max_cache_memory_usage` - defaults to 1/8 of total RAM with a cap of 2GB; values are specified in bytes
+- `matrix_synapse_cache_autotuning_target_cache_memory_usage` - defaults to 1/16 of total RAM with a cap of 1GB; values are specified in bytes
+- `matrix_synapse_cache_autotuning_min_cache_ttl` - defaults to `30s`
+
+These values should be good defaults for most servers, but may change over time as we experiment further.
+
+Refer to our new [Tuning caches and cache autotuning](docs/maintenance-synapse.md#tuning-caches-and-cache-autotuning) documentation section for more details.
+
+
+# 2024-01-31
+
+## (Backward-compatibility break) Minor changes necessary for some people serving a static website at the base domain
+
+This only affects people who are [Serving a static website at the base domain](./docs/configuring-playbook-base-domain-serving.md#serving-a-static-website-at-the-base-domain), but not managing its `index.html` through the playbook.
+
+That is, for people who have `matrix_static_files_file_index_html_enabled: false` in their `vars.yml` configuration, the playbook has a new default behavior. Since the playbook is not managing the `index.html` file, it will default to a more sensible way of handling the base domain  - redirecting `https://DOMAIN/` to `https://matrix.DOMAIN/`, instead of serving a 404 page.
+
+If you are managing your static website by yourself (by dropping files into `/matrix/static-files/public` somehow), then you probably don't wish for such redirection to happen. You can disable it by adding `matrix_static_files_container_labels_base_domain_root_path_redirection_enabled: false` to your `vars.yml` configuration file.
+
+
+# 2024-01-20
+
+## Support for more efficient (specialized) Synapse workers
+
+Thanks to [Charles Wright](https://github.com/cvwright) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook has [received support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100) for load-balancing the Synapse workload via [specialized workers](./docs/configuring-playbook-synapse.md#specialized-workers) which are supposed to work better than our old [generic workers](./docs/configuring-playbook-synapse.md#generic-workers) implementation.
+
+For now, playbook defaults remain unchanged and the `one-of-each` [workers preset](./docs/configuring-playbook-synapse.md#worker-presets) continues being the default. However, the default may change in the future. If you'd like to remain on this preset even if/when the defaults change, consider explicitly adding `matrix_synapse_workers_preset: one-of-each` to your `vars.yml` configuration.
+
+Our specialized workers setup is based on recommendations found in [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html). What's special about our new setup is that we try to parse information out of the request (who the user is; which room is being operated on) and try to forward similar requests to the same worker. As an example, this means that once a worker caches some room information, subsequent requests for the same room will be routed to the same worker (which supposedly still has the room's state cached).
+
+To get started, refer to our [Specialized workers](./docs/configuring-playbook-synapse.md#specialized-workers) documentation section.
+
+
+# 2024-01-17
+
+## Switching to Element's AGPLv3-licensed Synapse release
+
+A few months ago, the [Element](https://element.io/) company has [announced](https://element.io/blog/element-to-adopt-agplv3/) that their work on the Synapse homeserver would no longer be available under the permissive [Apache-2.0 license](https://www.apache.org/licenses/LICENSE-2.0), but only under:
+
+- the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) free-software license - the same license that this Ansible playbook has always used
+- a proprietary license, for those wishing for Element to [sell them an exception](https://gnu.org/philosophy/selling-exceptions.html) to the AGPLv3 license
+
+You can also learn more in [this post](https://matrix.org/blog/2023/11/06/future-of-synapse-dendrite/) by the Matrix Foundation.
+
+The change has [already happened](https://element.io/blog/synapse-now-lives-at-github-com-element-hq-synapse/) and the first Synapse release under the new license is here: [v1.99.0](https://github.com/element-hq/synapse/releases/tag/v1.99.0).
+
+There is no up-to-date alternative Synapse fork right now and this free-software (AGPLv3-licensed) playbook is definitely not against free-software licenses, so we are now switching to the Element-maintained Synapse release.
+
+**What does this mean to you?**
+
+For most home users, it doesn't mean anything. Your installation will continue working as it should and you don't need to do anything.
+
+For people building commercial products on top of Synapse, they may have to either buy a license exception from Element (from what we hear, the fee depends on the number of monthly-active users on your instance) or they may need to release all related code as free-software (which is what we've been doing at [etke.cc](https://etke.cc/) ([here](https://gitlab.com/etke.cc)) all along).
+
+We're no lawyers and this changelog entry does not aim to give you the best legal advice, so please research on your own!
+
+If you'd like to continue using the old Apache-2.0-licensed Synapse (for a while longer anyway), the playbook makes it possible by intruducing a new Ansible variable. You can do it like this:
+
+```yaml
+# Switch the organization that Synapse container images (or source code for self-building) are pulled from.
+# Note: the new default value is `element-hq/synapse`.
+matrix_synapse_github_org_and_repo: matrix-org/synapse
+
+# Pin the Synapse version to the last one (v1.98.0) released by the Matrix Foundation
+# under the old permissive Apache-2.0 license.
+matrix_synapse_version: v1.98.0
+```
+
+Notes:
+
+- if you had already upgraded Synapse to `v1.99.0` by running this playbook, you will still be able to downgrade to `v1.98.0`, because both releases use the same database schema version (`SCHEMA_COMPAT_VERSION = 83` - see [here for v1.98.0](https://github.com/element-hq/synapse/blob/v1.98.0/synapse/storage/schema/__init__.py#L131-L134) and [here for v1.99.0](https://github.com/element-hq/synapse/blob/v1.99.0/synapse/storage/schema/__init__.py#L137-L140)). More details on Synapse's database schema are available [here](https://element-hq.github.io/synapse/develop/development/database_schema.html). It appears that there are no new database migrations introduced in `v1.99.0`, so going back to the older release is possible. This is not guaranteed to hold true for future Synapse releases, so if you're seeing this early-enough, consider pinning the version and organization before re-running the playbook and getting upgraded to the latest version
+
+- running an outdated homeserver exposes you to security issues and incompatibilities. Only consider doing this as a short-term solution.
+
+# 2024-01-16
+
+## `Draupnir` has been relicensed to AFL-3.0
+
+As of [#204](https://github.com/the-draupnir-project/Draupnir/pull/204) Draupnir changed its licence to AFL-3.0 from the CSL licence. This change affects playbook users who could not run Draupnir under the old license restrictions. The new license is considerably less restrictive and is OSI approved. Draupnir version v1.86.0 and later are covered by this license change.
+
+# 2024-01-15
+
+## Goodbye, `matrix-nginx-proxy` 🪦
+
+**TLDR**: All traces of the `matrix-nginx-proxy` reverse-proxy component are now gone. This brought about many other internal changes (and security improvements), so setups may need minor adjustments or suffer some (temporary) breakage. People who have been on the Traefik-native setup may upgrade without much issues. Those running their own Traefik instance may need minor changes. People who have been postponing the migration away from `matrix-nginx-proxy` (for more than a year already!) will now finally need to do something about it.
+
+### Backstory on `matrix-nginx-proxy`
+
+We gather here today to celebrate the loss of a once-beloved component in our stack - `matrix-nginx-proxy`. It's been our [nginx](https://nginx.org/)-based reverse-proxy of choice since the [first commit](https://github.com/spantaleev/matrix-docker-ansible-deploy/tree/87f5883f2455fb115457b65f267f17de305c053c) of this playbook, 7 years ago.
+
+For 6 years, `matrix-nginx-proxy` has been the front-most reverse-proxy in our setup (doing SSL termination, etc.). After [transitioning to Traefik last year](#traefik-is-the-default-reverse-proxy-now), `matrix-nginx-proxy` took a step back. Nevertheless, since it was so ingrained into the playbook, it still remained in use - even if only internally. Despite our warnings of its imminent death, many of you have indubitably continued to use it instead of Traefik. Its suffering continued for too long, because it served many different purposes and massive effort was required to transition them to others.
+
+To us, `matrix-nginx-proxy` was:
+
+- an [nginx](https://nginx.org/)-based reverse-proxy
+- an Ansible role organizing the work of [certbot](https://certbot.eff.org/) - retrieving free [Let's Encrypt](https://letsencrypt.org/) SSL certificates for `matrix-nginx-proxy` and for the [Coturn TURN server](./docs/configuring-playbook-turn.md)
+- a central component for reverse-proxying to the [long list of services](./docs/configuring-playbook.md) supported by the playbook. As such, it became a dependency that all these services had to inject themselves into during runtime
+- an intermediary through which addons (bridges, bots) communicated with the homeserver. Going through an intermediary (instead of directly talking to the homeserver) is useful when certain components (like [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) or [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md)) are enabled, because it lets these services "steal routes" from the homeserver
+- a webserver for serving the `/.well-known/matrix` static files (generated by the `matrix-base` role until now)
+- a webserver [serving your base domain](./docs/configuring-playbook-base-domain-serving.md) (and also generating the `index.html` page for it)
+- a central component providing global [HTTP Basic Auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) password-protection for all `/metrics` endpoints when metrics were exposed publicly for consumption from a remote Prometheus server
+
+Talk about a jack of all trades! The [UNIX philosophy](https://en.wikipedia.org/wiki/Unix_philosophy) (and Docker container philosophy) of "do one thing and do it well" had been severely violated for too long.
+
+On a related note, we also had a large chain of reverse-proxies in the mix.
+In the worst case, it was something like this: (Traefik -> `matrix-nginx-proxy:8080` -> `matrix-nginx-proxy:12080` -> `matrix-synapse-reverse-proxy-companion:8008` -> `matrix-synapse:8008`).
+
+Due to complexity and the playbook's flexibility (trying to accommodate a mix of tens of components), many layers of indirection were necessary. We do like reverse-proxies, but.. not quite enough to enjoy going through a chain of ~4 of them before reaching the target service.
+
+After **a ton of work** in the last weeks (200+ commits, which changed 467 files - 8684 insertions and 8913 deletions), **we're finally saying goodbye** to `matrix-nginx-proxy`.
+
+
+### Going Traefik-native and cutting out all middlemen
+
+In our new setup, you'll see the bare minimum number of reverse-proxies.
+
+In most cases, there's only Traefik and all services being registered directly with it. When [Synapse workers](./docs/configuring-playbook-synapse.md#load-balancing-with-workers) are enabled, `matrix-synapse-reverse-proxy-companion` remains as an extra reverse-proxy that requests go through (for load-balancing to the correct Synapse worker), but in all other cases services are exposed directly.
+
+This reduces "network" hops (improving performance) and also decreases the number of components (containers).
+Each Ansible role in our setup is now independent and doesn't need to interact with other roles during runtime.
+
+
+### Traefik now has an extra job
+
+Previously, **Traefik had a single purpose** - being the main reverse-proxy. It was either front-most (terminating SSL, etc.) or you were [fronting Traefik with your own other reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy). In any case - it had this central (yet decentralized) job.
+
+Now, **Traefik has one more role** - it serves as an intermediary which allows addon services (bridges, bots, etc.) to communicate with the homeserver. As mentioned above, such an intermediary service is not strictly necessary in all kinds of setups, but more complex setups (including [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) or [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md)) benefit from it.
+
+To perform this new role, Traefik now has a new internal [entrypoint](https://doc.traefik.io/traefik/routing/entrypoints/) called `matrix-internal-matrix-client-api`. All homeservers (Conduit, Dendrite, Synapse and even `matrix-synapse-reverse-proxy-companion`) and homeserver-related core services ([matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md), [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md) and potentially others) register their routes (using [container labels](https://docs.docker.com/config/labels-custom-metadata/)) not only on the public entrypoints (`web-secure`, `matrix-federation`), but also on this new internal entrypoint.
+
+Doing so, services can contact Traefik on this entrypoint's dedicated port (the URL defaults to `http://matrix-traefik:8008`) and reach the homeserver Client-Server API as they expect. Internally, Traefik takes care of the routing to the correct service.
+
+We've also considered keeping it simple and having services talk to the homeserver over the public internet (e.g. `https://matrix.DOMAIN`) thus reusing all existing Traefik routing labels. In this scenario, performance was incredibly poor (e.g. 70 rps, instead of 1400 rps) due to TLS and networking overhead. The need for fast internal communication (via the new internal non-TLS-enabled Traefik entrypoint) is definitely there. In our benchmarks, Traefik even proved more efficient than nginx at doing this: ~1200 rps for Traefik compared to ~900 rps for nginx (out of ~1400 rps when talking to the Synapse homeserver directly).
+
+Traefik serving this second purpose has a few downsides:
+
+- Traefik becomes a runtime dependency for all homeserver-dependant container services
+- all homeserver-dependant services now need to be connected to the `traefik` container network, even if they don't need public internet exposure
+
+Despite these downsides (which the playbook manages automatically), we believe it's still a good compromise given the amount of complexity it eliminates and the performance benefits it yields. One alternative we've [considered](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3045#issuecomment-1867327001) was adding a new intermediary service (e.g. `matrix-homeserver-proxy` powered by nginx), but this both had much higher complexity (one more component in the mix; duplication of effort to produce nginx-compatible route definitions for it) and slightly worse performance (see above).
+
+People running the default Traefik setup do not need to do anything to make Traefik take on this extra job. Your Traefik configuration will be updated automatically.
+
+**People runnning their own Traefik reverse-proxy need to do [minor adjustments](#people-managing-their-own-traefik-instance-need-to-do-minor-changes)**, as described in the section below.
+
+You may disable Traefik acting as an intermediary by explicitly setting `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled` to `false`. Services would then be configured to talk to the homeserver directly, giving you a slight performance boost and a "simpler" Traefik setup. However, such a configuration is less tested and will cause troubles, especially if you enable more services (like `matrix-media-repo`, etc.) in the future. As such, it's not recommended.
+
+
+### People managing their own Traefik instance need to do minor changes
+
+This section is for people [managing their own Traefik instance on the Matrix server](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you). Those [using Traefik managed by the playbook](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-the-playbook) don't need to do any changes.
+
+Because [Traefik has an extra job now](#traefik-now-has-an-extra-job), you need to adapt your configuration to add the additional `matrix-internal-matrix-client-api` entrypoint and potentially configure the `matrix_playbook_reverse_proxy_container_network` variable. See the [Traefik managed by you](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you) documentation section for more details.
+
+
+### People fronting Traefik with another reverse proxy need to do minor changes
+
+We've already previously mentioned that you need to do some minor [configuration changes related to `devture_traefik_additional_entrypoints_auto`](#backward-compatibility-configuration-changes-required-for-people-fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy).
+
+If you don't do these changes (switching from `devture_traefik_additional_entrypoints_auto` to multiple other variables), your Traefik setup will not automatically receive the new `matrix-internal-matrix-client-api` Traefik entrypoint and Traefik would not be able to perform [its new duty of connecting addons with the homeserver](#traefik-now-has-an-extra-job).
+
+
+### Supported reverse proxy types are now fewer
+
+This section is for people using a more custom reverse-proxy setup - those having `matrix_playbook_reverse_proxy_type` set to a value different than the default (`playbook-managed-traefik`).
+
+Previously, we allowed you to set `matrix_playbook_reverse_proxy_type` to 7 different values to accommodate various reverse-proxy setups.
+
+The complexity of this is too high, so we only support 3 values right now:
+
+- (the default) `playbook-managed-traefik`, when you're [using Traefik managed by the playbook](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-the-playbook)
+- `other-traefik-container`, when you're [managing your own Traefik instance on the Matrix server](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you)
+- `none`, when you wish for [no reverse-proxy integration to be done at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all)
+
+The `none` value is not recommended and may not work adequately, due to lack of testing and [Traefik's new responsibilities](#traefik-now-has-an-extra-job) in our setup.
+
+**Previous values that are now gone** (and the playbook would report them as such) are: `playbook-managed-nginx`, `other-nginx-non-container`, `other-on-same-host` and `other-on-another-host`.
+
+If you were using these values as a way to stay away from Traefik, you now have 2 options:
+
+- (recommended) [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy)
+- (not recommended) [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all) and reverse-proxying to each and every service manually
+
+
+### Container networking changes
+
+Now that `matrix-nginx-proxy` is not in the mix, it became easier to clear out some other long-overdue technical debt.
+
+Since the very beginning of this playbook, all playbook services were connected to a single (shared) `matrix` container network. Later on, some additional container networks appeared, but most services (database, etc.) still remained in the `matrix` container network.  This meant that any random container in this network could try to talk (or attack) the Postgres database operating in the same `matrix` network.
+
+Moving components (especially the database) into other container networks was difficult - it required changes to many other components to ensure correct connectivity.
+
+All the hard work has been done now. We've added much more isolation between services by splitting them up into separate networks (`matrix-homeserver`, `matrix-addons`, `matrix-monitoring`, `matrix-exim-relay`, etc). Components are only joined to the networks they need and should (for the most part) not be able to access unrelated things.
+
+Carrying out these container networking changes necessitated modifying many components, so **we're hoping not too many bugs were introduced in the process**.
+
+We've refrained from creating too many container networks (e.g. one for each component), to avoid exhausting Docker's default network pool and contaminating the container networks list too much.
+
+
+### Metrics exposure changes
+
+This section is for people who are exposing monitoring metrics publicly, to be consumed by an external Prometheus server.
+
+Previously, `matrix-nginx-proxy` was potentially password-protecting all `/metrics/*` endpoints with the same username and password (specified as plain-text in your `vars.yml` configuration file).
+
+From now on, there are new variables for doing roughly the same - `matrix_metrics_exposure_enabled`, `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`. See the [Prometheus & Grafana](./docs/configuring-playbook-prometheus-grafana.md) docs page for details.
+
+`matrix-nginx-proxy` is not acting as a "global guardian" anymore. Now, each role provides its own metrics exposure and protection by registering with Traefik. Nevertheless, all roles are wired (via playbook configuration in `group_vars/matrix_servers`) to obey these new `matrix_metrics_exposure_*` variables. We've eliminated the centralization, but have kept the ease of use. Now, you can also do per-service password-protection (with different credentials), should you need to do that for some reason.
+
+The playbook will tell you about all variables that you need to migrate during runtime, so rest assured - you shouldn't be able to miss anything!
+
+
+### Matrix static files
+
+As mentioned above, static files like `/.well-known/matrix/*` or your base domain's `index.html` file (when [serving the base domain via the Matrix server](./docs/configuring-playbook-base-domain-serving.md) was enabled) were generated by the `matrix-base` or `matrix-nginx-proxy` roles and put into a `/matrix/static-files` directory on the server. Then `matrix-nginx-proxy` was serving all these static files.
+
+All of this has been extracted into a new `matrix-static-files` Ansible role that's part of the playbook. The static files generated by this new role still live at roughly the same place (`/matrix/static-files/public` directory, instead of `/matrix/static-files`).
+
+The playbook will migrate and update the `/.well-known/matrix/*` files automatically but not your own files in `nginx-proxy/data/matrix-domain/` you will need to back these up yourself otherwise they will be lost. It will also warn you about usage of old variable names, so you can adapt to the new names.
+
+
+### A note on performance
+
+Some of you have been voicing their concerns (for a long time) about Traefik being too slow and nginx being better.
+
+Some online benchmarks support this by demonstrating slightly higher SSL-termination performance in favor of nginx. The upcoming Traefik v3 release is [said to](https://medium.com/beyn-technology/is-nginx-dead-is-traefik-v3-20-faster-than-traefik-v2-f28ffb7eed3e) improve Traefik's SSL performance by some 20%, but that still ends up being somewhat slower than nginx.
+
+We believe that using Traefik provides way too many benefits to worry about this minor performance impairment.
+
+The heaviest part of running a Matrix homeserver is all the slow and potentially inefficient things the homeserver (e.g. Synapse) is doing. These things affect performance much more than whatever reverse-proxy is in front. Your server will die the same way by joining the famously large **Matrix HQ** room, no matter which reverse-proxy you put in front.
+
+Even our previously mentioned benchmarks (yielding ~1300 rps) are synthetic - hitting a useless `/_matrix/client/versions` endpoint. Real-use does much more than this.
+
+If this is still not convincing enough for you and you want the best possible performance, consider [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) (thus having the slowest part - SSL termination - happen elsewhere) or [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all). The playbook will not get in your way of doing that, but these options may make your life much harder. Performance comes at a cost, after all.
+
+
+### Migration procedure
+
+The updated playbook will automatically perform some migration tasks for you:
+
+1. It will stop and remove the `matrix-nginx-proxy` systemd service and container for you. This behavior cannot be disabled. It's essential that this service gets stopped, because it remaining running (and having container labels) may confuse Traefik as to where to route HTTP requests.
+
+2. It will delete the `/matrix/nginx-proxy` directory and all files within it. You can disable this behavior by adding `matrix_playbook_migration_matrix_nginx_proxy_uninstallation_enabled: false` to your `vars.yml` configuration file. Doing so will leave its data around.
+
+3. It will delete the `/matrix/ssl` directory and all files within it. You can disable this behavior by adding `matrix_playbook_migration_matrix_ssl_uninstallation_enabled: false` to your `vars.yml` configuration file. If you have some important certificates there for some reason, take them out or temporarily disable removal of these files until you do.
+
+4. It will tell you about all variables (`matrix_nginx_proxy_*` and many others - even from other roles) that have changed during this large nginx-elimination upgrade. You can disable this behavior by adding `matrix_playbook_migration_matrix_nginx_proxy_elimination_variable_transition_checks_enabled: false` to your `vars.yml` configuration file.
+
+5. It will tell you about any leftover `matrix_nginx_proxy_*` variables in your `vars.yml` file. You can disable this behavior by adding `matrix_playbook_migration_matrix_nginx_proxy_leftover_variable_validation_checks_enabled: false` to your `vars.yml` configuration file.
+
+6. It will tell you about any leftover `matrix_ssl_*` variables in your `vars.yml` file. You can disable this behavior by adding `matrix_playbook_migration_matrix_ssl_leftover_variable_checks_enabled: false` to your `vars.yml` configuration file.
+
+We don't recommend changing these variables and suppressing warnings, unless you know what you're doing.
+
+**Most people should just upgrade as per-normal**, bearing in mind that a lot has changed and some issues may arise.
+The playbook would guide you through renamed variables automatically.
+
+
+### Conclusion
+
+Thousands of lines of code were changed across hundreds of files.
+All addons (bridges, bots) were rewired in terms of container networking and in terms of how they reach the homeserver.
+
+I don't actively use all the ~100 components offered by the playbook (no one does), nor do I operate servers exercising all edge-cases. As such, issues may arise. Please have patience and report (or try to fix) these issues!
+
+
 # 2024-01-14
 
 ## (Backward Compatibility) Configuration changes required for people fronting the integrated reverse-proxy webserver with another reverse-proxy
@@ -120,7 +470,7 @@ 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.
+- In Synapse v1.7.0 (~2019), `allow_public_rooms_over_federation` [got disabled](https://github.com/element-hq/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.
 
@@ -582,7 +932,7 @@ Large Coturn deployments (with a huge range of ports specified via `matrix_cotur
 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
+matrix_coturn_container_network: host
 ```
 
 With such a configuration, **Docker no longer needs to configure thousands of firewall forwarding rules** each time Coturn starts and stops.
@@ -923,7 +1273,7 @@ You can also control the `background` workers count with `matrix_synapse_workers
 
 ### Appservice worker support is back
 
-We previously had an `appservice` worker type, which [Synapse deprecated in v1.59.0](https://github.com/matrix-org/synapse/blob/v1.59.0/docs/upgrade.md#deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types). So did we, at the time.
+We previously had an `appservice` worker type, which [Synapse deprecated in v1.59.0](https://github.com/element-hq/synapse/blob/v1.59.0/docs/upgrade.md#deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types). So did we, at the time.
 
 The new way to implement such workers is by using a `generic_worker` and dedicating it to the task of talking to Application Services.
 From now on, we have support for this.
@@ -933,7 +1283,7 @@ You can also control the `appservice` workers count with `matrix_synapse_workers
 
 ### User Directory worker support is back
 
-We previously had a `user_dir` worker type, which [Synapse deprecated in v1.59.0](https://github.com/matrix-org/synapse/blob/v1.59.0/docs/upgrade.md#deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types). So did we, at the time.
+We previously had a `user_dir` worker type, which [Synapse deprecated in v1.59.0](https://github.com/element-hq/synapse/blob/v1.59.0/docs/upgrade.md#deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types). So did we, at the time.
 
 The new way to implement such workers is by using a `generic_worker` and dedicating it to the task of serving the user directory.
 From now on, we have support for this.
@@ -1129,7 +1479,7 @@ If you're tired of being on an old and problematic Ansible version, you can now
 
 Synapse v1.60 will try to add a new unique index to `state_group_edges` upon startup and could fail if your database is corrupted.
 
-We haven't observed this problem yet, but [the Synapse v1.60.0 upgrade notes](https://github.com/matrix-org/synapse/blob/v1.60.0/docs/upgrade.md#adding-a-new-unique-index-to-state_group_edges-could-fail-if-your-database-is-corrupted) mention it, so we're giving you a heads up here in case you're unlucky.
+We haven't observed this problem yet, but [the Synapse v1.60.0 upgrade notes](https://github.com/element-hq/synapse/blob/v1.60.0/docs/upgrade.md#adding-a-new-unique-index-to-state_group_edges-could-fail-if-your-database-is-corrupted) mention it, so we're giving you a heads up here in case you're unlucky.
 
 **If Synapse fails to start** after your next playbook run, you'll need to:
 
@@ -1187,7 +1537,7 @@ See our [Setting up borg backup](docs/configuring-playbook-backup-borg.md) docum
 
 ## (Compatibility Break) Upgrading to Synapse v1.57 on setups using workers may require manual action
 
-If you're running a worker setup for Synapse (`matrix_synapse_workers_enabled: true`), the [Synapse v1.57 upgrade notes](https://github.com/matrix-org/synapse/blob/v1.57.0rc1/docs/upgrade.md#changes-to-database-schema-for-application-services) say that you may need to take special care when upgrading:
+If you're running a worker setup for Synapse (`matrix_synapse_workers_enabled: true`), the [Synapse v1.57 upgrade notes](https://github.com/element-hq/synapse/blob/v1.57.0rc1/docs/upgrade.md#changes-to-database-schema-for-application-services) say that you may need to take special care when upgrading:
 
 > Synapse v1.57.0 includes a change to the way transaction IDs are managed for application services. If your deployment uses a dedicated worker for application service traffic, **it must be stopped** when the database is upgraded (which normally happens when the main process is upgraded), to ensure the change is made safely without any risk of reusing transaction IDs.
 
@@ -1268,7 +1618,7 @@ See our [Setting up matrix-hookshot](docs/configuring-playbook-bridge-hookshot.m
 
 We believe that 2022 will be the year of the non-Synapse Matrix server!
 
-The playbook was previously quite [Synapse](https://github.com/matrix-org/synapse)-centric, but can now accommodate multiple homeserver implementations. Only one homeserver implementation can be active (installed) at a given time.
+The playbook was previously quite [Synapse](https://github.com/element-hq/synapse)-centric, but can now accommodate multiple homeserver implementations. Only one homeserver implementation can be active (installed) at a given time.
 
 **Synapse is still the default homeserver implementation** installed by the playbook. A new variable (`matrix_homeserver_implementation`) controls which server implementation is enabled (`synapse` or `dendrite` at the given moment).
 
@@ -1839,7 +2189,7 @@ To restore the old behavior of not redirecting anywhere and serving the Synapse
 We used to expose the Synapse Admin APIs publicly (at `https://matrix.DOMAIN/_synapse/admin`).
 These APIs require authentication with a valid access token, so it's not that big a deal to expose them.
 
-However, following [official Synapse's reverse-proxying recommendations](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints), we're no longer exposing `/_synapse/admin` by default.
+However, following [official Synapse's reverse-proxying recommendations](https://github.com/element-hq/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints), we're no longer exposing `/_synapse/admin` by default.
 
 If you'd like to restore restore the old behavior and expose `/_synapse/admin` publicly, you can use the following configuration (in your `vars.yml`):
 
@@ -2492,7 +2842,7 @@ To avoid doing it manually, run this:
 
 ## Synapse no longer required
 
-The playbook no longer insists on installing [Synapse](https://github.com/matrix-org/synapse) via the `matrix-synapse` role.
+The playbook no longer insists on installing [Synapse](https://github.com/element-hq/synapse) via the `matrix-synapse` role.
 
 If you would prefer to install Synapse another way and just use the playbook to install other services, it should be possible (`matrix_synapse_enabled: false`).
 
@@ -3024,7 +3374,7 @@ If users participate in large rooms with many other servers, disabling presence
 The playbook now makes the Synapse cache factor configurable, through the playbook's `matrix_synapse_cache_factor` variable (having a default value of `0.5`).
 
 Changing that value allows you to potentially decrease RAM usage or to increase performance by caching more stuff.
-Some information on it is available here: https://github.com/matrix-org/synapse#help-synapse-eats-all-my-ram
+Some information on it is available here: https://github.com/element-hq/synapse#help-synapse-eats-all-my-ram
 
 
 # 2018-09-26

README.md

@@ -37,7 +37,7 @@ The homeserver is the backbone of your matrix system. Choose one from the follow
 
 | 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) |
+| [Synapse](https://github.com/element-hq/synapse) | ✓ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network | [Link](docs/configuring-playbook-synapse.md) |
 | [Conduit](https://conduit.rs) | 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) |
 
@@ -63,7 +63,6 @@ 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) |
 | [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) |
@@ -166,12 +165,14 @@ 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_accept_invite](https://github.com/matrix-org/synapse-auto-accept-invite) | x | A Synapse module to automatically accept invites. | [Link](docs/configuring-playbook-synapse-auto-accept-invite.md) |
 | [synapse_auto_compressor](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) | 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) |
 | [Jitsi](https://jitsi.org/) | x | An open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
 | [Cactus Comments](https://cactus.chat) | x | A federated comment system built on matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
+| [Pantalaimon](https://github.com/matrix-org/pantalaimon) | x | An E2EE aware proxy daemon | [Link](docs/configuring-playbook-pantalaimon.md) |
 
 
 ## Installation

YEAR-IN-REVIEW.md

@@ -63,7 +63,7 @@ We have **hundreds of contributors to thank for their hard work** on making Matr
 
 # 2022
 
-For [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy/), 2022 started with **breaking the** [**Synapse**](https://github.com/matrix-org/synapse) **monopoly** by [adding support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#dendrite-support) for the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver in early January. This required various internal changes so that the [Ansible](https://www.ansible.com/) playbook would not be Synapse-centric anymore. This groundwork paved the way for continuing in this direction and we [added support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#conduit-support) for [Conduit](https://conduit.rs/) in August.
+For [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy/), 2022 started with **breaking the** [**Synapse**](https://github.com/element-hq/synapse) **monopoly** by [adding support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#dendrite-support) for the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver in early January. This required various internal changes so that the [Ansible](https://www.ansible.com/) playbook would not be Synapse-centric anymore. This groundwork paved the way for continuing in this direction and we [added support](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/ba09705f7fbaf0108652ecbe209793b1d935eba7/CHANGELOG.md#conduit-support) for [Conduit](https://conduit.rs/) in August.
 
 When it comes to the `matrix-docker-ansible-deploy` Ansible playbook, 2022 was the year of the non-Synapse homeserver implementation. In practice, none of these homeserver implementations seem ready for prime-time yet and there is no migration path when coming from Synapse. Having done our job of adding support for these alternative homeserver implementations, we can say that we're not getting in the way of future progress. It's time for the Dendrite developers to push harder (development-wise) and for the Synapse developers to take a well-deserved long (infinite) break, and we may get to see more people migrating away from Synapse in the next year(s).
 

ansible.cfg

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

bin/ansible-all-hosts.sh

@@ -8,7 +8,7 @@
 #
 
 # set playbook root path
-root=$(dirname "$(readlink -f "$0")")/../..
+root=$(dirname "$(readlink -f "$0")")/..
 
 # set default tags or get from first argument if any
 tags="${1:-setup-all,start}"

bin/rebuild-mautrix-meta-instagram.sh

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

docs/configuring-captcha.md

@@ -1,4 +1,4 @@
-(Adapted from the [upstream project](https://github.com/matrix-org/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
+(Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
 
 # Overview
 Captcha can be enabled for this home server. This file explains how to do that.

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

@@ -0,0 +1,100 @@
+# Setting up Draupnir for All/D4A (optional)
+
+The playbook can install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool for you in appservice mode.
+
+Appservice mode can be used together with the regular [Draupnir bot](configuring-playbook-bot-draupnir.md) or independently. Details about the differences between the 2 modes are described below.
+
+
+## Draupnir Appservice mode compared to Draupnir bot mode
+
+The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
+
+Draupnir for all is the way to go if you need more than 1 Draupnir instance, but you don't need access to Synapse Admin features as they are not accessible through Draupnir for All (Even though the commands do show up in help).
+
+Draupnir for all in the playbook is rate-limit-exempt automatically as its appservice configuration file does not specify any rate limits.
+
+Normal Draupnir does come with the benefit of access to Synapse Admin features. You are also able to more easily customise your normal Draupnir than D4A as D4A even on the branch with the Avatar command (To be Upstreamed to Mainline Draupnir) that command is clunky as it requires the use of things like Element devtools. In normal draupnir this is a quick operation where you login to Draupnir with a normal client and set Avatar and Display name normally.
+
+Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
+
+
+## Installation
+
+### 1. Create a main management room.
+
+The playbook does not create a management room for your Main Draupnir. This task you have to do on your own.
+
+The management room has to be given an alias and be public when you are setting up the bot for the first time as the bot does not differentiate between invites
+and invites to the management room.
+
+This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element calls this powerlevel.
+
+As noted in the Draupnir install instructions the control room is sensitive. The following is said about the control room in the Draupnir install instructions.
+>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.
+
+### 2. Give your main management room an alias.
+
+Give the room from step 1 an alias. This alias can be anything you want and its recommended for increased security during the setup phase of the bot that you make this alias be a random string. You can give your room a secondary human readable alias when it has been locked down after setup phase.
+
+### 3. 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 `ALIAS_FROM_STEP_2_GOES_HERE` with the alias you created in step 2.
+
+```yaml
+matrix_appservice_draupnir_for_all_enabled: true
+
+matrix_appservice_draupnir_for_all_master_control_room_alias: "ALIAS_FROM_STEP_2_GOES_HERE"
+```
+
+### 4. Installing
+
+After configuring the playbook, run the [installation](installing.md) command:
+
+```
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+
+## Usage
+
+If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:matrix-homeserver-domain` you have succesfully installed Draupnir for All and can now start using it.
+
+The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for allis almost identical to Draupnir bot mode.
+
+### 1. Granting Users the ability to use D4A
+
+Draupnir for all includes several security measures like that it only allows users that are on its allow list to ask for a bot. To add a user to this list we have 2 primary options. Using the chat to tell Draupnir to do this for us or if you want to automatically do it by sending `m.policy.rule.user` events that target the subject you want to allow provisioning for with the `org.matrix.mjolnir.allow` recomendation. Using the chat is recomended.
+
+The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
+
+To allow users or whole homeservers you type /plain @draupnir-main:matrix-homeserver-domain allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
+
+### 2. How to provision a D4A once you are allowed to.
+
+Open a DM with @draupnir-main:matrix-homeserver-domain and if using Element send a message into this DM to finalise creating it. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
+
+Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
+
+### Configuration of D4A
+
+You can refer to the upstream [documentation](https://github.com/the-draupnir-project/Draupnir) for more configuration documentation. Please note that the playbook ships a full copy of the example config that does transfer to provisioned draupnirs in the production-bots.yaml.j2 file in the template directory of the role.
+
+Please note that Config extension does not affect the appservices config as this config is not extensible in current Draupnir anyways. Config extension instead touches the config passed to the Draupnirs that your Appservice creates. So for example below makes all provisioned Draupnirs protect all joined rooms.
+
+You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file.
+
+For example to change draupnir's `protectAllJoinedRooms` option to `true` you would add the following to your `vars.yml` file.
+
+```yaml
+matrix_appservice_draupnir_for_all_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_appservice_draupnir_for_all_yaml`.
+  protectAllJoinedRooms: true
+```

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

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

docs/configuring-playbook-bot-buscarron.md

@@ -20,8 +20,6 @@ matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
 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
 

docs/configuring-playbook-bot-draupnir.md

@@ -4,6 +4,9 @@ The playbook can install and configure the [draupnir](https://github.com/the-dra
 
 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.
 
+This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead.
+
+
 If your migrating from Mjolnir skip to step 5b.
 
 ## 1. Register the bot account
@@ -32,7 +35,7 @@ Refer to the documentation on [how to obtain an access token](obtaining-access-t
 
 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. 
+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_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
 
 The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@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.
 
@@ -40,14 +43,57 @@ The following command works on semi up to date Windows 10 installs and All Windo
 
 ## 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.
+Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
+
+If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
 
 Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element 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
+## 5. Adjusting the playbook configuration
+
+Decide whether you want Draupnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Draupnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+
+### 5a. Configuration with E2EE support
+
+When using Pantalaimon, Draupnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
+matrix_pantalaimon_enabled: true
+
+# Enable Draupnir
+matrix_bot_draupnir_enabled: true
+
+# Tell Draupnir to use Pantalaimon
+matrix_bot_draupnir_pantalaimon_use: true
+
+# User name and password for the bot. Required when using Pantalaimon.
+matrix_bot_draupnir_pantalaimon_username: "DRAUPNIR_USERNAME_FROM_STEP_1"
+matrix_bot_draupnir_pantalaimon_password: ### you should create a secure password for the bot account
+
+matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+```
+
+The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Draupnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
+
+```yaml
+# Endpoint URL that Draupnir uses to interact with the matrix homeserver (client-server API).
+# Set this to the pantalaimon URL if you're using that.
+matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_draupnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
+
+# Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
+# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
+matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+```
+
+### 5b. Configuration without E2EE support
+
+When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account.
 
 Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
@@ -61,7 +107,7 @@ 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.)
+### 5c. 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.

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

@@ -39,8 +39,6 @@ matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
 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
 
@@ -62,7 +60,7 @@ matrix_bot_go_neb_clients:
   - UserID: "@goneb:{{ matrix_domain }}"
     AccessToken: "MDASDASJDIASDJASDAFGFRGER"
     DeviceID: "DEVICE1"
-    HomeserverURL: "{{ matrix_homeserver_container_url }}"
+    HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: true
     AutoJoinRooms: true
     DisplayName: "Go-NEB!"
@@ -71,7 +69,7 @@ matrix_bot_go_neb_clients:
   - UserID: "@another_goneb:{{ matrix_domain }}"
     AccessToken: "MDASDASJDIASDJASDAFGFRGER"
     DeviceID: "DEVICE2"
-    HomeserverURL: "{{ matrix_homeserver_container_url }}"
+    HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}"
     Sync: false
     AutoJoinRooms: false
     DisplayName: "Go-NEB!"
@@ -178,13 +176,13 @@ matrix_bot_go_neb_services:
       Rooms:
         "!someroom:id":
           Repos:
-            "matrix-org/synapse":
+            "element-hq/synapse":
               Events: ["push", "issues"]
             "matrix-org/dendron":
               Events: ["pull_request"]
         "!anotherroom:id":
           Repos:
-            "matrix-org/synapse":
+            "element-hq/synapse":
               Events: ["push", "issues"]
             "matrix-org/dendron":
               Events: ["pull_request"]

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

@@ -3,8 +3,7 @@
 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** 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.
+It can be used for an invitation-based server, where you invite someone by sending them a registration token (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process.
 
 See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
 does and why it might be useful to you.

docs/configuring-playbook-bot-maubot.md

@@ -55,4 +55,4 @@ Choose a strong password for the bot. You can generate a good password with a co
 ## Obtaining an admin access token
 
 This can be done via `mbc login` then `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). To run these commands you'll need to open the bot docker container with `docker exec -it matrix-bot-maubot sh`
-Alternatively, use Element or curl to [obtain an access token](obtaining-access-tokens.md). However these two methods won't allow the bot to work in encrypted rooms.
+Alternatively, use Element or curl to [obtain an access token](obtaining-access-tokens.md).

docs/configuring-playbook-bot-mjolnir.md

@@ -31,13 +31,15 @@ Refer to the documentation on [how to obtain an access token](obtaining-access-t
 
 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.
 
-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. 
+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_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
 
 The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@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
 
-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.
+Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
+
+If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
 
 Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element 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`.
 
@@ -46,6 +48,47 @@ Finally invite the `@bot.mjolnir:DOMAIN` account you created earlier into the ro
 
 ## 5. Adjusting the playbook configuration
 
+Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+
+### 5a. Configuration with E2EE support
+
+When using Pantalaimon, Mjolnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
+matrix_pantalaimon_enabled: true
+
+# Enable Mjolnir
+matrix_bot_mjolnir_enabled: true
+
+# Tell Mjolnir to use Pantalaimon
+matrix_bot_mjolnir_pantalaimon_use: true
+
+# User name and password for the bot. Required when using Pantalaimon.
+matrix_bot_mjolnir_pantalaimon_username: "MJOLNIR_USERNAME_FROM_STEP_1"
+matrix_bot_mjolnir_pantalaimon_password: ### you should create a secure password for the bot account
+
+matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+```
+
+The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Mjolnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
+
+```yaml
+# Endpoint URL that Mjolnir uses to interact with the matrix homeserver (client-server API).
+# Set this to the pantalaimon URL if you're using that.
+matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_mjolnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
+
+# Endpoint URL that Mjolnir could use to fetch events related to reports (client-server API and /_synapse/),
+# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
+matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+```
+
+### 5b. Configuration without E2EE support
+
+When NOT using Pantalaimon, Mjolnir does not log in by itself and you must give it an access token for its bot account.
+
 Add the following configuration to your `inventory/host_vars/matrix.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.

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

@@ -20,8 +20,24 @@ matrix_appservice_slack_enabled: true
 matrix_appservice_slack_control_room_id: "Your matrix admin room id"
 ```
 
-3. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
-4. Invite the bridge bot user into the admin room:
+3. Enable puppeting (optional, but recommended)
+
+```yaml
+matrix_appservice_slack_puppeting_enabled: true
+matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
+matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
+```
+
+4. Enable Team Sync (optional)
+
+```yaml
+matrix_appservice_slack_team_sync_enabled: true
+```
+
+   See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
+
+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 into the admin room:
 
 ```
     /invite @slackbot:MY.DOMAIN
@@ -29,7 +45,7 @@ matrix_appservice_slack_control_room_id: "Your matrix admin room id"
 
 Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
 
-5. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
+6. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
 
     Name the app "matrixbot" (or anything else you'll remember).
 
@@ -37,7 +53,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
 
     Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
 
-6. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
+7. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
 
      Bot User Events:
 
@@ -47,7 +63,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
     - reaction_added
     - reaction_removed
 
-7. Click on OAuth & Permissions and add the following scopes:
+8. Click on OAuth & Permissions and add the following scopes:
 
     - chat:write:bot
     - users:read
@@ -59,9 +75,9 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
 
     Note: In order to make Slack files visible to matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
 
-8. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
+9. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
 
-9. For each channel you would like to bridge, perform the following steps:
+10. If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
 
     * Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !aBcDeF:example.com.
 
@@ -86,7 +102,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
 
 Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
 
-10. Unlinking
+11. Unlinking
 
     Channels can be unlinked again like this:
     ```

docs/configuring-playbook-bridge-hookshot.md

@@ -57,9 +57,9 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
 | provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
 | appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
 | widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
-| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and `matrix_hookshot_metrics_proxying_enabled`. Requires `/metrics/*` endpoints to also be enabled via `matrix_nginx_proxy_proxy_matrix_metrics_enabled` (see the `matrix-nginx-proxy` role). Read more in the [Metrics section](#metrics) below. | Prometheus |
+| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and exposure enabled via `matrix_hookshot_metrics_proxying_enabled` or `matrix_metrics_exposure_enabled`. Read more in the [Metrics section](#metrics) below. | Prometheus |
 
-See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/custom/matrix-bridge-hookshot/tasks/inject_into_nginx_proxy.yml).
+Also see the various `matrix_hookshot_container_labels_*` variables in in [default/main.yml](/roles/custom/matrix-bridge-hookshot/default/main.yml), which expose URLs publicly.
 
 The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
 
@@ -91,10 +91,12 @@ Metrics are **only enabled by default** if the builtin [Prometheus](configuring-
 
 To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This only exposes metrics over the container network, however.
 
-**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to:
+**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.DOMAIN/metrics/hookshot` by:
 
-- enable the `https://matrix.DOMAIN/metrics/*` endpoints on `matrix.DOMAIN` using `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true` (see the `matrix-nginx-role` or [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for enabling this feature)
-- expose the Hookshot metrics under `https://matrix.DOMAIN/metrics/hookshot` by setting `matrix_hookshot_metrics_proxying_enabled: true`
+- either enabling metrics exposure for Hookshot via `matrix_hookshot_metrics_proxying_enabled: true`
+- or enabling metrics exposure for all services via `matrix_metrics_exposure_enabled: true`
+
+Whichever one you go with, by default metrics are exposed publicly **without** password-protection. See [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for details about password-protection for metrics.
 
 ### Collision with matrix-appservice-webhooks
 

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

@@ -1,5 +1,7 @@
 # Setting up Mautrix Facebook (optional)
 
+**Note**: bridging to Facebook [Messenger](https://messenger.com) via this bridge is being [superseded by a new bridge - mautrix-meta](https://github.com/mautrix/facebook/issues/332). For now, the mautrix-facebook bridge continues to work, but the new [mautrix-meta-messenger bridge](./configuring-playbook-bridge-mautrix-meta-messenger.md) is better and more supported. Consider using that bridge instead of this one.
+
 The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you.
 
 See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.

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

@@ -1,5 +1,7 @@
 # Setting up Mautrix Instagram (optional)
 
+**Note**: bridging to Facebook [Instagram](https://instagram.com) via this bridge is being [superseded by a new bridge - mautrix-meta](https://github.com/mautrix/facebook/issues/332). For now, the mautrix-instagram bridge continues to work, but the new [mautrix-meta-instagram bridge](./configuring-playbook-bridge-mautrix-meta-instagram.md) is better and more supported. Consider using that bridge instead of this one.
+
 The playbook can install and configure [mautrix-instagram](https://github.com/mautrix/instagram) for you.
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/index.html) to learn what it does and why it might be useful to you.

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

@@ -0,0 +1,90 @@
+# Setting up Instagram bridging via Mautrix Meta (optional)
+
+The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
+
+Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
+
+This documentation page only deals with the bridge's ability to bridge to Instagram. For bridging to Facebook/Messenger, see [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md).
+
+
+## Migrating from the old mautrix-instagram bridge
+
+If you've been using the [mautrix-instagram](./configuring-playbook-bridge-mautrix-instagram.md) bridge, **you'd better get rid of it first** or the 2 bridges will be in conflict:
+
+- both trying to use `@instagrambot:YOUR_DOMAIN` as their username. This conflict may be resolved by adjusting `matrix_mautrix_instagram_appservice_bot_username` or `matrix_mautrix_meta_instagram_appservice_username`
+- both trying to bridge the same DMs
+
+To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@instagrambot:YOUR_DOMAIN`).
+
+This would give you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
+
+Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
+
+
+## Configuration
+
+Most simply, you can enable the bridge with the following playbook configuration:
+
+```yaml
+matrix_mautrix_meta_instagram_enabled: true
+```
+
+Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
+
+### Bridge permissions
+
+By default, any user on your homeserver will be able to use the bridge.
+
+Different levels of permission can be granted to users:
+
+- `relay` - Allowed to be relayed through the bridge, no access to commands
+- `user` - Use the bridge with puppeting
+- `admin` - Use and administer the bridge
+
+The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
+
+The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this:
+```yaml
+matrix_mautrix_meta_instagram_bridge_permissions_default:
+  '*': relay
+  YOUR_DOMAIN: user
+  '{{ matrix_admin }}': admin
+```
+
+If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:YOUR_DOMAIN`), then there's no admin by default.
+
+You may redefine `matrix_mautrix_meta_instagram_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_instagram_bridge_permissions_custom` like this:
+
+```yaml
+matrix_mautrix_meta_instagram_bridge_permissions_custom:
+  '@YOUR_USERNAME:YOUR_DOMAIN': admin
+```
+
+You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
+
+## 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 session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
+
+
+## Usage
+
+You then need to start a chat with `@instagrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

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

@@ -0,0 +1,105 @@
+# Setting up Messenger bridging via Mautrix Meta (optional)
+
+The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
+
+Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
+
+This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md).
+
+
+## Migrating from the old mautrix-facebook bridge
+
+If you've been using the [mautrix-facebook](./configuring-playbook-bridge-mautrix-facebook.md) bridge, it's possible to migrate the database using [instructions from the bridge documentation](https://docs.mau.fi/bridges/go/meta/facebook-migration.html) (advanced).
+
+Then you may wish to get rid of the Facebook bridge. To do so, send a `clean-rooms` command to the management room with the old bridge bot (`@facebookbot:YOUR_DOMAIN`).
+
+This would give you a list of portals and groups of portals you may purge. Proceed with sending commands like `clean recommended`, etc.
+
+Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
+
+
+## Configuration
+
+Most simply, you can enable the bridge with the following playbook configuration:
+
+```yaml
+matrix_mautrix_meta_messenger_enabled: true
+```
+
+Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below.
+
+### Bridge mode
+
+As mentioned above, the [mautrix-meta](https://github.com/mautrix/meta) bridge supports multiple modes of operation.
+The bridge can pull your Messenger messages via 3 different methods:
+
+- (`facebook`) Facebook via `facebook.com`
+- (`facebook-tor`) Facebook via `facebookwkhpilnemxj7asaniu7vnjjbiltxjqhye3mhbshg7kx5tfyd.onion` ([Tor](https://www.torproject.org/)) - does not currently proxy media downloads
+- (default) (`messenger`) Messenger via `messenger.com` - usable even without a Facebook account
+
+You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variable. The playbook defaults to the `messenger` mode, because it's most universal (every Facebook user has a Messenger account, but the opposite is not true).
+
+Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.).
+
+
+### Bridge permissions
+
+By default, any user on your homeserver will be able to use the bridge.
+
+Different levels of permission can be granted to users:
+
+- `relay` - Allowed to be relayed through the bridge, no access to commands
+- `user` - Use the bridge with puppeting
+- `admin` - Use and administer the bridge
+
+The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
+
+The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this:
+```yaml
+matrix_mautrix_meta_messenger_bridge_permissions_default:
+  '*': relay
+  YOUR_DOMAIN: user
+  '{{ matrix_admin }}': admin
+```
+
+If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:YOUR_DOMAIN`), then there's no admin by default.
+
+You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this:
+
+```yaml
+matrix_mautrix_meta_messenger_bridge_permissions_custom:
+  '@YOUR_USERNAME:YOUR_DOMAIN': admin
+```
+
+You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
+
+## 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 session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
+
+
+## Usage
+
+You then need to start a chat with `@messengerbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+
+You then need to send a `login` command and follow the bridge bot's instructions.
+
+Given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there as per [the bridge's authentication instructions](https://docs.mau.fi/bridges/go/meta/authentication.html).

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

@@ -45,7 +45,7 @@ This will add the admin permission to the specific user, while keeping the defau
 
 In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
 ```yaml
-matrix_mautrix_signal_bridge_permissions: |
+matrix_mautrix_signal_bridge_permissions:
   '@ADMIN:YOUR_DOMAIN': admin
   '@USER:YOUR_DOMAIN' : user
 ```

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

@@ -24,23 +24,6 @@ matrix_mautrix_whatsapp_bridge_relay_admin_only: false
 If you want to activate the relay bot in a room, use `!wa set-relay`.
 Use `!wa 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.
-Use the following playbook configuration:
-
-```yaml
-matrix_synapse_configuration_extension_yaml: |
-  experimental_features:
-    msc2716_enabled: true
-```
-```yaml
-matrix_mautrix_whatsapp_configuration_extension_yaml:
-  bridge:
-    history_sync:
-      backfill: true
-```
-
 ## Set up Double Puppeting
 
 If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.

docs/configuring-playbook-cactus-comments.md

@@ -1,13 +1,19 @@
 # Setting up Cactus Comments (optional)
 
-The playbook can install and configure [Cactus Comments](https://cactus.chat) for you.
+The playbook can install and configure the [Cactus Comments](https://cactus.chat) system for you.
 
-Cactus Comments is a **federated comment system** built on Matrix. The role allows you to self-host the system.
-It respects your privacy, and puts you in control.
+Cactus Comments is a **federated comment system** built on Matrix. It respects your privacy, and puts you in control.
 
 See the project's [documentation](https://cactus.chat/docs/getting-started/introduction/) to learn what it
 does and why it might be useful to you.
 
+The playbook contains 2 roles for configuring different pieces of the Cactus Comments system:
+
+- `matrix-cactus-comments` - the backend appservice integrating with the Matrix homeserver
+
+- `matrix-cactus-comments-client` - a static website server serving the [cactus-client](https://cactus.chat/docs/client/introduction/) static assets (`cactus.js` and `styles.css`)
+
+You can enable whichever component you need (typically both).
 
 ## Configuration
 
@@ -18,22 +24,29 @@ Add the following block to your `vars.yaml` and make sure to exchange the tokens
 ## Cactus Chat ##
 #################
 
+# This enables the backend (appservice)
 matrix_cactus_comments_enabled: true
 
 # To allow guest comments without users needing to log in, you need to have guest registration enabled.
-# To do this you need to uncomment one of the following lines (depending if you are using synapse or dentrite as a homeserver)
-# If you don't know which one you use: The default is synapse ;)
+# To do this you need to uncomment one of the following lines (depending if you are using Synapse or Dendrite as a homeserver)
+# If you don't know which one you use: The default is Synapse ;)
 # matrix_synapse_allow_guest_access: true
-# matrix_dentrite_allow_guest_access: true
+# matrix_dendrite_allow_guest_access: true
+
+# This enables client assets static files serving on `https://matrix.DOMAIN/cactus-comments`.
+# When the backend (appservice) is enabled, this is also enabled automatically,
+# but we explicitly enable it here.
+matrix_cactus_comments_client_enabled: true
+
+# Uncomment and adjust if you'd like to host the client assets at a different location.
+# These variables are only make used if (`matrix_cactus_comments_client_enabled: true`)
+# matrix_cactus_comments_client_hostname: "{{ matrix_server_fqn_matrix }}"
+# matrix_cactus_comments_client_path_prefix: /cactus-comments
 ```
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command again:
-
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
-```
+After configuring the playbook, run the [installation](installing.md) command again.
 
 
 ## Usage
@@ -48,7 +61,6 @@ Now you are good to go and can include the comment section on your website!
 
 Insert the following snippet into you page and make sure to replace `example.com` with your base domain!
 
-
 ```html
 <script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
 <link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">

docs/configuring-playbook-client-schildichat.md

@@ -2,7 +2,7 @@
 
 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!
+**WARNING**: SchildiChat is based on Element-web, but its releases are lagging behind. As an example (from 2024-02-26), SchildiChat is 22 releases behind (it being based on element-web `v1.11.36`, while element-web is now on `v1.11.58`). 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

docs/configuring-playbook-conduit.md

@@ -1,6 +1,6 @@
 # Configuring Conduit (optional)
 
-By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).
+By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).
 
 **NOTES**:
 
@@ -55,4 +55,3 @@ Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/ma
     sender_localpart: _bot_signalbot
     url: http://matrix-mautrix-signal:29328
     ```
-

docs/configuring-playbook-dendrite.md

@@ -1,6 +1,6 @@
 # Configuring Dendrite (optional)
 
-By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, but you can also use [Dendrite](https://github.com/matrix-org/dendrite).
+By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, but you can also use [Dendrite](https://github.com/matrix-org/dendrite).
 
 **NOTES**:
 

docs/configuring-playbook-dimension.md

@@ -5,7 +5,7 @@ If you're just installing Matrix services for the first time, please continue wi
 
 **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).
+**Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
 
 
 ## Decide on a domain and path

docs/configuring-playbook-email2matrix.md

@@ -70,7 +70,6 @@ matrix_email2matrix_matrix_mappings:
     SkipMarkdown: true
 ```
 
-You can also set `MatrixHomeserverUrl` to `http://matrix-synapse-reverse-proxy-companion:8008`, instead of the public `https://matrix.DOMAIN`.
-However, that's more likely to break in the future if you switch to another server implementation than Synapse.
+You can also set `MatrixHomeserverUrl` to the container URL where your homeserver's Client-Server API lives by using the `{{ matrix_addons_homeserver_client_api_url }}` variable, instead of the public `https://matrix.DOMAIN` endpoint.
 
 Re-run the playbook (`--tags=setup-email2matrix,start`) and try sending an email to `my-mailbox@matrix.DOMAIN`.

docs/configuring-playbook-etherpad.md

@@ -20,16 +20,6 @@ etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
 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
 

docs/configuring-playbook-federation.md

@@ -33,7 +33,7 @@ matrix_synapse_allow_public_rooms_over_federation: true
 To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
 
 ```yaml
-matrix_synapse_federation_enabled: false
+matrix_homeserver_federation_enabled: false
 ```
 
 With that, your server's users will only be able to talk among themselves, but not to anyone who is on another server.
@@ -41,12 +41,11 @@ With that, your server's users will only be able to talk among themselves, but n
 **Disabling federation does not necessarily disable the federation port** (`8448`). Services like [Dimension](configuring-playbook-dimension.md) and [ma1sd](configuring-playbook-ma1sd.md) normally rely on `openid` APIs exposed on that port. Even if you disable federation and only if necessary, we may still be exposing the federation port and serving the `openid` APIs there. To override this and completely disable Synapse's federation port use:
 
 ```yaml
+matrix_homeserver_federation_enabled: false
+
 # This stops the federation port on the Synapse side (normally `matrix-synapse:8048` on the container network).
 matrix_synapse_federation_port_enabled: false
 
-# This removes the `8448` virtual host from the matrix-nginx-proxy reverse-proxy server.
-matrix_nginx_proxy_proxy_matrix_federation_api_enabled: false
-
 # This stops the federation port on the synapse-reverse-proxy-companion side (normally `matrix-synapse-reverse-proxy-companion:8048` on the container network).
 matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
 ```
@@ -55,6 +54,7 @@ matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
 
 Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
 
+
 The following changes in the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
 
 ```

docs/configuring-playbook-ma1sd.md

@@ -44,9 +44,9 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
 
 - `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring_captcha.md) documentation.
 
-- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering
+- `matrix_synapse_registrations_require_3pid` - a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering
 
-- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
+- variables prefixed with `matrix_ma1sd_container_labels_` (e.g. `matrix_ma1sd_container_labels_matrix_client_3pid_registration_enabled`) - to configure the Traefik reverse-proxy to capture and send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality
 
 - `matrix_ma1sd_configuration_extension_yaml` - to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
 

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

@@ -29,5 +29,8 @@ matrix_ldap_registration_proxy_ldap_uri: "{{ matrix_synapse_ext_password_provide
 matrix_ldap_registration_proxy_ldap_base_dn: "{{ matrix_synapse_ext_password_provider_ldap_base }}"
 matrix_ldap_registration_proxy_ldap_user: "{{ matrix_synapse_ext_password_provider_ldap_bind_dn }}"
 matrix_ldap_registration_proxy_ldap_password: "{{ matrix_synapse_ext_password_provider_ldap_bind_password }}"
+
+matrix_ldap_registration_proxy_systemd_wanted_services_list_custom:
+  - matrix-synapse.service
 ```
 

docs/configuring-playbook-mautrix-bridges.md

@@ -40,16 +40,14 @@ Encryption support is off by default. If you would like to enable encryption, ad
 
 ```yaml
 matrix_bridges_encryption_enabled: true
+matrix_bridges_encryption_default: true
 ```
 
 **Alternatively**, for a specific bridge:
 
 ```yaml
-matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
-  bridge:
-    encryption:
-      allow: true
-      default: true
+matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
+matrix_mautrix_SERVICENAME_bridge_encryption_default: true
 ```
 
 ## relay mode

docs/configuring-playbook-nginx.md

@@ -1,83 +1,3 @@
 # Configure Nginx (optional, advanced)
 
-**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
-
-This will serve a statuspage to the hosting machine only. Useful for monitoring software like [longview](https://www.linode.com/docs/platform/longview/longview-app-for-nginx/)
-
-```yaml
-matrix_nginx_proxy_proxy_matrix_nginx_status_enabled: true
-```
-
-This will serve the status page under the following addresses:
-- `http://matrix.DOMAIN/nginx_status` (using HTTP)
-- `https://matrix.DOMAIN/nginx_status` (using HTTPS)
-
-By default, if ```matrix_nginx_proxy_nginx_status_enabled``` is enabled, access to the status page would be allowed from the local IP address of the server. If you wish to allow access from other IP addresses, you can provide them as a list:
-
-```yaml
-matrix_nginx_proxy_proxy_matrix_nginx_status_allowed_addresses:
-- 8.8.8.8
-- 1.1.1.1
-```
-
-## Adjusting SSL in your server
-
-You can adjust how the SSL is served by the nginx server using the `matrix_nginx_proxy_ssl_preset` variable. We support a few presets, based on the Mozilla Server Side TLS
-Recommended configurations. These presets influence the TLS Protocol, the SSL Cipher Suites and the `ssl_prefer_server_ciphers` variable of nginx.
-Possible values are:
-
-- `"modern"` - For Modern clients that support TLS 1.3, with no need for backwards compatibility
-- `"intermediate"` (**default**) - Recommended configuration for a general-purpose server
-- `"old"` - Services accessed by very old clients or libraries, such as Internet Explorer 8 (Windows XP), Java 6, or OpenSSL 0.9.8
-
-**Be really carefull when setting it to `"modern"`**. This could break comunication with other Matrix servers, limiting your federation posibilities.
-
-Besides changing the preset (`matrix_nginx_proxy_ssl_preset`), you can also directly override these 3 variables:
-
-- `matrix_nginx_proxy_ssl_protocols`: for specifying the supported TLS protocols.
-- `matrix_nginx_proxy_ssl_prefer_server_ciphers`: for specifying if the server or the client choice when negotiating the cipher. It can set to `on` or `off`.
-- `matrix_nginx_proxy_ssl_ciphers`: for specifying the SSL Cipher suites used by nginx.
-
-For more information about these variables, check the `roles/custom/matrix-nginx-proxy/defaults/main.yml` file.
-
-## Synapse + OpenID Connect for Single-Sign-On
-
-If you want to use OpenID Connect as an SSO provider (as per the [Synapse OpenID docs](https://github.com/matrix-org/synapse/blob/develop/docs/openid.md)), you need to use the following configuration (in your `vars.yml` file) to instruct nginx to forward `/_synapse/oidc` to Synapse:
-
-```yaml
-matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_oidc_api_enabled: true
-```
-
-## Disable Nginx access logs
-
-This will disable the access logging for nginx.
-
-```yaml
-matrix_nginx_proxy_access_log_enabled: false
-```
-
-## Additional configuration
-
-This playbook also allows for additional configuration to be applied to the nginx server.
-
-If you want this playbook to obtain and renew certificates for other domains, then you can set the `matrix_ssl_additional_domains_to_obtain_certificates_for` variable (as mentioned in the [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) documentation as well). Make sure that you have set the DNS configuration for the domains you want to include to point at your server.
-
-```yaml
-matrix_ssl_additional_domains_to_obtain_certificates_for:
-  - domain.one.example
-  - domain.two.example
-```
-
-You can include additional nginx configuration by setting the `matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks` variable.
-
-```yaml
-matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks:
-  - |
-    # These lines will be included in the nginx configuration.
-    # This is at the top level of the file, so you will need to define all of the `server { ... }` blocks.
-  - |
-    # For advanced use, have a look at the template files in `roles/custom/matrix-nginx-proxy/templates/nginx/conf.d`
-```
+Since 2024-01, this playbook no longer uses nginx as its reverse-proxy.

docs/configuring-playbook-own-webserver.md

@@ -6,7 +6,11 @@ If that's alright, you can skip this.
 
 ## Traefik
 
-[Traefik](https://traefik.io/) is the default reverse-proxy for the playbook since [2023-02-26](../CHANGELOG.md/#2023-02-26).
+[Traefik](https://traefik.io/) is the default reverse-proxy for the playbook since [2023-02-26](../CHANGELOG.md/#2023-02-26) and serves **2 purposes**:
+
+- serving public traffic and providing SSL-termination with certificates obtained from [Let's Encrypt](https://letsencrypt.org/). See [Adjusting SSL certificate retrieval](./configuring-playbook-ssl-certificates.md).
+
+- assists internal communication between addon services (briges, bots, etc.) and the homeserver via an internal entrypoint (`matrix-internal-matrix-client-api`).
 
 There are 2 ways to use Traefik with this playbook, as described below.
 
@@ -22,31 +26,39 @@ devture_traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
 
 Traefik will manage SSL certificates for all services seamlessly.
 
-**Note**: for a while longer, our old reverse-proxy (`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 near future, we'll be able to run without nginx, but we're not there yet.
 
 ### Traefik managed by you
 
 ```yaml
 matrix_playbook_reverse_proxy_type: other-traefik-container
 
-matrix_playbook_reverse_proxyable_services_additional_network: your-traefik-network
+# Uncomment and adjust if your Traefik container is on another network
+# matrix_playbook_reverse_proxy_container_network: traefik
+
+# Adjust to point to your Traefik container
+matrix_playbook_reverse_proxy_hostname: name-of-your-traefik-container
 
 devture_traefik_certs_dumper_ssl_dir_path: "/path/to/your/traefiks/acme.json/directory"
 
 # Uncomment and tweak the variable below if the name of your federation entrypoint is different
 # than the default value (matrix-federation).
-# matrix_federation_traefik_entrypoint: matrix-federation
+# matrix_federation_traefik_entrypoint_name: matrix-federation
 ```
 
 In this mode all roles will still have Traefik labels attached. You will, however, need to configure your Traefik instance and its entrypoints.
 
-By default, the playbook congiures services use a `web-secure` (443) and `matrix-federation` (8448) entrypoints, as well as a `default` certificate resolver.
+By default, the playbook configured a `default` certificate resolver and multiple entrypoints.
 
-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`).
+You need to configure 4 entrypoints for your Traefik server:
+
+- `web` (TCP port `80`) - used for redirecting to HTTPS (`web-secure`)
+- `web-secure` (TCP port `443`) - used for exposing the Matrix Client-Server API and all other services
+- `matrix-federation` (TCP port `8448`) - used for exposing the Matrix Federation API
+- `matrix-internal-matrix-client-api` (TCP port `8008`) - used internally for addon services (bridges, bots) to communicate with the homserver
 
 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:
+Note that this configuration on its own does **not** redirect traffic on port 80 (plain HTTP) to port 443 for HTTPS. If you are not already doing this in Traefik, it can be added to Traefik in a [file provider](https://docs.traefik.io/v2.0/providers/file/) as follows:
 
 ```toml
 [http]
@@ -86,6 +98,7 @@ services:
       - "--providers.docker.exposedbydefault=false"
       - "--entrypoints.web-secure.address=:443"
       - "--entrypoints.matrix-federation.address=:8448"
+      - "--entrypoints.matrix-internal-matrix-client-api.address=:8008"
       - "--certificatesresolvers.default.acme.tlschallenge=true"
       - "--certificatesresolvers.default.acme.email=YOUR EMAIL"
       - "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
@@ -109,9 +122,9 @@ 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
+- (recommended) [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) - using the playbook-managed reverse-proxy (Traefik), but 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)
+- (difficult) [Using no reverse-proxy on the Matrix side at all](#using-no-reverse-proxy-on-the-matrix-side-at-all) disabling the playbook-managed reverse-proxy (Traefik), exposing services one by one using `_host_bind_port` variables and forwarding traffic from your own webserver to those ports
 
 
 ### Fronting the integrated reverse-proxy webserver with another reverse-proxy
@@ -120,9 +133,9 @@ This method is about leaving the integrated reverse-proxy webserver be, but maki
 
 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).
+You can disable such behavior and make the integrated reverse-proxy webserver only serve traffic locally on the host itself (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.
+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 then 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:
 
@@ -132,7 +145,9 @@ 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
+# Disable the web-secure (port 443) endpoint, which also disables SSL certificate retrieval.
+# This has the side-effect of also automatically disabling TLS for the matrix-federation entrypoint
+# (by toggling `matrix_federation_traefik_entrypoint_tls`).
 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`
@@ -154,7 +169,7 @@ devture_traefik_config_entrypoint_web_forwardedHeaders_insecure: true
 # If your reverse-proxy runs on another machine, consider:
 # - using `0.0.0.0:8449`, just `8449` or `SOME_IP_ADDRESS_OF_THIS_MACHINE:8449` below
 # - adjusting `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom` (below) - removing `insecure: true` and enabling/configuring `trustedIPs`
-matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: 127.0.0.1:8449
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: '127.0.0.1:8449'
 
 # Depending on the value of `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port` above,
 # this may need to be reconfigured. See the comments above.
@@ -164,67 +179,22 @@ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
   # 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).
+Such a configuration would expose all services on a local port `81` and Matrix Federation on a local port `8449`.
+
+Your reverse-proxy configuration needs to send traffic to these ports. The [`examples/reverse-proxies` directory](../examples/reverse-proxies/) contains sample configuration for various webservers (Apache2, Caddy, HAproxy, nginx, Nginx Proxy Manager).
+
+It's important that these webservers proxy-pass requests to the correct place and also set the `Host` HTTP header appropriately.
+If you don't pass the `Host` header correctly, you would get a 404 not found error from Traefik.
+
+To put it another way, `curl http://127.0.0.1:81` would give you a 404, but `curl -H 'Host: matrix.DOMAIN' http://127.0.0.1:81` should work.
 
 
 ### 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.
+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 Traefik reverse-proxy. You would then need to reverse-proxy from your own webserver directly to each individual Matrix service.
 
 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.
+Also, the Traefik reverse-proxy, besides fronting everything is also serving a 2nd purpose of allowing addons services to communicate with the Matrix homeserver thanks to its `matrix-internal-matrix-client-api` entrypoint (read more about it above). Disabling Traefik completely means the playbook would wire services to directly talk to the homeserver. This can work for basic setups, but not for more complex setups involving [matrix-media-repo](./configuring-playbook-matrix-media-repo.md), [matrix-corporal](./configuring-playbook-matrix-corporal.md) or other such services that need to "steal routes" from the homeserver.
 
-#### 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 near 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.
+If your webserver is on the same machine, ensure 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, so that it can serve static files from `/matrix/static-files`.

docs/configuring-playbook-pantalaimon.md

@@ -0,0 +1,21 @@
+# Setting up pantalaimon (optional)
+
+The playbook can install and configure the [pantalaimon](https://github.com/matrix-org/pantalaimon) E2EE aware proxy daemon for you.
+
+See the project's [documentation](https://github.com/matrix-org/pantalaimon) to learn what it does and why it might be useful to you.
+
+This role exposes Pantalaimon's API only within the container network, so bots and clients installed on the same machine can use it. In particular the [Draupnir](configuring-playbook-bot-draupnir.md) and [Mjolnir](configuring-playbook-bot-mjolnir.md) roles (and possibly others) can use it.
+
+## 1. Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+matrix_pantalaimon_enabled: true
+```
+
+The default configuration should suffice. For advanced configuration, you can override the variables documented in the role's [defaults](../roles/custom/matrix-pantalaimon/defaults/main.yml).
+
+## 2. Installing
+
+After configuring the playbook, run the [installation](installing.md) command.

docs/configuring-playbook-prometheus-grafana.md

@@ -61,43 +61,29 @@ Most of our docker containers run with limited system access, but the `prometheu
 
 When you'd like **to collect metrics from an external Prometheus server**, you need to expose service metrics outside of the container network.
 
-The playbook provides a single endpoint (`https://matrix.DOMAIN/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/hookshot`, etc). To enable this `/metrics/*` feature, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled` below.
+The playbook provides a single endpoint (`https://matrix.DOMAIN/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/hookshot`, etc). To expose all services on this `/metrics/*` feature, use `matrix_metrics_exposure_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` below.
+
+When using `matrix_metrics_exposure_enabled`, you don't need to expose metrics for individual services one by one.
 
 The following variables may be of interest:
 
 Name | Description
 -----|----------
-`matrix_nginx_proxy_proxy_matrix_metrics_enabled`|Set this to `true` to enable metrics exposure for various services on `https://matrix.DOMAIN/metrics/*`. Refer to the individual `matrix_SERVICE_metrics_proxying_enabled` variables below for exposing metrics for each individual service.
-`matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.DOMAIN/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials). When enabled, all endpoints beneath `/metrics` will be protected with the same credentials
-`matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_username`|Set this to the Basic Authentication username you'd like to protect `/metrics/*` with. You also need to set `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password`. If one username/password pair is not enough, you can leave the `username` and `password` variables unset and use `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_raw_content` instead
-`matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password`|Set this to the Basic Authentication password you'd like to protect `/metrics/*` with
-`matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_raw_content`|Set this to the Basic Authentication credentials (raw `htpasswd` file content) used to protect `/metrics/*`. This htpasswd-file needs to be generated with the `htpasswd` tool and can include multiple username/password pairs. If you only need one credential, use `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_username` and `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_password` instead.
+`matrix_metrics_exposure_enabled`|Set this to `true` to **enable metrics exposure for all services** on `https://matrix.DOMAIN/metrics/*`. If you think this is too much, refer to the helpful (but nonexhaustive) list of individual `matrix_SERVICE_metrics_proxying_enabled` (or similar) variables below for exposing metrics on a per-service basis.
+`matrix_metrics_exposure_http_basic_auth_enabled`|Set this to `true` to protect all `https://matrix.DOMAIN/metrics/*` endpoints with [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) (see the other variables below for supplying the actual credentials). When enabled, all endpoints beneath `/metrics` will be protected with the same credentials
+`matrix_metrics_exposure_http_basic_auth_users`|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.
 `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_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`. Read [below](#collecting-synapse-worker-metrics-to-an-external-prometheus-server) if you're running a Synapse worker setup (`matrix_synapse_workers_enabled: true`). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
 `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_node_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
 `prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
+`prometheus_postgres_exporter_container_labels_traefik_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
 `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_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`. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above.
+`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. To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` above or `matrix_SERVICE_container_labels_metrics_middleware_basic_auth_enabled`/`matrix_SERVICE_container_labels_metrics_middleware_basic_auth_users` variables provided by each role.
 `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
-matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks:
-  - 'location /metrics/another-service {
-  resolver 127.0.0.11 valid=5s;
-  proxy_pass http://matrix-another-service:9100/metrics;
-  }'
-```
-
-Using `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks` only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true` (see above).
-
-Note : The playbook will hash the basic_auth password for you on setup. Thus, you need to give the plain-text version of the password as a variable.
-
 ### Collecting Synapse worker metrics to an external Prometheus server
 
 If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.DOMAIN/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`.
@@ -133,7 +119,7 @@ scrape_configs:
 
 ## More information
 
-- [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/matrix-org/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
-- [The Prometheus scraping rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus) (we use v2)
-- [The Synapse Grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana)
+- [Understanding Synapse Performance Issues Through Grafana Graphs](https://github.com/element-hq/synapse/wiki/Understanding-Synapse-Performance-Issues-Through-Grafana-Graphs) at the Synapse Github Wiki
+- [The Prometheus scraping rules](https://github.com/element-hq/synapse/tree/master/contrib/prometheus) (we use v2)
+- [The Synapse Grafana dashboard](https://github.com/element-hq/synapse/tree/master/contrib/grafana)
 - [The Node Exporter dashboard](https://github.com/rfrail3/grafana-dashboards) (for generic non-synapse performance graphs)

docs/configuring-playbook-prometheus-nginxlog.md

@@ -1,34 +1,34 @@
 # Enabling metrics and graphs for NginX logs (optional)
 
-It can be useful to have some (visual) insight into NignX logs.
+It can be useful to have some (visual) insight into [nginx](https://nginx.org/) 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`
+This adds [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) to your Matrix deployment.
+
+It will collect access logs from various nginx reverse-proxies which may be used internally (e.g. `matrix-synapse-reverse-proxy-companion`, if Synapse workers are enabled) and will make them available at a Prometheus-compatible `/metrics` endpoint.
+
+**NOTE**: nginx is only used internally by this Ansible playbook. With Traefik being our default reverse-proxy, collecting nginx metrics is less relevant.
+
+To make use of this, you need to install [Prometheus](./configuring-playbook-prometheus-grafana.md) either via the playbook or externally. When using an external Prometheus, configuration adjustments are necessary - see [Save metrics on an external Prometheus server](#save-metrics-on-an-external-prometheus-server).
+
+If your setup includes [Grafana](./configuring-playbook-prometheus-grafana.md), a dedicated `NGINX PROXY` Grafana dashboard will be created.
+
+## Configuration
 
 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.
+Then, re-run the playbook. See [installation](./installing.md).
 
 ## 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
+The playbook currently does not support [self-building](./self-building.md) a container image on other architectures.
+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
@@ -41,19 +41,14 @@ 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 playbook will automatically integrate the metrics into the [Prometheus](./configuring-playbook-prometheus-grafana.md) server provided with this playbook (if enabled). In such cases, the metrics endpoint is not exposed publicly - it's only available on the container network.
 
-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
+When using an external Prometheus server, you'll need to expose metrics publicly. See [Collecting metrics to an external Prometheus server](./configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server).
 
-# 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`.
+You can either use `matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled: true` to expose just this one service, or `matrix_metrics_exposure_enabled: true` to expose all services.
+
+Whichever way you go with, this service will expose its metrics endpoint **without password-protection** at `https://matrix.DOMAIN/metrics/nginxlog` by default.
+
+For password-protection, use (`matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`) or (`matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_enabled` and `matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_users`).
 
-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

@@ -16,7 +16,7 @@ Name | Description
 `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`)
+`prometheus_postgres_exporter_container_labels_traefik_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). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page.
 
 
 ## More information

docs/configuring-playbook-rageshake.md

@@ -20,8 +20,6 @@ matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}"
 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
 

docs/configuring-playbook-riot-web.md

@@ -25,15 +25,10 @@ There are a few options for handling this:
 
 - (**avoiding changes** - using the old `riot.DOMAIN` domain and avoiding DNS changes) -- to keep using `riot.DOMAIN` instead of `element.DOMAIN`, override the domain at which the playbook serves Element: `matrix_server_fqn_element: "riot.{{ matrix_domain }}"`
 
-- (**embracing changes** - using only `element.DOMAIN`) - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.DOMAIN` in this case. If so, you may also wish to remove old SSL certificates (`rm -rf /matrix/ssl/config/live/riot.DOMAIN`) and renewal configuration (`rm -f /matrix/ssl/config/renewal/riot.DOMAIN.conf`), so that `certbot` would stop trying to renew them.
-
-- (**embracing changes and transitioning smoothly** - using both `element.DOMAIN` and `riot.DOMAIN`) - to serve Element at the new domain (`element.DOMAIN`) and to also have `riot.DOMAIN` redirect there - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)) and enable Riot to Element redirection (`matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`).
+- (**embracing changes** - using only `element.DOMAIN`) - set up the `element.DOMAIN` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.DOMAIN` in this case.
 
 
 ### Re-running the playbook
 
-As always, after making the necessary DNS and configuration adjustments, re-run the playbook to apply the changes:
-
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+As always, after making the necessary DNS and configuration adjustments, [re-run the playbook](./installing.md) to apply the changes.
 ```

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

@@ -10,8 +10,6 @@ Element X iOS is [available on TestFlight](https://testflight.apple.com/join/uZb
 
 Element X Android is [available on the Github Releases page](https://github.com/element-hq/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

docs/configuring-playbook-sygnal.md

@@ -26,8 +26,6 @@ matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}"
 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
 

docs/configuring-playbook-synapse-admin.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) for you.
 
-It's a web UI tool you can use to **administrate users and rooms on your Matrix server**.
+It's a web UI tool you can use to **administrate users and rooms on your Matrix server**. It's designed to work with the Synapse homeserver implementation, but to some extent may work with [Dendrite](./configuring-playbook-dendrite.md) as well.
 
 See the project's [documentation](https://github.com/Awesome-Technologies/synapse-admin) to learn what it does and why it might be useful to you.
 
@@ -15,7 +15,10 @@ 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://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`).
+**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/element-hq/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, the playbook **automatically** exposes the Synapse Admin API publicly for you. Depending on the homeserver implementation you're using (Synapse, Dendrite), this is equivalent to:
+
+- for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true`
+- for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true`
 
 
 ## Installing
@@ -34,15 +37,3 @@ After installation, Synapse Admin will be accessible at: `https://matrix.DOMAIN/
 To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server.
 
 The Homeserver URL to use on Synapse Admin's login page is: `https://matrix.DOMAIN`
-
-### Sample configuration for running behind Caddy v2
-
-Below is a sample configuration for using this playbook with a [Caddy](https://caddyserver.com/v2) 2.0 reverse proxy (non-default configuration where `matrix-nginx-proxy` is disabled - `matrix_nginx_proxy_enabled: false`).
-
-```caddy
-# This is a basic configuration that will function the same as the default nginx proxy - exposing the synapse-admin panel to matrix.YOURSERVER.com/synapse-admin/
-  handle_path /synapse-admin* {
-        reverse_proxy localhost:8766  {
-        }
-  }
-```

docs/configuring-playbook-synapse-auto-accept-invite.md

@@ -0,0 +1,24 @@
+# Setting up Synapse Auto Invite Accept (optional)
+
+The playbook can install and configure [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) for you.
+
+See that project's [documentation](https://github.com/matrix-org/synapse-auto-accept-invite) to learn what it does and why it might be useful to you.
+In short, it automatically accepts room invites. You can specify that only 1:1 room invites are auto-accepted. Defaults to false if not specified.
+
+If you decide that you'd like to let this playbook install it for you, you need a configuration like this:
+
+```yaml
+matrix_synapse_ext_synapse_auto_accept_invite_enabled: true
+
+matrix_synapse_ext_synapse_auto_accept_invite_accept_invites_only_direct_messages: true
+```
+
+## Synapse worker deployments
+
+In a [workerized Synapse deployment](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/c9a842147e09647c355799ca024d65a5de66b099/docs/configuring-playbook-synapse.md#load-balancing-with-workers) it is possible to run this module on a worker to reduce the load on the main process (Default is 'null'). For example add this to your configuration:
+
+```yaml
+matrix_synapse_ext_synapse_auto_accept_invite_worker_to_run_on: 'matrix-synapse-worker-generic-0'
+```
+
+There might be an [issue with federation](https://github.com/matrix-org/synapse-auto-accept-invite/issues/18).

docs/configuring-playbook-synapse.md

@@ -1,6 +1,6 @@
 # Configuring Synapse (optional)
 
-By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, so that it works for the general case.
+By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, so that it works for the general case.
 If that's enough for you, you can skip this document.
 
 The playbook provides lots of customization variables you could use to change Synapse's settings.
@@ -20,22 +20,65 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
 
 ## Load balancing with workers
 
-To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/matrix-org/synapse/blob/master/docs/workers.md).
+To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html).
 
 To enable Synapse worker support, update your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_synapse_workers_enabled: true
+
+matrix_synapse_workers_preset: one-of-each
 ```
 
-We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration):
-- `little-federation-helper` - a very minimal worker configuration to improve federation performance
-- `one-of-each` - one worker of each supported type
+By default, this enables the `one-of-each` [worker preset](#worker-presets), but you may wish to use another preset or [control the number of worker instances](#controlling-the-number-of-worker-instances).
 
-If you'd like more customization power, you can start with one of the presets and tweak various `matrix_synapse_workers_*_count` variables manually.
+### Worker presets
+
+We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration right now):
+
+- (federation-only) `little-federation-helper` - a very minimal worker configuration to improve federation performance
+- (generic) `one-of-each` - defaults to one worker of each supported type - no smart routing, just generic workers
+- (specialized) `specialized-workers` - defaults to one worker of each supported type, but disables generic workers and uses [specialized workers](#specialized-workers) instead
+
+These presets represent a few common configurations. There are many worker types which can be mixed and matched based on your needs.
+
+#### Generic workers
+
+Previously, the playbook only supported the most basic type of load-balancing. We call it **generic load-balancing** below, because incoming HTTP requests are sent to a generic worker. Load-balancing was done based on the requestor's IP address. This is simple, but not necessarily optimal. If you're accessing your account from multiple IP addresses (e.g. your mobile phone being on a different network than your PC), these separate requests may potentially be routed to different workers, each of which would need to cache roughly the same data.
+
+This is **still the default load-balancing method (preset) used by the playbook**.
+
+To use generic load-balancing, do not specify `matrix_synapse_workers_preset` to make it use the default value (`one-of-each`), or better yet - explicitly set it as `one-of-each`.
+
+You may also consider [tweaking the number of workers of each type](#controlling-the-number-of-worker-instances) from the default (one of each).
+
+#### Specialized workers
+
+The playbook now supports a smarter **specialized load-balancing** inspired by [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html). Instead of routing requests to one or more [generic workers](#generic-workers) based only on the requestor's IP adddress, specialized load-balancing routes to **4 different types of specialized workers** based on **smarter criteria** - the access token (username) of the requestor and/or on the resource (room, etc.) being requested.
+
+The playbook supports these **4 types** of specialized workers:
+
+- Room workers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) & [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs dedicated to handling specific rooms
+- Sync workers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs related to synchronization (most notably [the `/sync` endpoint](https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3sync))
+- Client readers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs which are not for specific rooms (handled by **room workers**) or for synchronization (handled by **sync workers**)
+- Federation readers - handles various [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs which are not for specific rooms (handled by **room workers**)
+
+To use specialized load-balancing, consider enabling the `specialized-workers` [worker preset](#worker-presets) and potentially [tweaking the number of workers of each type](#controlling-the-number-of-worker-instances) from the default (one of each).
+
+#### Controlling the number of worker instances
+
+If you'd like more customization power, you can start with one of the [worker presets](#worker-presets) and then tweak various `matrix_synapse_workers_*_count` variables manually.
+
+To find what variables are available for you to override in your own `vars.yml` configuration file, see the [`defaults/main.yml` file for the `matrix-synapse` Ansible role](../roles/custom/matrix-synapse/defaults/main.yml).
+
+The only thing you **cannot** do is mix [generic workers](#generic-workers) and [specialized workers](#specialized-workers).
+
+#### Effect of enabling workers on the rest of your server
 
 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.
 
+A separate Ansible role (`matrix-synapse-reverse-proxy-companion`) and component handles load-balancing for workers. This role/component is automatically enabled when you enable workers. Make sure to use the `setup-all` tag (not `install-all`!) during the playbook's [installation](./installing.md) process, especially if you're disabling workers, so that components may be installed/uninstalled correctly.
+
 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-*'`.
 
 
@@ -46,38 +89,39 @@ Certain Synapse administration tasks (managing users and rooms, etc.) can be per
 
 ## Synapse + OpenID Connect for Single-Sign-On
 
-If you'd like to use OpenID Connect authentication with Synapse, you'll need some additional reverse-proxy configuration (see [our nginx reverse-proxy doc page](configuring-playbook-nginx.md#synapse-openid-connect-for-single-sign-on)).
+If you'd like to use OpenID Connect authentication with Synapse, you'll need some additional configuration.
 
 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).
+For more detailed documentation on available options and how to setup keycloak, see the [Synapse documentation on OpenID Connect with keycloak](https://github.com/element-hq/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 ;
 
-```
-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
+```yml
+matrix_synapse_oidc_enabled: true
+
+matrix_synapse_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**.
+[Templates](https://github.com/element-hq/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)).
+This playbook allows you to customize the default templates (see the [`synapse/res/templates` directory](https://github.com/element-hq/synapse/tree/develop/synapse/res/templates)).
 
 If template customization is enabled, the playbook will build a custom container image based on the official one.
 

docs/configuring-playbook-telemetry.md

@@ -12,9 +12,9 @@ growth of the Matrix community, and helps to make Matrix a success.
 If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
 
 ```yaml
-matrix_synapse_report_stats: true # for synapse 
+matrix_synapse_report_stats: true # for synapse
 
-matrix_dendrite_report_stats: true # for dendrite 
+matrix_dendrite_report_stats: true # for dendrite
 ```
 
 
@@ -24,5 +24,5 @@ When enabled, your homeserver will regularly upload a few dozen statistics about
 This data includes your homeserver's domain, the total number of users, the number of active
 users, the total number of rooms, and the number of messages sent per day on your homeserver.
 
-See [Synapse's documentation](https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics) or [Dendrite's documentation](https://github.com/matrix-org/dendrite/blob/main/docs/FAQ.md#what-is-being-reported-when-enabling-phone-home-statistics)
+See [Synapse's documentation](https://github.com/element-hq/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics) or [Dendrite's documentation](https://github.com/matrix-org/dendrite/blob/main/docs/FAQ.md#what-is-being-reported-when-enabling-phone-home-statistics)
 for the full list of statistics that are reported.

docs/configuring-playbook-traefik.md

@@ -35,7 +35,7 @@ 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.
+**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
 
@@ -48,3 +48,114 @@ devture_traefik_configuration_extension_yaml: |
   api:
     dashboard: true
 ```
+
+## Reverse-proxying another service behind Traefik
+
+The preferred way to reverse-proxy additional services behind Traefik would be to start the service as another container, configure the container with the corresponding Traefik [container labels](https://docs.docker.com/config/labels-custom-metadata/) (see [Traefik & Docker](https://doc.traefik.io/traefik/routing/providers/docker/)), and connect the service to the `traefik` network. Some services are also already available via the compatible [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook), but take a look at the minor [interoperability adjustments](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/interoperability.md).
+
+However, if your service does not run on a container or runs on another machine, the following configuration might be what you are looking for.
+
+## Reverse-proxying a remote HTTP/HTTPS service behind Traefik
+
+If you want to host another webserver would be reachable via `my-fancy-website.mydomain.com` from the internet and via `https://<internal webserver IP address>:<internal port>` from inside your network, you can make the playbook's integrated Traefik instance reverse-proxy the traffic to the correct host.
+
+Prerequisites: DNS and routing for the domain `my-fancy-website.mydomain.com` need to be set up correctly. In this case, you'd be pointing the domain name to your Matrix server - `my-fancy-website.mydomain.com` would be a CNAME going to `matrix.example.com`.
+
+First, we have to adjust the static configuration of Traefik, so that we can add additional configuration files:
+
+```yaml
+# We enable all config files in the /config/ folder to be loaded.
+# `/config` is the path as it appears in the Traefik container.
+# On the host, it's actually `/matrix/traefik/config` (as defined in `devture_traefik_config_dir_path`).
+devture_traefik_configuration_extension_yaml: |
+  providers:
+    file:
+      directory: /config/
+      watch: true
+      filename: ""
+```
+
+If you are using a self-signed certificate on your webserver, you can tell Traefik to trust your own backend servers by adding more configuration to the static configuration file. If you do so, bear in mind the security implications of disabling the certificate validity checks towards your back end.
+
+```yaml
+# We enable all config files in the /config/ folder to be loaded and
+devture_traefik_configuration_extension_yaml: |
+  providers:
+    file:
+      directory: /config/
+      watch: true
+      filename: ""
+  serversTransport:
+    insecureSkipVerify: true
+```
+
+
+Next, you have to add a new dynamic configuration file for Traefik that contains the actual information of the server using the `aux_file_definitions` variable. In this example, we will terminate SSL at the Traefik instance and connect to the other server via HTTPS. Traefik will now take care of managing the certificates. 
+
+```yaml
+aux_file_definitions:
+  - dest: "{{ devture_traefik_config_dir_path }}/provider_my_fancy_website.yml"
+    content: |
+      http:
+        routers:
+          webserver-router:
+            rule: Host(`my_fancy_website.mydomain.com`)
+            service: webserver-service
+            tls:
+              certResolver: default
+        services:
+          webserver-service:
+            loadBalancer:
+              servers:
+                - url: "https://<internal webserver IP address>:<internal port>"
+```
+Changing the `url` to one with an `http://` prefix would allow to connect to the server via HTTP.
+
+## Reverse-proxying another service behind Traefik without terminating SSL
+
+If you do not want to terminate SSL at the Traefik instance (for example, because you're already terminating SSL at other webserver), you need to adjust the static configuration in the same way as in the previous chapter in order to be able to add our own dynamic configuration files. Afterwards, you can add the following configuration to your `vars.yml` configuration file:
+
+```yaml
+aux_file_definitions:
+  - dest: "{{ devture_traefik_config_dir_path }}/providers_my_fancy_website.yml"
+    content: |
+      tcp:
+        routers:
+          webserver-router:
+            rule: Host(`my_fancy_website.mydomain.com`)
+            service: webserver-service
+            tls:
+              passthrough: true
+        services:
+          webserver-service:
+            loadBalancer:
+              servers:
+                - url: "https://<internal webserver IP address>:<internal port>"
+```
+Changing the `url` to one with an `http://` prefix would allow to connect to the server via HTTP.
+
+With these changes, all TCP traffic will be reverse-proxied to the target system. 
+
+**WARNING**: This configuration might lead to problems or need additional steps when a [certbot](https://certbot.eff.org/) behind Traefik also tries to manage [Let's Encrypt](https://letsencrypt.org/) certificates, as Traefik captures all traffic to ```PathPrefix(`/.well-known/acme-challenge/`)```. 
+
+
+## Traefik behind a `proxy_protocol` reverse-proxy
+
+If you run a reverse-proxy which speaks `proxy_protocol`, add the following to your configuration file:
+
+```yaml
+devture_traefik_configuration_extension_yaml: |
+  entryPoints:
+    web-secure:
+      proxyProtocol:
+        trustedIPs:
+          - "127.0.0.1/32"
+          - "<proxy internal IPv4>/32"
+          - "<proxy IPv6>/128"
+    matrix-federation:
+        proxyProtocol:
+          trustedIPs:
+            - "127.0.0.1/32"
+            - "<proxy internal IPv4>/32"
+            - "<proxy IPv6>/128"
+```

docs/configuring-playbook-turn.md

@@ -34,6 +34,21 @@ If your server has multiple external IP addresses, the Coturn role offers a diff
 matrix_coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']
 ```
 
+## Changing the authentication mechanism
+
+The playbook uses the [`auth-secret` authentication method](https://github.com/coturn/coturn/blob/873cabd6a2e5edd7e9cc5662cac3ffe47fe87a8e/README.turnserver#L186-L199) by default, but you may switch to the [`lt-cred-mech` method](https://github.com/coturn/coturn/blob/873cabd6a2e5edd7e9cc5662cac3ffe47fe87a8e/README.turnserver#L178) which [some report](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3191) to be working better.
+
+To do so, add this override to your configuration:
+
+```yml
+matrix_coturn_authentication_method: lt-cred-mech
+```
+
+Regardless of the selected authentication method, the playbook generates secrets automatically and passes them to the homeserver and Coturn.
+
+If you're using [Jitsi](./configuring-playbook-jitsi.md), note that switching to `lt-cred-mech` will remove the integration between Jitsi and your own Coturn server, because Jitsi only seems to support the `auth-secret` authentication method.
+
+
 ## Using your own external Coturn server
 
 If you'd like to use another TURN server (be it Coturn or some other one), you can configure the playbook like this:

docs/configuring-playbook.md

@@ -8,7 +8,7 @@ To configure the playbook, you need to have done the following things:
 
 You can then follow these steps inside the playbook directory:
 
-1. create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
+1. create a directory to hold your configuration (`mkdir -p inventory/host_vars/matrix.<your-domain>`)
 
 1. copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
 
@@ -65,8 +65,6 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Configure the Traefik reverse-proxy](configuring-playbook-traefik.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)
@@ -107,7 +105,9 @@ 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)
+- [Setting up Matrix User Verification Service](configuring-playbook-user-verification-service.md) (optional, advanced)
+
+- [Setting up Pantalaimon (E2EE aware proxy daemon)](configuring-playbook-pantalaimon.md) (optional, advanced)
 
 
 ### Bridging other networks
@@ -122,13 +122,17 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Mautrix Whatsapp bridging](configuring-playbook-bridge-mautrix-whatsapp.md) (optional)
 
-- [Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md) (optional)
+- [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md) (optional)
+
+- [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md) (optional)
+
+- ~~[Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md)~~ - consider bridging to Facebook/Messenger using the new [mautrix-meta-messenger](./configuring-playbook-bridge-mautrix-meta-messenger.md) bridge (optional)
 
 - [Setting up Mautrix Hangouts bridging](configuring-playbook-bridge-mautrix-hangouts.md) (optional)
 
 - [Setting up Mautrix Google Chat bridging](configuring-playbook-bridge-mautrix-googlechat.md) (optional)
 
-- [Setting up Mautrix Instagram bridging](configuring-playbook-bridge-mautrix-instagram.md) (optional)
+- ~~[Setting up Mautrix Instagram bridging](configuring-playbook-bridge-mautrix-instagram.md)~~ - consider bridging to Instagram using the new [mautrix-meta-instagram](./configuring-playbook-bridge-mautrix-meta-instagram.md) bridge (optional)
 
 - [Setting up Mautrix Twitter bridging](configuring-playbook-bridge-mautrix-twitter.md) (optional)
 
@@ -193,6 +197,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [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 Draupnir for all](configuring-playbook-appservice-draupnir-for-all.md) - like the [Draupnir bot](configuring-playbook-bot-draupnir.md) mentioned above, but running in appservice mode and supporting multiple instances (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)
 
 

docs/configuring-well-known.md

@@ -40,15 +40,15 @@ To learn how to set it up, read the Installing section below.
 
 [MSC 1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929) specifies a way to add contact details of admins, as well as a link to a support page for users who are having issues with the service. Automated services may also index this information and use it for abuse reports, etc.
 
-The two playbook variables that you could look for, if you're interested in being an early adopter, are: `matrix_homeserver_admin_contacts` and `matrix_homeserver_support_url`.
+The two playbook variables that you could look for, if you're interested in being an early adopter, are: `matrix_static_files_file_matrix_support_property_m_contacts` and `matrix_static_files_file_matrix_support_property_m_support_page`.
 
 Example snippet for `vars.yml`:
 ```
 # Enable generation of `/.well-known/matrix/support`.
-matrix_well_known_matrix_support_enabled: true
+matrix_static_files_file_matrix_support_enabled: true
 
 # Homeserver admin contacts as per MSC 1929 https://github.com/matrix-org/matrix-spec-proposals/pull/1929
-matrix_homeserver_admin_contacts:
+matrix_static_files_file_matrix_support_property_m_contacts:
   - matrix_id: "@admin1:{{ matrix_domain }}"
     email_address: admin@domain.tld
     role: m.role.admin
@@ -58,7 +58,7 @@ matrix_homeserver_admin_contacts:
   - email_address: security@domain.tld
     role: m.role.security
 
-matrix_homeserver_support_url: "https://example.domain.tld/support"
+matrix_static_files_file_matrix_support_property_m_support_page: "https://example.domain.tld/support"
 ```
 
 To learn how to set up `/.well-known/matrix/support` for the base domain, read the Installing section below.

docs/container-images.md

@@ -9,7 +9,7 @@ We try to stick to official images (provided by their respective projects) as mu
 
 These services are enabled and used by default, but you can turn them off, if you wish.
 
-- [matrixdotorg/synapse](https://hub.docker.com/r/matrixdotorg/synapse/) - the official [Synapse](https://github.com/matrix-org/synapse) Matrix homeserver (optional)
+- [matrixdotorg/synapse](https://hub.docker.com/r/matrixdotorg/synapse/) - the official [Synapse](https://github.com/element-hq/synapse) Matrix homeserver (optional)
 
 - [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) - the [Coturn](https://github.com/coturn/coturn) STUN/TURN server (optional)
 
@@ -108,13 +108,15 @@ These services are not part of our default installation, but can be enabled by [
 
 - [matrixdotorg/mjolnir](https://hub.docker.com/r/matrixdotorg/mjolnir) - the [mjolnir](https://github.com/matrix-org/mjolnir) moderation bot (optional)
 
+- [gnuxie/draupnir](https://hub.docker.com/r/gnuxie/draupnir) - the [Draupnir](https://github.com/the-draupnir-project/Draupnir/) moderation bot (optional)
+
 - [awesometechnologies/synapse-admin](https://hub.docker.com/r/awesometechnologies/synapse-admin) - the [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) web UI tool for administrating users and rooms on your Matrix server (optional)
 
 - [prom/prometheus](https://hub.docker.com/r/prom/prometheus/) - [Prometheus](https://github.com/prometheus/prometheus/) is a systems and service monitoring system
 
 - [prom/node-exporter](https://hub.docker.com/r/prom/node-exporter/) - [Prometheus Node Exporter](https://github.com/prometheus/node_exporter/) is an addon for Prometheus that gathers standard system metrics
 
-- [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) - [Grafana](https://github.com/grafana/grafana/) is a graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/matrix-org/synapse/tree/master/contrib/grafana) and  [Node Exporter](https://github.com/rfrail3/grafana-dashboards)
+- [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) - [Grafana](https://github.com/grafana/grafana/) is a graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/element-hq/synapse/tree/master/contrib/grafana) and  [Node Exporter](https://github.com/rfrail3/grafana-dashboards)
 
 - [matrixdotorg/sygnal](https://hub.docker.com/r/matrixdotorg/sygnal/) - [Sygnal](https://github.com/matrix-org/sygnal) is a reference Push Gateway for Matrix
 

docs/faq.md

@@ -61,7 +61,7 @@ There are 3 ways to get into Martix, depending on your technical ability and nee
 
 ### How do I set up my own Matrix server?
 
-Normally, you'd first choose the [Matrix](https://matrix.org/) server software you'd like to run. At the time of this writing (January/2021), there's only one fully-featured server program, so there's only one reasonable choice. That's [Synapse](https://github.com/matrix-org/synapse).
+Normally, you'd first choose the [Matrix](https://matrix.org/) server software you'd like to run. At the time of this writing (January/2021), there's only one fully-featured server program, so there's only one reasonable choice. That's [Synapse](https://github.com/element-hq/synapse).
 
 There are [many guides about installing Synapse](https://matrix.org/docs/guides/#installing-synapse). Using this Ansible playbook is just one way of doing it.
 
@@ -82,13 +82,13 @@ To learn more, see our [dedicated Ansible documentation page](ansible.md).
 
 ### Why use this playbook and not install Synapse and other things manually?
 
-There are various guides telling you how easy it is to install [Synapse](https://github.com/matrix-org/synapse).
+There are various guides telling you how easy it is to install [Synapse](https://github.com/element-hq/synapse).
 
 Reading the documentation of this Ansible playbook, you may also be thinking:
 
 > I don't know what [Ansible](https://www.ansible.com/) is. I don't know what [Docker](https://www.docker.com/) is. This looks more complicated.
 
-.. so you may be leaning toward [installing Synapse manually](https://github.com/matrix-org/synapse/blob/master/INSTALL.md).
+.. so you may be leaning toward [installing Synapse manually](https://github.com/element-hq/synapse/blob/master/INSTALL.md).
 
 The problem with a manual installation is:
 

docs/howto-server-delegation.md

@@ -43,7 +43,7 @@ This prevents you from suffering the [Downsides of well-known-based Server Deleg
 
 To use DNS SRV record validation, you need to:
 
-- ensure that `/.well-known/matrix/server` is **not served** from the base domain, as that would interfere with DNS SRV record Server Delegation. To make the playbook **not** generate and serve the file, use the following configuration: `matrix_well_known_matrix_server_enabled: false`.
+- ensure that `/.well-known/matrix/server` is **not served** from the base domain, as that would interfere with DNS SRV record Server Delegation. To make the playbook **not** generate and serve the file, use the following configuration: `matrix_static_files_file_matrix_server_enabled: false`.
 
 - ensure that you have a `_matrix._tcp` DNS SRV record for your base domain (`<your-domain>`) with a value of `10 0 8448 matrix.<your-domain>`
 
@@ -67,52 +67,28 @@ Regardless of which method for obtaining certificates you've used, once you've m
 
 Based on your setup, you have different ways to go about it:
 
-- [Serving the Federation API with your certificates and matrix-nginx-proxy](#serving-the-federation-api-with-your-certificates-and-matrix-nginx-proxy)
-
-- [Serving the Federation API with your certificates and another webserver](#serving-the-federation-api-with-your-certificates-and-another-webserver)
-
-- [Serving the Federation API with your certificates and Synapse handling Federation](#serving-the-federation-api-with-your-certificates-and-synapse-handling-federation)
+- [Server Delegation](#server-delegation)
+	- [Server Delegation via a well-known file](#server-delegation-via-a-well-known-file)
+		- [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation)
+	- [Server Delegation via a DNS SRV record (advanced)](#server-delegation-via-a-dns-srv-record-advanced)
+		- [Obtaining certificates](#obtaining-certificates)
+		- [Serving the Federation API with your certificates](#serving-the-federation-api-with-your-certificates)
+		- [Serving the Federation API with your certificates and another webserver](#serving-the-federation-api-with-your-certificates-and-another-webserver)
+		- [Serving the Federation API with your certificates and Synapse handling Federation](#serving-the-federation-api-with-your-certificates-and-synapse-handling-federation)
 
 
-### Serving the Federation API with your certificates and matrix-nginx-proxy
-
-**If you are using matrix-nginx-proxy**, a reverse-proxy webserver used by default in this playbook, you only need to override the certificates used for the Matrix Federation API. You can do that using:
-
-```yaml
-# Adjust paths below to point to your certificate.
-#
-# NOTE: these are in-container paths. `/matrix/ssl` on the host is mounted into the container
-# at the same path (`/matrix/ssl`) by default, so if that's the path you need, it would be seamless.
-matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate: /matrix/ssl/config/live/<your-domain>/fullchain.pem
-matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: /matrix/ssl/config/live/<your-domain>/privkey.pem
-```
-
-If your files are not in `/matrix/ssl` but in some other location, you would need to mount them into the container:
-
-```yaml
-matrix_nginx_proxy_container_extra_arguments:
-  - "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
-```
-
-You then refer to them (for `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate` and `matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key`) by using `/some/path/inside/the/container`.
-
-Make sure to reload matrix-nginx-proxy once in a while (`systemctl reload matrix-nginx-proxy`), so that newer certificates can kick in.
-Reloading doesn't cause any downtime.
 
 
 ### Serving the Federation API with your certificates and another webserver
 
-**If you are NOT using matrix-nginx-proxy**, but rather some other webserver, you can set up reverse-proxying for the `tcp/8448` port by yourself.
+**If you are using some other webserver**, you can set up reverse-proxying for the `tcp/8448` port by yourself.
 Make sure to use the proper certificates for `<your-domain>` (not for `matrix.<your-domain>`) when serving the `tcp/8448` port.
 
-Proxying needs to happen to `127.0.0.1:8048` (unencrypted Synapse federation listener).
-
-Make sure to reload/restart your webserver once in a while, so that newer certificates can kick in.
-
+As recommended in our [Fronting the integrated reverse-proxy webserver with another reverse-proxy](./configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) documentation section, we recommend you to expose the Matrix Federation entrypoint from traffic at a local port (e.g. `127.0.0.1:8449`), so your reverese-proxy should send traffic there.
 
 ### Serving the Federation API with your certificates and Synapse handling Federation
 
-**Alternatively**, if you are **NOT using matrix-nginx-proxy** and **would rather not use your own webserver for Federation traffic**, you can let Synapse handle Federation by itself.
+**Alternatively**, you can let Synapse handle Federation by itself.
 
 To do that, make sure the certificate files are mounted into the Synapse container:
 

docs/howto-srv-server-delegation.md

@@ -1,6 +1,6 @@
 # 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. 
+**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.
 
@@ -16,11 +16,18 @@ The up-to-date list can be accessed on [traefik's documentation](https://doc.tra
 
 ## The changes
 
+**NOTE**: the changes below instruct you how to do this for a basic Synapse installation. You will need to adapt the variable name and the content of the labels:
+
+- if you're using another homeserver implementation (e.g. [Conduit](./configuring-playbook-conduit.md) or [Dendrite](./configuring-playbook-dendrite.md))
+- if you're using [Synapse with workers enabled](./configuring-playbook-synapse.md#load-balancing-with-workers) (`matrix_synapse_workers_enabled: true`). In that case, it's actually the `matrix-synapse-reverse-proxy-companion` service which has Traefik labels attached
+
+Also, all instructions below are from an older version of the playbook and may not work anymore.
+
 ### 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`)
+# To serve the federation from any domain, as long as the path matches
+matrix_synapse_container_labels_public_federation_api_traefik_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.
@@ -29,13 +36,13 @@ This is because with SRV federation, some servers / tools (one of which being th
 
 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.
+This is because the matrix specification expects the federation endpoint to be served using a certificate compatible 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"
+matrix_synapse_container_labels_additional_labels: |
+  traefik.http.routers.matrix-synapse-federation-api.tls.domains.main="example.com"
+  traefik.http.routers.matrix-synapse-federation-api.tls.domains.sans="*.example.com"
 ```
 
 ### Configure the DNS-01 challenge for let's encrypt
@@ -60,7 +67,7 @@ devture_traefik_configuration_extension_yaml: |
         email: {{ devture_traefik_config_certificatesResolvers_acme_email | to_json }}
         dnsChallenge:
           provider: cloudflare
-          resolvers: 
+          resolvers:
             - "1.1.1.1:53"
             - "8.8.8.8:53"
         storage: {{ devture_traefik_config_certificatesResolvers_acme_storage | to_json }}
@@ -95,21 +102,6 @@ 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 []
-    )
-    +
     (
       [
        {
@@ -134,13 +126,13 @@ matrix_coturn_container_additional_volumes: |
 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 serve the federation from any domain, as long as the path matches
+matrix_synapse_container_labels_public_federation_api_traefik_rule: PathPrefix(`/_matrix/federation`)
 
 # 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"
+matrix_synapse_container_labels_additional_labels: |
+  traefik.http.routers.matrix-synapse-federation-api.tls.domains.main="example.com"
+  traefik.http.routers.matrix-synapse-federation-api.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: |
@@ -152,7 +144,7 @@ devture_traefik_configuration_extension_yaml: |
         email: {{ devture_traefik_config_certificatesResolvers_acme_email | to_json }}
         dnsChallenge:
           provider: cloudflare
-          resolvers: 
+          resolvers:
             - "1.1.1.1:53"
             - "8.8.8.8:53"
         storage: {{ devture_traefik_config_certificatesResolvers_acme_storage | to_json }}
@@ -173,21 +165,6 @@ 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 []
-    )
-    +
     (
       [
        {

docs/maintenance-and-troubleshooting.md

@@ -4,22 +4,27 @@
 
 You can check the status of your services by using `systemctl status`. Example:
 ```
-sudo systemctl status matrix-nginx-proxy
+sudo systemctl status matrix-synapse
 
-● matrix-nginx-proxy.service - Matrix nginx proxy server
-   Loaded: loaded (/etc/systemd/system/matrix-nginx-proxy.service; enabled; vendor preset: enabled)
-   Active: active (running) since Wed 2018-11-14 19:38:35 UTC; 49min ago
+● matrix-synapse.service - Synapse server
+     Loaded: loaded (/etc/systemd/system/matrix-synapse.service; enabled; vendor preset: enabled)
+     Active: active (running) since Sun 2024-01-14 09:13:06 UTC; 1h 31min ago
 ```
 
-You can see the logs by using journalctl. Example:
-```
+Docker containers that the playbook configures are supervised by [systemd](https://wiki.archlinux.org/title/Systemd) and their logs are configured to go to [systemd-journald](https://wiki.archlinux.org/title/Systemd/Journal).
+
+To prevent double-logging, Docker logging is disabled by explicitly passing `--log-driver=none` to all containers. Due to this, you **cannot** view logs using `docker logs`.
+
+To view systemd-journald logs using [journalctl](https://man.archlinux.org/man/journalctl.1), run a command like this:
+
+```sh
 sudo journalctl -fu matrix-synapse
 ```
 
 
 ## Increasing Synapse logging
 
-Because the [Synapse](https://github.com/matrix-org/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`.
+Because the [Synapse](https://github.com/element-hq/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`.
 
 If you'd like to debug an issue or [report a Synapse bug](https://github.com/matrix-org/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increasing the logging level to `INFO`.
 

docs/maintenance-postgres.md

@@ -87,8 +87,6 @@ This playbook can upgrade your existing Postgres setup with the following comman
 just run-tags upgrade-postgres
 ```
 
-**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"`
 

docs/maintenance-synapse.md

@@ -14,13 +14,13 @@ Table of contents:
 
 ## Purging old data with the Purge History API
 
-You can use the **[Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md)** to delete old messages on a per-room basis. **This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.
+You can use the **[Purge History API](https://github.com/element-hq/synapse/blob/master/docs/admin_api/purge_history_api.md)** to delete old messages on a per-room basis. **This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.
 
-To make use of this API, **you'll need an admin access token** first. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+To make use of this Synapse Admin API, **you'll need an admin access token** first. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
-Synapse's Admin API is not exposed to the internet by default. To expose it you will need to add `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true` to your `vars.yml` file.
+Synapse's Admin API is not exposed to the internet by default, following [official Synapse reverse-proxying recommendations](https://github.com/element-hq/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints). To expose it you will need to add `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` to your `vars.yml` file.
 
-Follow the [Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md) documentation page for the actual purging instructions.
+Follow the [Purge History API](https://github.com/element-hq/synapse/blob/master/docs/admin_api/purge_history_api.md) documentation page for the actual purging instructions.
 
 After deleting data, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
 
@@ -47,7 +47,7 @@ After state compression, you may wish to run a [`FULL` Postgres `VACUUM`](./main
 
 ## Browse and manipulate the database
 
-When the [Synapse Admin API](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) and the other tools do not provide a more convenient way, having a look at synapse's postgresql database can satisfy a lot of admins' needs.
+When the [Synapse Admin API](https://github.com/element-hq/synapse/tree/master/docs/admin_api) and the other tools do not provide a more convenient way, having a look at synapse's postgresql database can satisfy a lot of admins' needs.
 
 Editing the database manually is not recommended or supported by the Synapse developers. If you are going to do so you should [make a database backup](./maintenance-postgres.md#backing-up-postgresql).
 
@@ -74,8 +74,32 @@ Synapse's presence feature which tracks which users are online and which are off
 
 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](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 also need to tune Postgres manually.
 
-[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.
+### Tuning caches and cache autotuning
+
+Tuning Synapse's cache factor is useful for performance increases but also as part of controlling Synapse's memory use. Use the variable `matrix_synapse_caches_global_factor` to set the cache factor as part of this process.
+
+**The playbook defaults the global cache factor to a large value** (e.g. `10`). A smaller value (e.g. `0.5`) will decrease the amount used for caches, but will [not necessarily decrease RAM usage as a whole](https://github.com/matrix-org/synapse/issues/3939).
+
+Tuning the cache factor is useful only to a limited degree (as its crude to do in isolation) and therefore users who are tuning their cache factor should likely look into tuning autotune variables as well (see below).
+
+Cache autotuning is **enabled by default** and controlled via the following variables:
+
+- `matrix_synapse_cache_autotuning_max_cache_memory_usage` - defaults to 1/8 of total RAM with a cap of 2GB; values are specified in bytes
+- `matrix_synapse_cache_autotuning_target_cache_memory_usage` - defaults to 1/16 of total RAM with a cap of 1GB; values are specified in bytes
+- `matrix_synapse_cache_autotuning_min_cache_ttl` - defaults to `30s`
+
+You can **learn more about cache-autotuning and the global cache factor settings** in the [Synapse's documentation on caches and associated values](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#caches-and-associated-values).
+
+To **disable cache auto-tuning**, unset all values:
+
+```yml
+matrix_synapse_cache_autotuning_max_cache_memory_usage: ''
+matrix_synapse_cache_autotuning_target_cache_memory_usage: ''
+matrix_synapse_cache_autotuning_min_cache_ttl: ''
+```
+
+Users who wish to lower Synapse's RAM footprint should look into lowering the global cache factor and tweaking the autotune variables (or disabling auto-tuning). If your cache factor is too low for a given auto tune setting your caches will not reach autotune thresholds and autotune won't be able to do its job. Therefore, when auto-tuning is enabled (which it is by default), it's recommended to have your cache factor be large.
 
 See also [How do I optimize this setup for a low-power server?](faq.md#how-do-i-optimize-this-setup-for-a-low-power-server).

docs/prerequisites.md

@@ -2,11 +2,11 @@
 
 To install Matrix services using this Ansible playbook, you need:
 
-- (Recommended) An **x86** server ([What kind of server specs do I need?](faq.md#what-kind-of-server-specs-do-i-need)) running one of these operating systems:
-  - **CentOS** (7 only for now; [8 is not yet supported](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/300))
-  - **Debian** (10/Buster or newer)
-  - **Ubuntu** (18.04 or newer, although [20.04 may be problematic](ansible.md#supported-ansible-versions))
+- (Recommended) An **x86** server ([What kind of server specs do I need?](faq.md#what-kind-of-server-specs-do-i-need)) running one of these operating systems that make use of [systemd](https://systemd.io/):
   - **Archlinux**
+  - **CentOS**, **Rocky Linux**, **AlmaLinux**, or possibly other RHEL alternatives (although your mileage may vary)
+  - **Debian** (10/Buster or newer)
+  - **Ubuntu** (18.04 or newer, although [20.04 may be problematic](ansible.md#supported-ansible-versions) if you run the Ansible playbook on it)
 
 Generally, newer is better. We only strive to support released stable versions of distributions, not betas or pre-releases. This playbook can take over your whole server or co-exist with other services that you have there.
 

docs/self-building.md

@@ -40,6 +40,7 @@ Possibly outdated list of roles where self-building the Docker image is currentl
 - `matrix-bot-matrix-reminder-bot`
 - `matrix-bot-maubot`
 - `matrix-email2matrix`
+- `matrix-pantalaimon`
 
 Adding self-building support to other roles is welcome. Feel free to contribute!
 

docs/updating-users-passwords.md

@@ -32,7 +32,7 @@ where `<password-hash>` is the hash returned by the docker command above.
 
 ## Option 3:
 
-Use the Synapse User Admin API as described here: https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#reset-password
+Use the Synapse User Admin API as described here: https://github.com/element-hq/synapse/blob/master/docs/admin_api/user_admin_api.rst#reset-password
 
 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.*
 

examples/apache/README.md

@@ -1,17 +0,0 @@
-# Apache reverse-proxy
-
-This directory contains sample files that show you how to do reverse-proxying using Apache.
-
-This is for when you wish to have your own Apache webserver sitting in front of Matrix services installed by this playbook.
-See the [Using your own webserver, instead of this playbook's nginx proxy](../../docs/configuring-playbook-own-webserver.md) documentation page.
-
-To use your own Apache reverse-proxy, you first need to disable the integrated nginx server.
-You do that with the following custom configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
-
-```yaml
-matrix_nginx_proxy_enabled: false
-```
-
-You can then use the configuration files from this directory as an example for how to configure your Apache server.
-
-**NOTE**: this is just an example and may not be entirely accurate. It may also not cover other use cases (enabling various services or bridges requires additional reverse-proxying configuration).

examples/apache/matrix-dimension.conf

@@ -1,41 +0,0 @@
-# This is a sample file demonstrating how to set up reverse-proxy for dimension.DOMAIN.
-# If you're not using Dimension (`matrix_dimension_enabled: false`, which is also the default), you won't need this.
-
-<VirtualHost *:80>
-	ServerName dimension.DOMAIN
-
-	ProxyVia On
-
-	# Map /.well-known/acme-challenge to the certbot server
-	# If you manage SSL certificates by yourself, this will differ.
-	<Location /.well-known/acme-challenge>
-		ProxyPreserveHost On
-		ProxyPass http://127.0.0.1:2402/.well-known/acme-challenge
-	</Location>
-
-	Redirect permanent / https://dimension.DOMAIN/
-</VirtualHost>
-
-<VirtualHost *:443>
-	ServerName dimension.DOMAIN
-
-	SSLEngine On
-
-	# If you manage SSL certificates by yourself, these paths will differ.
-	SSLCertificateFile /matrix/ssl/config/live/dimension.DOMAIN/fullchain.pem
-	SSLCertificateKeyFile /matrix/ssl/config/live/dimension.DOMAIN/privkey.pem
-
-	SSLProxyEngine on
-	SSLProxyProtocol +TLSv1.2 +TLSv1.3
-	SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
-
-	ProxyPreserveHost On
-	ProxyRequests Off
-	ProxyVia On
-
-	ProxyPass / http://127.0.0.1:8184/
-	ProxyPassReverse / http://127.0.0.1:8184/
-
-	ErrorLog ${APACHE_LOG_DIR}/dimension.DOMAIN-error.log
-	CustomLog ${APACHE_LOG_DIR}/dimension.DOMAIN-access.log combined
-</VirtualHost>

examples/apache/matrix-synapse.conf

@@ -1,146 +0,0 @@
-# This is a sample file demonstrating how to set up reverse-proxy for matrix.DOMAIN
-
-<VirtualHost *:80>
-	ServerName matrix.DOMAIN
-
-	ProxyVia On
-
-	# Map /.well-known/acme-challenge to the certbot server
-	# If you manage SSL certificates by yourself, this will differ.
-	<Location /.well-known/acme-challenge>
-		ProxyPreserveHost On
-		ProxyPass http://127.0.0.1:2402/.well-known/acme-challenge
-	</Location>
-
-	Redirect permanent / https://matrix.DOMAIN/
-</VirtualHost>
-
-# Client-Server API
-<VirtualHost *:443>
-	ServerName matrix.DOMAIN
-
-	SSLEngine On
-
-	# If you manage SSL certificates by yourself, these paths will differ.
-	SSLCertificateFile /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem
-	SSLCertificateKeyFile /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem
-
-	SSLProxyEngine on
-	SSLProxyProtocol +TLSv1.2 +TLSv1.3
-	SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
-
-	ProxyPreserveHost On
-	ProxyRequests Off
-	ProxyVia On
-	RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
-
-	# Keep some URIs free for different proxy/location
-	ProxyPassMatch ^/.well-known/matrix/client !
-	ProxyPassMatch ^/.well-known/matrix/server !
-	ProxyPassMatch ^/.well-known/matrix/support !
-	ProxyPassMatch ^/_matrix/identity !
-	ProxyPassMatch ^/_matrix/client/r0/user_directory/search !
-
-	# Proxy all remaining traffic to Synapse
-	AllowEncodedSlashes NoDecode
-	ProxyPass /_matrix http://127.0.0.1:8008/_matrix retry=0 nocanon
-	ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
-	ProxyPass /_synapse/client http://127.0.0.1:8008/_synapse/client retry=0 nocanon
-	ProxyPassReverse /_synapse/client http://127.0.0.1:8008/_synapse/client
-
-	# Proxy Admin API (necessary for Synapse-Admin)
-	# ProxyPass /_synapse/admin http://127.0.0.1:8008/_synapse/admin retry=0 nocanon
-	# ProxyPassReverse /_synapse/admin http://127.0.0.1:8008/_synapse/admin
-
-	# Proxy Synapse-Admin
-	# ProxyPass /synapse-admin http://127.0.0.1:8766 retry=0 nocanon
-	# ProxyPassReverse /synapse-admin http://127.0.0.1:8766
-
-	# Map /.well-known/matrix/client for client discovery
-	Alias /.well-known/matrix/client /matrix/static-files/.well-known/matrix/client
-	<Files "/matrix/static-files/.well-known/matrix/client">
-		Require all granted
-	</Files>
-	<Location "/.well-known/matrix/client">
-		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">
-		Require all granted
-	</Files>
-	<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:
-		Require all granted
-		# Or for Apache 2.2:
-		#order allow,deny
-	</Directory>
-
-	# Map /_matrix/identity to the identity server
-	<Location /_matrix/identity>
-		ProxyPass http://127.0.0.1:8090/_matrix/identity nocanon
-	</Location>
-
-	# Map /_matrix/client/r0/user_directory/search to the identity server
-	<Location /_matrix/client/r0/user_directory/search>
-		ProxyPass http://127.0.0.1:8090/_matrix/client/r0/user_directory/search nocanon
-	</Location>
-
-	ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log
-	CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined
-</VirtualHost>
-
-# Server-Server (federation) API
-# Use this apache reverse proxy template to enable matrix server-to-server federation traffic
-# Be sure that network traffic on port 8448 is possible
-#
-# You can check your federation config at https://federationtester.matrix.org/
-# Enter there your base DOMAIN address, NOT your matrix.DOMAIN address, ex. https://DOMAIN
-#
-# In this example we use all services on the same machine (127.0.0.1) but you can do this with different machines.
-# If you do so be sure to reach the destinated IPADRESS and the correspondending port. Check this with netstat, nmap or your favourite tool.
-Listen 8448
-<VirtualHost *:8448>
-	ServerName matrix.DOMAIN
-
-	SSLEngine On
-
-	# If you manage SSL certificates by yourself, these paths will differ.
-	SSLCertificateFile /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem
-	SSLCertificateKeyFile /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem
-
-	SSLProxyEngine on
-	SSLProxyProtocol +TLSv1.2 +TLSv1.3
-	SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
-
-	ProxyPreserveHost On
-	ProxyRequests Off
-	ProxyVia On
-	RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
-
-	# Proxy all remaining traffic to the Synapse port
-	# Beware: In this example the local traffic goes to the local synapse server at 127.0.0.1
-	# Of course you can use another IPADRESS in case of using other synapse servers in your network
-	AllowEncodedSlashes NoDecode
-	ProxyPass /_matrix http://127.0.0.1:8048/_matrix retry=0 nocanon
-	ProxyPassReverse /_matrix http://127.0.0.1:8048/_matrix
-
-	ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log
-	CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined
-</VirtualHost>

examples/caddy/matrix-client-element

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

examples/caddy/matrix-dimension

@@ -1,9 +0,0 @@
-https://dimension.DOMAIN {
-	# These might differ if you are supplying your own certificates
-	# If you wish to use Caddy's built-in Let's Encrypt support, you can also supply an email address here
-	tls /matrix/ssl/config/live/dimension.DOMAIN/fullchain.pem /matrix/ssl/config/live/dimension.DOMAIN/privkey.pem
-
-	proxy / http://127.0.0.1:8184/ {
-		transparent
-	}
-}

examples/caddy/matrix-synapse

@@ -1,31 +0,0 @@
-https://matrix.DOMAIN {
-	# If you use your own certificates, your path may differ
-	# If you wish to use Caddy's built-in Let's Encrypt support, you can also supply an email address here
-	tls /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem
-
-	root /matrix/static-files
-
-	header / {
-		Access-Control-Allow-Origin *
-		Strict-Transport-Security "mag=age=31536000;"
-		X-Frame-Options "DENY"
-		X-XSS-Protection "1; mode=block"
-	}
-
-	# Identity server traffic
-	proxy /_matrix/identity matrix-ma1sd:8090 {
-		transparent
-	}
-	proxy /_matrix/client/r0/user_directory/search matrix-ma1sd:8090 {
-		transparent
-	}
-
-	# Synapse Client<>Server API
-	proxy /_matrix matrix-synapse-reverse-proxy-companion:8008 {
-		transparent
-		except /_matrix/identity/ /_matrix/client/r0/user_directory/search
-	}
-	proxy /_synapse/client matrix-synapse-reverse-proxy-companion:8008 {
-		transparent
-	}
-}

examples/caddy/matrix-util

@@ -1,7 +0,0 @@
-:80 {
-	# Redirect ACME-Challenge traffic to port 2402
-	proxy /.well-known/acme-challenge http://127.0.0.1:2402
-
-	# Redirect all other traffic to HTTPS
-	redir /  https://{host}{uri} 301
-}

examples/caddy2/Caddyfile.deprecated

@@ -1,269 +0,0 @@
-(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,20 +0,0 @@
-# Caddy reverse-proxy fronting the playbook's integrated Traefik reverse-proxy
-
-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.
-
-
-## 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/haproxy/Dockerfile

@@ -1,12 +0,0 @@
-# Pull nginx base image
-FROM nginx:latest
-
-# Expost port 80
-EXPOSE 80
-
-# Copy custom configuration file from the current directory
-COPY nginx.conf /etc/nginx/nginx.conf
-
-# Start up nginx server
-CMD ["nginx"]
-

examples/haproxy/README.md

@@ -1,26 +0,0 @@
-# HAproxy reverse-proxy
-
-This directory contains sample files that show you how to do reverse-proxying using HAproxy.
-
-This is for when you wish to have your own HAproxy instance sitting in front of Matrix services installed by this playbook.
-See the [Using your own webserver, instead of this playbook's nginx proxy](../../docs/configuring-playbook-own-webserver.md) documentation page.
-
-To use your own HAproxy reverse-proxy, you first need to disable the integrated Nginx server.
-You do that with the following custom configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
-
-```yaml
-matrix_nginx_proxy_enabled: false
-```
-
-You can then use the configuration files from this directory as an example for how to configure your HAproxy reverse proxy.
-
-**NOTE**: this is just an example and may not be entirely accurate. It may also not cover other use cases or performance needs.
-
-### Configuration
-
-HAproxy, unlike Apache, Nginx and others, does not provide you with a webserver to serve static files (i.e., `/.well-known/` directory). For this reason, in this folder you can find an example on how to use HAproxy together with a simple Nginx container whose only task is to serve those files.
-
-* Build the Docker image. `docker build -t local/nginx .` 
-* Start the container. `docker-compose up -d`. Note that if you want to run Nginx on a different port, you will have to change the port both in the `docker-compose.yml` and in `haproxy.cfg`.
-* If you don't want to use a wildcard certificate, you will need to modify the corresponding line in the HTTPS frontent and add the paths of all the specific certificates (as for the commented example in `haproxy.cfg`).
-* Start HAproxy with the proposed configuration.

examples/haproxy/docker-compose.yml

@@ -1,9 +0,0 @@
----
-version: '3'
-services:
-  nginx:
-    image: local/nginx
-    ports:
-      - 40888:80
-    volumes:
-      - /matrix/static-files:/var/www/:ro

examples/haproxy/nginx.conf

@@ -1,15 +0,0 @@
-worker_processes auto;
-daemon off;
-
-events {
-  worker_connections 1024;
-}
-
-http {
-  server_tokens off;
-  server {
-    listen 80;
-    index index.html;
-    root /var/www;
-  }
-}

examples/reverse-proxies/README.md

@@ -0,0 +1,5 @@
+## Using other reverse-proxies for fronting the integrated Traefik reverse-proxy
+
+This directory contains sample configuration for various webservers, showing you how to put these reverse-proxies in front of the integrated Traefik reverse-proxy used by the playbook.
+
+To learn more, see [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).

examples/reverse-proxies/apache/README.md

@@ -0,0 +1,14 @@
+# Apache reverse-proxy
+
+This directory contains sample files that show you how to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver with your Apache 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 Apache configuration
+
+`matrix-domain.conf` contains configuration for the Matrix domain, which handles both the Client-Server API (port `443`) and the Matrix Federation API (port `8448`).
+
+`matrix-client-element.conf` is an example for when you're hosting Element at `element.DOMAIN`.
+This configuration can also be used as an example for handling other domains, depending on the services you enable with the playbook (e.g. `dimension.DOMAIN`, etc).

examples/reverse-proxies/apache/matrix-client-element.conf

@@ -4,14 +4,8 @@
 <VirtualHost *:80>
 	ServerName element.DOMAIN
 
-	ProxyVia On
-
-	# Map /.well-known/acme-challenge to the certbot server
-	# If you manage SSL certificates by yourself, this will differ.
-	<Location /.well-known/acme-challenge>
-		ProxyPreserveHost On
-		ProxyPass http://127.0.0.1:2402/.well-known/acme-challenge
-	</Location>
+	# You may wish to handle the /.well-known/acme-challenge paths here somehow,
+	# if you're using ACME (Let's Encrypt) certificates.
 
 	Redirect permanent / https://element.DOMAIN/
 </VirtualHost>
@@ -33,8 +27,8 @@
 	ProxyRequests Off
 	ProxyVia On
 
-	ProxyPass / http://127.0.0.1:8765/
-	ProxyPassReverse / http://127.0.0.1:8765/
+	ProxyPass / http://127.0.0.1:81/
+	ProxyPassReverse / http://127.0.0.1:81/
 
 	ErrorLog ${APACHE_LOG_DIR}/element.DOMAIN-error.log
 	CustomLog ${APACHE_LOG_DIR}/element.DOMAIN-access.log combined

examples/reverse-proxies/apache/matrix-domain.conf

@@ -0,0 +1,65 @@
+# This is a sample file demonstrating how to set up reverse-proxy for matrix.DOMAIN
+
+<VirtualHost *:80>
+	ServerName matrix.DOMAIN
+
+	# You may wish to handle the /.well-known/acme-challenge paths here somehow,
+	# if you're using ACME (Let's Encrypt) certificates.
+
+	Redirect permanent / https://matrix.DOMAIN/
+</VirtualHost>
+
+# Client-Server API
+<VirtualHost *:443>
+	ServerName matrix.DOMAIN
+
+	SSLEngine On
+
+	# If you manage SSL certificates by yourself, these paths will differ.
+	SSLCertificateFile /path/to/matrix.DOMAIN/fullchain.pem
+	SSLCertificateKeyFile /path/to/matrix.DOMAIN/privkey.pem
+
+	SSLProxyEngine on
+	SSLProxyProtocol +TLSv1.2 +TLSv1.3
+	SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
+
+	ProxyPreserveHost On
+	ProxyRequests Off
+	ProxyVia On
+	RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+
+	AllowEncodedSlashes NoDecode
+	ProxyPass / http://127.0.0.1:81/ retry=0 nocanon
+	ProxyPassReverse / http://127.0.0.1:81/
+
+	ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log
+	CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined
+</VirtualHost>
+
+# Server-Server (federation) API
+Listen 8448
+<VirtualHost *:8448>
+	ServerName matrix.DOMAIN
+
+	SSLEngine On
+
+	# If you manage SSL certificates by yourself, these paths will differ.
+	SSLCertificateFile /matrix/ssl/config/live/matrix.DOMAIN/fullchain.pem
+	SSLCertificateKeyFile /matrix/ssl/config/live/matrix.DOMAIN/privkey.pem
+
+	SSLProxyEngine on
+	SSLProxyProtocol +TLSv1.2 +TLSv1.3
+	SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
+
+	ProxyPreserveHost On
+	ProxyRequests Off
+	ProxyVia On
+	RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+
+	AllowEncodedSlashes NoDecode
+	ProxyPass / http://127.0.0.1:8449/ retry=0 nocanon
+	ProxyPassReverse / http://127.0.0.1:8449/
+
+	ErrorLog ${APACHE_LOG_DIR}/matrix.DOMAIN-error.log
+	CustomLog ${APACHE_LOG_DIR}/matrix.DOMAIN-access.log combined
+</VirtualHost>

examples/reverse-proxies/caddy2/README.md

@@ -0,0 +1,16 @@
+# Caddy reverse-proxy fronting the playbook's integrated Traefik reverse-proxy
+
+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.
+
+
+## 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.

examples/reverse-proxies/haproxy/README.md

@@ -0,0 +1,9 @@
+# HAproxy reverse-proxy
+
+This directory contains sample files that show you how to do reverse-proxying using HAproxy.
+
+This is for when you wish to have your own HAproxy instance sitting in front of Matrix services installed by this playbook.
+
+We recommend that you use HAProxy in front of Traefik. See our [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) documentation.
+
+You can then use the configuration files from this directory as an example for how to configure your HAproxy reverse proxy.

examples/reverse-proxies/haproxy/haproxy.cfg

@@ -43,29 +43,16 @@ frontend https-frontend
     reqadd X-Forwarded-Proto:\ https
     option httplog
     option http-server-close
-    #
-    # Matrix
-    #
-    # matrix.example.com
+
+    # You can do per-domain routing (as shown above),
+	# or just send everything to the same backend via `default_backend`.
+
     acl matrix_domain hdr_dom(host) -i matrix.example.com
-    acl static_files path -i -m beg /.well-known/matrix
-    use_backend nginx-static if static_files
-    # /_matrix/identity and /_matrix/client/r0/user_directory/search
-    acl matrix_identity path -i -m beg /_matrix/identity
-    acl matrix_search path -i -m beg /_matrix/client/r0/user_directory/search
-    # Send to :8090
-    use_backend matrix-supporting if matrix_identity or matrix_search
-    # /_matrix and /_synapse/admin
-    acl matrix_path path -i -m beg /_matrix
-    acl synapse_admin path -i -m beg /_synapse/admin
-    # Send to :8008
-    use_backend matrix-main if matrix_path or synapse_admin
-    # element.example.com
-    acl element_domain hdr_dom(host) -i element.example.com
-    # Send to 8765
-    use_backend element if element_domain
-    # If nothing else match, just send to default matrix backend
     use_backend matrix-main if matrix_domain
+
+    acl matrix_domain hdr_dom(host) -i element.example.com
+    use_backend matrix-main if matrix_domain
+
     #default_backend matrix-main
 
 frontend matrix-federation
@@ -75,14 +62,11 @@ frontend matrix-federation
   option http-server-close
   default_backend synapse
 
-backend matrix-supporting
-     server matrix-supporting 127.0.0.1:8090 check
-
 backend matrix-main
-     server matrix-main 127.0.0.1:8008 check
+     server matrix-main 127.0.0.1:81 check
 
-backend synapse
-     server synapse 127.0.0.1:8048 check
+backend matrix-federation
+     server matrix-federation 127.0.0.1:8049 check
 
 backend nginx-static
      capture request header origin len 128

examples/reverse-proxies/nginx-proxy-manager/README.md

@@ -0,0 +1,63 @@
+# Nginx Proxy Manager fronting the playbook's integrated Traefik reverse-proxy
+
+Similar to standard nginx, [Nginx Proxy Manager](https://nginxproxymanager.com/) provides nginx capabilities but inside a pre-built Docker container. With the ability for managing proxy hosts and automatic SSL certificates via a simple web interface.
+
+This page summarizes how to use Nginx Proxy Manager (NPM) to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver.
+
+
+## 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`).
+
+If Matrix federation is enabled, then you will need to make changes to [NPM's Docker configuration](https://nginxproxymanager.com/guide/#quick-setup). By default NPM already exposes ports `80` and `443`, but you would also need to **additionally expose the Matrix Federation port** (as it appears on the public side): `8448`.
+
+
+## Using Nginx Proxy Manager
+
+You'll need to create two proxy hosts in NPM for matrix web and federation traffic.
+
+Open the 'Proxy Hosts' page in the NPM web interface and select `Add Proxy Host`, the first being for matrix web traffic. Apply the proxys configuration like this:
+
+```md
+# Details
+# Matrix web proxy config
+Domain Names: matrix.DOMAIN
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 81
+
+# SSL
+# Either 'Request a new certificate' or select an existing one
+SSL Certificate: matrix.DOMAIN or *.DOMAIN
+Force SSL: true
+HTTP/2 Support: true
+
+# Advanced
+Custom Nginx Configuration:
+	client_max_body_size 50M;
+```
+
+Again, under the 'Proxy Hosts' page select `Add Proxy Host`, this time for your federation traffic. Apply the proxys configuration like this:
+
+```md
+# Details
+# Matrix Federation proxy config
+Domain Names: matrix.DOMAIN:8448
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 8449
+
+# SSL
+# Either 'Request a new certificate' or select an existing one
+SSL Certificate: matrix.DOMAIN or *.DOMAIN
+Force SSL: true
+HTTP/2 Support: true
+
+# Advanced
+# Allows NPM to listen on the federation port
+Custom Nginx Configuration:
+	listen 8448 ssl http2;
+	client_max_body_size 50M;
+```
+
+Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.DOMAIN` or `jitsi.DOMAIN`, which would use the forwarding port `81`.

examples/reverse-proxies/nginx/README.md

@@ -5,7 +5,7 @@ This directory contains a sample config that shows you how to use the [nginx](ht
 
 ## 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`).
+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
@@ -14,4 +14,4 @@ Copy the [matrix.conf](matrix.conf) file to your nginx server's filesystem, modi
 
 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.
+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.

flake.lock

@@ -0,0 +1,60 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1710146030,
+        "narHash": "sha256-SZ5L6eA7HJ/nmkzGG7/ISclqe6oZdOZTNoesiInkXPQ=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "b1d9ab70662946ef0850d488da1c9019f3a9752a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1712578459,
+        "narHash": "sha256-r+rjtYIdwV7mEqFwbvaS7dZSH+3xNW9loR3Rh9C0ifI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "b1a486be09c354e25a18689eb21425e43892e38c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -1,19 +1,30 @@
 {
-  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.passlib
-        ];
-        LC_ALL = "C.UTF-8";
-        LC_CTYPE = "C.UTF-8";
-      };
-    };
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+  outputs = {
+    self,
+    nixpkgs,
+    flake-utils,
+  }:
+    flake-utils.lib.eachDefaultSystem
+    (
+      system: let
+        pkgs = import nixpkgs {
+          inherit system;
+        };
+      in
+        with pkgs; {
+          devShells.default = mkShell {
+            buildInputs = [
+              just
+              ansible
+            ];
+            shellHook = ''
+              echo "$(ansible --version)"
+            '';
+          };
+        }
+    );
 }

gpg/open_vault.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -e -u
+
+gpg2 --batch --use-agent --decrypt $(dirname $0)/vault_passphrase.gpg 2>/dev/null

gpg/vault_passphrase.gpg

@@ -0,0 +1,18 @@
+-----BEGIN PGP MESSAGE-----
+
+hQIMAxEs7W/4x4lxARAAssinIzR2rGs+Qkm0Q2tRdSXSXRx3OhH+2T5p0Rz3YkqU
+iyiUtyT/Ll7RMUAlAEDZITvirXe4ZZImDcxQegEzFgO7BowQYJDRdhaRmLKZpiuQ
+foRnJAAR12sf49arjJjaBQb91ViOp5MkxAtXiiqWyXwSSII+cV88flMq143cFmfC
+C5OdIQd3SqrbFhGRTjUzoIMqnJH8xksjwph9GS811dY14rQv5X1Ybt5zehMJ7/m/
+luLNg2zgQgYOUxcovddCVMI54ThXyDubDox/5xLvVjyVOFHgwC/VLn+QXHuPY/r5
++rVzz/30eq0uOLKD3LnDBQskCWRVWGC2ulKaZtlylBq6KRzIM6c6+VPSHCjoFyES
+RRpRHeIXGLs31eLkr8dc+VNbPKpMsjm/E/4ZVE2JBpy7S/kh1XYVQxT6ahDKT1tD
+4YN9O0JyNXzjiyNaTTLwNGh5+ICEd3ZCfa4O/og2LySGPOw6mX8ukgP029LHVp6+
+0tRwSWiIM3US/NIVGA+o9e9I/I5Bp/cnzJgd7faUIlzcVPP+euCbo4GsYWpX3Nca
+eRcr7AVY3wwuZtl7/s8KbQKk0ulLxS4Lo2XmdpQl8CPGwASdbMf/H8B256+xiUQ3
+ml400ZaCC7Loeduwl1ez1H/dFFzmpUziaxxtWW4aFtOUYhGeSCTu6ZIgxVq3eBnS
+jAGv8bt+0Xnrpih3mZWM92cw2VKfzYD9WG+dCB4DtZMKhl1ub2bkeTC/B9F+QuP6
+anlonYHs2wmPXzjcx8ajonbYrYXanoNRHDId6OqVAbjYqbua6TG6H9LUFweIj1RV
+yhUPejzhA8xEB0nUcKJZKLvuqvwPbr06GODnAKY5TQ4yILMAnBx0pNzfQNzo
+=Cecg
+-----END PGP MESSAGE-----

inventory/host_vars/matrix.finallycoffee.eu/vars.yml

@@ -0,0 +1,385 @@
+#
+# General config
+# Domain of the matrix server and SSL config
+#
+matrix_domain: finallycoffee.eu
+
+matrix_playbook_reverse_proxy_type: playbook-managed-traefik
+matrix_playbook_ssl_enabled: true
+devture_traefik_config_entrypoint_web_secure_enabled: false
+devture_traefik_container_web_host_bind_port: '127.0.10.1:8080'
+devture_traefik_config_entrypoint_web_forwardedHeaders_insecure: true
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: '127.0.10.2:8448'
+matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
+  forwardedHeaders:
+    insecure: true
+
+matrix_synapse_metrics_proxying_enabled: true
+
+matrix_base_data_path: "{{ vault_matrix_base_data_path }}"
+matrix_server_fqn_element: "chat.{{ matrix_domain }}"
+matrix_playbook_docker_installation_enabled: false
+
+#matrix_client_element_version: v1.8.4
+#matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:v1.7.21"
+#matrix_synapse_docker_image: "{{ matrix_synapse_docker_image_name_prefix }}matrixdotorg/synapse:v1.77.0"
+#matrix_synapse_in_container_python_packages_path: "/usr/local/lib/python3.11/site-packages"
+#matrix_synapse_default_room_version: "10"
+matrix_dimension_scheme: https
+
+devture_timesync_installation_enabled: false
+matrix_homeserver_generic_secret_key: "{{ vault_homeserver_generic_secret_key }}"
+devture_systemd_service_manager_up_verification_delay_seconds: 180
+
+web_user: "web"
+revproxy_autoload_dir: "/vault/services/web/sites.d"
+postgres_dump_dir: /vault/temp
+
+
+#
+# General Synapse config
+#
+devture_postgres_connection_password: "{{ vault_matrix_postgres_connection_password }}"
+# A secret used to protect access keys issued by the server.
+# matrix_homeserver_generic_secret_key: "{{ vault_homeserver_generic_secret_key }}"
+# Make synapse accept larger media aswell
+matrix_synapse_max_upload_size_mb: 200
+# Enable metrics at (default) :9100/_synapse/metrics
+matrix_synapse_metrics_enabled: true
+matrix_synapse_turn_shared_secret: "{{ vault_matrix_coturn_turn_static_auth_secret }}"
+matrix_synapse_turn_uris:
+  - "turn:voip.matrix.finallycoffee.eu?transport=udp"
+  - "turn:voip.matrix.finallycoffee.eu?transport=tcp"
+# Auto-join all users into those rooms
+matrix_synapse_auto_join_rooms:
+  - "#welcome:finallycoffee.eu"
+  - "#announcements:finallycoffee.eu"
+
+## Synapse rate limits
+matrix_synapse_rc_federation:
+  window_size: 1000
+  sleep_limit: 50
+  sleep_delay: 500
+  reject_limit: 50
+  concurrent: 10
+matrix_synapse_rc_message:
+  per_second: 0.5
+  burst_count: 25
+matrix_synapse_rc_joins:
+  local:
+    per_second: 0.5
+    burst_count: 20
+  remote:
+    per_second: 0.05
+    burst_count: 20
+matrix_synapse_rc_joins_per_room:
+  per_second: 1
+  burst_count: 10
+matrix_synapse_rc_invites:
+  per_room:
+    per_second: 0.5
+    burst_count: 10
+  per_user:
+    per_second: 0.006
+    burst_count: 10
+  per_issuer:
+    per_second: 2
+    burst_count: 20
+
+## Synapse cache tuning
+matrix_synapse_caches_global_factor: 1.5
+matrix_synapse_event_cache_size: "300K"
+
+## Synapse workers
+matrix_synapse_workers_enabled: true
+matrix_synapse_workers_preset: "little-federation-helper"
+matrix_synapse_workers_generic_workers_count: 1
+matrix_synapse_workers_media_repository_workers_count: 2
+matrix_synapse_workers_federation_sender_workers_count: 2
+matrix_synapse_workers_pusher_workers_count: 1
+matrix_synapse_workers_appservice_workers_count: 1
+
+# Static secret auth for matrix-synapse-shared-secret-auth
+matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
+matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: "{{ vault_matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret }}"
+matrix_synapse_ext_password_provider_rest_auth_enabled: true
+matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-ma1sd:8090"
+matrix_synapse_ext_password_provider_rest_auth_registration_enforce_lowercase: false
+matrix_synapse_ext_password_provider_rest_auth_registration_profile_name_autofill: true
+matrix_synapse_ext_password_provider_rest_auth_login_profile_name_autofill: false
+
+matrix_synapse_configuration_extension_yaml: |
+  database:
+    args:
+      cp_max: 20
+  caches:
+    per_cache_factors:
+      device_id_exists: 3
+      get_users_in_room: 4
+      _get_joined_users_from_context: 4
+      _get_joined_profile_from_event_id: 3
+      "*stateGroupMembersCache*": 2
+      _matches_user_in_member_list: 3
+      get_users_who_share_room_with_user: 3
+      is_interested_in_room: 2
+      get_user_by_id: 1.5
+      room_push_rule_cache: 1.5
+    expire_caches: true
+    cache_entry_ttl: 45m
+    sync_response_cache_duration: 2m
+  
+
+#
+# synapse-admin tool
+#
+matrix_synapse_admin_enabled: true
+matrix_synapse_admin_container_http_host_bind_port: 8985
+
+
+#
+# VoIP / CoTURN config
+#
+# A shared secret (between Synapse and Coturn) used for authentication.
+matrix_coturn_turn_static_auth_secret: "{{ vault_matrix_coturn_turn_static_auth_secret }}"
+# Disable coturn, as we use own instance
+matrix_coturn_enabled: false
+
+
+#
+# dimension (integration manager) config
+#
+matrix_dimension_enabled: true
+matrix_dimension_admins: "{{ vault_matrix_dimension_admins }}"
+matrix_server_fqn_dimension: "dimension.matrix.{{ matrix_domain }}"
+matrix_dimension_access_token: "{{ vault_matrix_dimension_access_token }}"
+matrix_dimension_configuration_extension_yaml: |
+    telegram:
+        botToken: "{{ vault_matrix_dimension_configuration_telegram_bot_token }}"
+
+
+#
+# mautrix-whatsapp config
+#
+matrix_mautrix_whatsapp_enabled: true
+matrix_mautrix_whatsapp_bridge_personal_filtering_spaces: true
+matrix_mautrix_whatsapp_bridge_mute_bridging: true
+matrix_mautrix_whatsapp_bridge_enable_status_broadcast: false
+matrix_mautrix_whatsapp_bridge_allow_user_invite: true
+matrix_mautrix_whatsapp_container_http_monitoring_host_bind_port: 9402
+matrix_mautrix_whatsapp_container_extra_arguments:
+  - "-p 127.0.0.1:{{ matrix_mautrix_whatsapp_container_http_monitoring_host_bind_port }}:{{ matrix_mautrix_whatsapp_container_http_monitoring_host_bind_port }}"
+matrix_mautrix_whatsapp_configuration_extension_yaml: |
+    bridge:
+        displayname_template: "{% raw %}{{.Name}} ({{if .Notify}}{{.Notify}}{{else}}{{.Jid}}{{end}}) (via WhatsApp){% endraw %}"
+        max_connection_attempts: 5
+        connection_timeout: 30
+        contact_wait_delay: 5
+        private_chat_portal_meta: true
+        login_shared_secret: "{{ matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret }}"
+    logging:
+        print_level: info
+    metrics:
+        enabled: true
+        listen: 0.0.0.0:{{ matrix_mautrix_whatsapp_container_http_monitoring_host_bind_port }}
+    whatsapp:
+        os_name: Linux mautrix-whatsapp
+        browser_name: Chrome
+
+
+#
+# mautrix-telegram config
+#
+matrix_mautrix_telegram_enabled: true
+matrix_mautrix_telegram_api_id: "{{ vault_matrix_mautrix_telegram_api_id }}"
+matrix_mautrix_telegram_api_hash: "{{ vault_matrix_mautrix_telegram_api_hash }}"
+matrix_mautrix_telegram_public_endpoint: '/bridge/telegram'
+matrix_mautrix_telegram_container_http_monitoring_host_bind_port: 9401
+matrix_mautrix_telegram_container_http_host_bind_port_public: 8980
+matrix_mautrix_telegram_container_extra_arguments:
+  - "-p 127.0.0.1:{{ matrix_mautrix_telegram_container_http_monitoring_host_bind_port }}:{{ matrix_mautrix_telegram_container_http_monitoring_host_bind_port }}"
+  - "-p 127.0.0.1:{{ matrix_mautrix_telegram_container_http_host_bind_port_public }}:80"
+matrix_mautrix_telegram_configuration_extension_yaml: |
+    bridge:
+        displayname_template: "{displayname} (via Telegram)"
+        parallel_file_transfer: false
+        inline_images: false
+        image_as_file_size: 20
+        delivery_receipts: true
+        login_shared_secret: "{{ matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret }}"
+        animated_sticker:
+            target: webm
+        encryption:
+            allow: true
+            default: true
+        permissions:
+            "@transcaffeine:finallycoffee.eu": "admin"
+            "gruenhage.xyz": "full"
+            "boobies.software": "full"
+    logging:
+        root:
+            level: INFO
+    metrics:
+        enabled: true
+        listen_port: {{ matrix_mautrix_telegram_container_http_monitoring_host_bind_port }}
+#        permissions: "{{ vault_matrix_mautrix_telegram_permission_map | from_yaml }}"
+
+
+#
+# mautrix-signal config
+#
+matrix_mautrix_signal_enabled: true
+matrix_mautrix_signal_container_http_monitoring_host_bind_port: 9408
+matrix_mautrix_signal_container_extra_arguments:
+    - "-p 127.0.0.1:{{ matrix_mautrix_signal_container_http_monitoring_host_bind_port }}:{{ matrix_mautrix_signal_container_http_monitoring_host_bind_port }}"
+matrix_mautrix_signal_configuration_extension_yaml: |
+    bridge:
+        displayname_template: "{displayname} (via Signal)"
+        community_id: "+signal:finallycoffee.eu"
+        encryption:
+            allow: true
+            default: true
+            key_sharing:
+                allow: true
+                require_verification: false
+        delivery_receipts: true
+        permissions:
+          "@ilosai:fairydust.space": "user"
+    logging:
+        root:
+            level: INFO
+    metrics:
+        enabled: true
+        listen_port: {{ matrix_mautrix_signal_container_http_monitoring_host_bind_port }}
+
+
+#
+# mx-puppet-instagram configuration
+#
+matrix_mx_puppet_instagram_enabled: true
+matrix_mx_puppet_instagram_container_http_monitoring_host_bind_port: 9403
+matrix_mx_puppet_instagram_container_extra_arguments:
+  - "-p 127.0.0.1:{{ matrix_mx_puppet_instagram_container_http_monitoring_host_bind_port }}:{{ matrix_mx_puppet_instagram_container_http_monitoring_host_bind_port }}"
+matrix_mx_puppet_instagram_configuration_extension_yaml: |
+    bridge:
+        enableGroupSync: true
+        avatarUrl: mxc://finallycoffee.eu/acmiSAinuHDOULofFFeolTvr
+    metrics:
+        enabled: true
+        port: {{ matrix_mx_puppet_instagram_container_http_monitoring_host_bind_port }}
+        path: /metrics
+    presence:
+        enabled: true
+        interval: 3000
+
+
+#
+# mx-puppet-discord configuration
+#
+matrix_mx_puppet_discord_enabled: false
+matrix_mx_puppet_discord_client_id: "{{ vault_matrix_mx_puppet_discord_client_id }}"
+matrix_mx_puppet_discord_client_secret: "{{ vault_matrix_mx_puppet_discord_client_secret }}"
+matrix_mx_puppet_discord_container_http_monitoring_host_bind_port: 9404
+matrix_mx_puppet_discord_container_extra_arguments:
+  - "-p 127.0.0.1:{{ matrix_mx_puppet_discord_container_http_monitoring_host_bind_port }}:{{ matrix_mx_puppet_discord_container_http_monitoring_host_bind_port }}"
+matrix_mx_puppet_discord_configuration_extension_yaml: |
+    bridge:
+        enableGroupSync: true
+        avatarUrl: mxc://finallycoffee.eu/BxcAAhjXmglMbtthStEHtCzd
+    metrics:
+        enabled: true
+        port: {{ matrix_mx_puppet_discord_container_http_monitoring_host_bind_port }}
+        path: /metrics
+    limits:
+        maxAutojoinUsers: 500
+        roomUserAutojoinDelay: 50
+    presence:
+        enabled: true
+        interval: 3000
+
+
+#
+# mx-puppet-slack configuration
+#
+matrix_mx_puppet_slack_enabled: true
+matrix_mx_puppet_slack_client_id: "{{ vault_matrix_mx_puppet_slack_client_id }}"
+matrix_mx_puppet_slack_client_secret: "{{ vault_matrix_mx_puppet_slack_client_secret }}"
+matrix_mx_puppet_slack_oauth_redirect_path: '/bridge/slack/oauth'
+matrix_mx_puppet_slack_container_http_auth_host_bind_port: 8981
+matrix_mx_puppet_slack_container_http_monitoring_host_bind_port: 9406
+matrix_mx_puppet_slack_container_extra_arguments:
+  - "-p 127.0.0.1:{{ matrix_mx_puppet_slack_container_http_monitoring_host_bind_port }}:{{ matrix_mx_puppet_slack_container_http_monitoring_host_bind_port }}"
+  - "-p 127.0.0.1:{{ matrix_mx_puppet_slack_container_http_auth_host_bind_port }}:8008"
+matrix_mx_puppet_slack_configuration_extension_yaml: |
+    bridge:
+        enableGroupSync: true
+    metrics:
+        enabled: true
+        port: {{ matrix_mx_puppet_slack_container_http_monitoring_host_bind_port }}
+        path: /metrics
+    limits:
+        maxAutojoinUsers: 500
+        roomUserAutojoinDelay: 50
+    presence:
+        enabled: true
+        interval: 3000
+
+
+#
+# Element web configuration
+#
+# Branding config
+matrix_client_element_brand: "Chat"
+matrix_client_element_default_theme: "dark"
+matrix_client_element_themes_enabled: true
+matrix_client_element_welcome_headline: "Welcome to chat.finallycoffee.eu"
+matrix_client_element_welcome_text: |
+    Decentralised, encrypted chat &amp; collaboration,<br />
+    hosted on finallycoffee.eu, powered by element.io &amp;
+    <a href="https://matrix.org" target="_blank" rel="noreferrer noopener">
+      <img width="79" height="34" alt="[matrix]" style="padding-left: 1px;vertical-align: middle" src="welcome/images/matrix.svg" />
+    </a>
+matrix_client_element_welcome_logo: "welcome/images/logo.png"
+matrix_client_element_welcome_logo_link: "https://{{ matrix_domain }}"
+matrix_client_element_branding_auth_header_logo_url: "welcome/images/logo.png"
+matrix_client_element_branding_welcome_background_url: "welcome/images/background.jpg"
+matrix_client_element_container_extra_arguments:
+  - "-v {{ matrix_client_element_data_path }}/background.jpg:/app/{{ matrix_client_element_branding_welcome_background_url }}:ro"
+  - "-v {{ matrix_client_element_data_path }}/logo.png:/app/{{ matrix_client_element_branding_auth_header_logo_url }}:ro"
+# Integration and capabilites config
+matrix_client_element_integrations_ui_url: "https://{{ matrix_server_fqn_dimension }}/element"
+matrix_client_element_integrations_rest_url: "https://{{ matrix_server_fqn_dimension }}/api/v1/scalar"
+matrix_client_element_integrations_widgets_urls:
+  - "https://{{ matrix_server_fqn_dimension }}/widgets"
+  - "https://scalar.vector.im/api"
+matrix_client_element_integrations_jitsi_widget_url: "https://{{ matrix_server_fqn_dimension }}/widgets/jitsi"
+matrix_client_element_disable_custom_urls: false
+matrix_client_element_room_directory_servers:
+  - "matrix.org"
+  - "finallycoffee.eu"
+  - "entropia.de"
+matrix_client_element_enable_presence_by_hs_url:
+  https://matrix.org: false
+
+
+# Matrix ma1sd extended configuration
+matrix_ma1sd_configuration_extension_yaml: |
+    hashing:
+      enabled: true
+      pepperLength: 20
+      rotationPolicy: per_requests
+      requests: 10
+      hashStorageType: sql
+      algorithms:
+          - none
+          - sha256
+
+
+# Matrix mail notification relay setup
+exim_relay_enabled: true
+exim_relay_sender_address: "Matrix on finallycoffee.eu <system-matrix@{{ matrix_domain }}>"
+exim_relay_relay_use: true
+exim_relay_relay_host_name: "{{ vault_matrix_mailer_relay_host_name }}"
+exim_relay_relay_host_port: 587
+exim_relay_relay_auth: true
+exim_relay_relay_auth_username: "{{ vault_matrix_mailer_relay_auth_username }}"
+exim_relay_relay_auth_password: "{{ vault_matrix_mailer_relay_auth_password }}"

inventory/host_vars/matrix.finallycoffee.eu/vault.yml

@@ -0,0 +1,100 @@
+$ANSIBLE_VAULT;1.1;AES256
+39366364363633336238333130353832663162393038633665396333343732353964333363666539
+6562346632343235623835643735386434316666393234360a383634616537393134613631383836
+61333835363666623033306166376232303930306433343366373463653234623736643633383734
+3330333665383539650a383132353032386230393031626361343764323034386230363066306331
+34646236336262623435633566363033613737373064616266336237343233663066396163373034
+62303765353066653737366539626461636531636438323932333134363136363134646164646531
+63656638666233313437663261396665653736373164323433306435323336633938313164646264
+33653661633965363833393031616463633761356234633630643562306366653133366637346166
+38636433343736343461613731623538633361363934343764326466313261353633646230353065
+37366134303164356433333961346663313963626165323966656536313532376162326565383539
+65363333633964323838663461373666353665643236623839646664653661613838353239613137
+39353061323131306365656261343630313665356165623064616436653566373663343733316237
+34393666383465323463313838393465643830373632373938633763666636346539666233303265
+38353337633833373331356663633936326334366337393135653030333531613565643666633038
+64393862303765366632393137313432376563353335353231323464633637343334346634306534
+35613330373336633031376263306466306437656635396133613335386130346163663438386136
+61646437343938663431343736363564376238316666373531616231366132643864346538363866
+35396433366137356162313963666134383134306462313336613735386639363936326131383939
+66623833643433663039623837623133303336666233623935313438366136353332313165333936
+31386632336535383533646639636164313331346630633366383739623261366465656632393062
+63373332623738303364623437666531396331646666336230353333366261653438363861656466
+39333762633037383336393164616563396564383232636533363864636230616664303330323932
+66666234633362346132303932643464366466323535303835363430333737666661373534333934
+61393362616438626636383564613335363634626231663234616438343464383461303632363033
+39336362396339316661323662393665383031643931626333646335643335353661653939363538
+38666561313539613566386132336630643237333432656236356132616230663561343665353938
+33366663353834356434366335373265373439363430636533303933656264366338623232613435
+35356662383232386137313064313363303861326635333435393737643663336534363234623430
+32376432353330613666396337303935376366613564353039396164383361616337656535346166
+34396635356266326461613135303639643935363261396363636338636564643838313262326266
+31663139343336376233303637373864363835313839326433656235616332333134306139623239
+37636639356263646437373362333931613262363363313462666534643765313139386461623731
+33376635653133353033333733613464396632636634313063326363313030376632643863336237
+61636638353237313764313435626463633964643665313536326235343639663137373436303564
+30636232626137376339303238653664346538356430306238633037366332316263623666373062
+63646533646131303466653637346463613237323161313265613834383634626237323563653733
+38656435303264346663663465333966376631666530333833353233376263336436613065366362
+36366263343438393132326661623031316663663231663464383732343064383234616636306530
+66613634626362316533303034393063666632343262613431613635663866636433623535363238
+30643933613731363236346234336662613633323831633437613435326465383530653765616262
+63373538396364316563343365303134373466663639386137663564356532353531343636613135
+63316463353264316164306566326462333732316431643939626161346530636638636662303037
+34346461313961613063336332333934383363373335616636363661396362613661383762663866
+64303834636264376461396266663763336665356561376161333136336638646363313133353161
+31643061623833623239373432633537663664636334623534326639616633616361333834366131
+30376361656238353332656666316637643133623433333861653265636266376639666135383638
+37363337326231656530363536393737383565666266306532626361633633353539363866376534
+61303737326632303762626666306134343837376566343035386663613336626332383035383035
+37633462373066373062313862323766316362393832666466396637363562353865303366323062
+39346332383966313437646138623364656234663066663639663138626163656433363038323166
+65613862386665643438323061323763306635666162303366323131363436633335356332393366
+63373966383132303434633835333438333337303664346335643066623839343835643364306561
+34643336346564363462396330643263653931376664386335313433376332653832323437376135
+35383231386133363236653334393433306638303131323064343931623538323130343666653061
+36353536383632333964343730346265626433303131346531303133663832363036333261386237
+30363361356265356139323761623563396565336137333733656431636531333234323061343862
+33623935346663333735613661363234646234356331323636386637343661373363363261646231
+33643233343235323230393933616664623166666266333862323631653835666135303233653635
+63373061656163353762636531613632366638383366303864343132376162643963366564363563
+61336338613935613532636165383463633866633036393533313433643562313737383431353163
+37623165373933376236393931363939633963666636303136373065376635623761346537643530
+35363464313630376233633863306238616138666464316534363332333937343362343233346431
+34643032323934353939666364323239653932363735373061633434653062326336353239633261
+38306237336266663038656534393664646138343038323335633064616431386666613739326630
+34383963666534313530376331366238343836303036306336343533666332386163643033643138
+33336333333338353733383165306139623964303035653439623131633566356136386431613135
+63616462386639303230343866346631346532353531373132613433363239646330653666633532
+65393766333238383531313132633537633833363335303630376239396565373730646331313633
+30383861303739343265623934643635633361623262356433323035393062353630346430646262
+63303434353038646361353661616339313937323336303566303536366163623362356332383862
+37326333393761633732653264646333653439363039323238383361336233323232613336303464
+34393635633131313135313665363161306466643364393734346264633030373234306466653862
+32336163666435636162343465386633653863363533616339636531306130383331376563393533
+65366136626662343065383164646665613035393636373565346235656439303933343563366339
+36643838393033353033396535613331303031646162316361613564323163633434633861356135
+62343461616335323565636633383962316531316362396165366533346166336163623232366261
+39376230376562626135346333326437373733373266393236383435343562653034313133376236
+61666138346562613330633630373837653465393233613261353937336666646231366666393335
+35393463333936323664323831396639333462626238613164616435363664643438653763623431
+32663237363134353061373563396535653565636431366565386337653863316333343738343432
+62303132636338303462313439376535363063333833363632613832303436353834376561333330
+66633632383135646263626333643230343630326539663762633934316261633062663732373932
+30306438386263626335373838343236643562326135663366353638353163346365396261313133
+36333634306133353235316237343738623263333732343063356238333162323931346664346539
+66323733643061386334306130633537353630663336313966663538373963313435666564316539
+63613030366332363432303036396232306537663765653938353736376135316539613135623632
+66356639623635663365323635646635383638346539323438336261393332373935383536333831
+61306639343061333639336162366536366438356166396266666132303932333037613632623666
+63616662343830303664353931306632323630316162643432653835313962633735626163366332
+34373637633066333432383533316363613031393963373963386161663430623533383165653561
+38343439633066366663643138326264653539336530393932386236366533663935353664343966
+39323161646231353234633961633732613065323039663062313661386565366534623430356632
+64343732336238393262363338363734643639353830646163343361653761633134303163616562
+35633436393832393137383534613031303963613339333566343065336530623964636662353065
+32366630353538383339346465376661323666333234373665613164633866363364613066643034
+37616630366232353166366535633936366536626462353831643335306337353564316461653564
+66663133373466333431336366346435623436656230376232613665633466333463636263373464
+30386434336538303061666566383033616563303564666362346432663130306531613063363537
+646635613236636563666161666630653836

inventory/hosts

@@ -0,0 +1,24 @@
+$ANSIBLE_VAULT;1.1;AES256
+37366366376266633033656235333633346134336666323465356666353363323130366365393534
+3365373534643965613139656465323663393862336163640a623663366631323035346632353030
+37396264356137336535363663323935646464333138653035623562346438643139323439366132
+3364356364353738660a616638393635333938373838316631396536386134333831613831343732
+39333066363566643864343661646633326134633039316636306332303063366665373638353735
+34386339633566663038613538316233306238383734623363623666346261336562663039373264
+31313061616432643761633139643039636164613136643264663131666166646531366335346164
+34303339393334616434633736383763653035386333363137336431363034653263306261646661
+37323563373436333736633836666563646162303232393932346430373039346431356166393930
+37616639333038653936633163323139396666303638663039623633633832333737633764643863
+61383763613865323061636662663837656339373335643066333964393362303766366533303332
+63646335356639366130393530373936636330633132356639626531303839656166346263613733
+31333362316537323934306434393630656161353465636434303538643835396361613563663437
+34383765626235356530396433643037306233663263623664636163326132316237386231323165
+65643235356434626161396136303563633836313961343664653339623862633338313963333237
+63663961636661383634343532356234626531373938313164373561386139366338393066623036
+36633137623361626161313961386630623635323336353036623165316632353333383162623531
+61353138613030343636326166303762656264643834396330313563616439323265333039323566
+64356538346662613836356462613536656636373065643734346166353466363266353939393535
+66333739623735656463373530646663303535643562363534306438323135353763303363376135
+37653566306461396563333135633235626130313231636165383438376237383663373939353637
+30366661303131333438376363366131613361326635366264363064633034376230353137663030
+346238306532363635623732396366633538

justfile

@@ -58,3 +58,7 @@ 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 }}
+
+# Rebuilds the mautrix-meta-instagram Ansible role using the mautrix-meta-messenger role as a source
+rebuild-mautrix-meta-instagram:
+    /bin/bash {{ justfile_directory() }}/bin/rebuild-mautrix-meta-instagram.sh {{ justfile_directory() }}/roles/custom

requirements.yml

@@ -4,34 +4,37 @@
   version: v1.0.0-3
   name: auxiliary
 - src: git+https://gitlab.com/etke.cc/roles/backup_borg.git
-  version: v1.2.7-1.8.6-0
+  version: v1.2.8-1.8.9-0
   name: backup_borg
 - src: git+https://github.com/devture/com.devture.ansible.role.container_socket_proxy.git
-  version: v0.1.1-3
+  version: v0.1.2-1
   name: container_socket_proxy
 - src: git+https://github.com/geerlingguy/ansible-role-docker
-  version: 7.0.2
+  version: 7.1.0
   name: docker
 - src: git+https://github.com/devture/com.devture.ansible.role.docker_sdk_for_python.git
   version: 129c8590e106b83e6f4c259649a613c6279e937a
   name: docker_sdk_for_python
 - src: git+https://gitlab.com/etke.cc/roles/etherpad.git
-  version: v1.9.6-0
+  version: v2.0.3-0
   name: etherpad
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-exim-relay.git
-  version: v4.97-r0-0-1
+  version: v4.97.1-r0-0-2
   name: exim_relay
 - src: git+https://gitlab.com/etke.cc/roles/grafana.git
-  version: v10.2.3-0
+  version: v11.0.0-0
   name: grafana
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-jitsi.git
-  version: v9111-1
+  version: v9457-3
   name: jitsi
+- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-keydb.git
+  version: v6.3.4-1
+  name: keydb
 - src: git+https://gitlab.com/etke.cc/roles/ntfy.git
-  version: v2.8.0-1
+  version: v2.10.0-0
   name: ntfy
 - src: git+https://github.com/devture/com.devture.ansible.role.playbook_help.git
-  version: c1f40e82b4d6b072b6f0e885239322bdaaaf554f
+  version: 201c939eed363de269a83ba29784fc3244846048
   name: playbook_help
 - src: git+https://github.com/devture/com.devture.ansible.role.playbook_runtime_messages.git
   version: 9b4b088c62b528b73a9a7c93d3109b091dd42ec6
@@ -40,34 +43,34 @@
   version: ff2fd42e1c1a9e28e3312bbd725395f9c2fc7f16
   name: playbook_state_preserver
 - src: git+https://github.com/devture/com.devture.ansible.role.postgres.git
-  version: v16.1-4
+  version: v16.3-0
   name: postgres
 - src: git+https://github.com/devture/com.devture.ansible.role.postgres_backup.git
-  version: 7eadc992ca952fc29bf3fab5aa6335fa82ff01e5
+  version: 046004a8cb9946979b72ce81c2526c8033ea8067
   name: postgres_backup
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus.git
-  version: v2.48.1-0
+  version: v2.52.0-0
   name: prometheus
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-node-exporter.git
-  version: v1.7.0-2
+  version: v1.8.0-0
   name: prometheus_node_exporter
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus-postgres-exporter.git
-  version: v0.14.0-3
+  version: v0.14.0-4
   name: prometheus_postgres_exporter
 - src: git+https://gitlab.com/etke.cc/roles/redis.git
-  version: v7.2.3-2
+  version: v7.2.4-0
   name: redis
 - src: git+https://github.com/devture/com.devture.ansible.role.systemd_docker_base.git
-  version: v1.0.0-2
+  version: v1.1.0-0
   name: systemd_docker_base
 - src: git+https://github.com/devture/com.devture.ansible.role.systemd_service_manager.git
-  version: v1.0.0-3
+  version: v1.0.0-4
   name: systemd_service_manager
 - src: git+https://github.com/devture/com.devture.ansible.role.timesync.git
   version: v1.0.0-0
   name: timesync
 - src: git+https://github.com/devture/com.devture.ansible.role.traefik.git
-  version: v2.10.7-0
+  version: v2.11.2-0
   name: traefik
 - src: git+https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper.git
   version: v2.8.3-1

roles/custom/etherpad-proxy-connect/defaults/main.yml

@@ -1,11 +0,0 @@
----
-
-# etherpad-proxy-connect is a compatibility role connecting the new Etherpad role with matrix-nginx-proxy.
-# It adds back support for serving Etherpad under the Dimension domain (`matrix_server_fqn_dimension`).
-
-# Controls whether Etherpad will be hosted under the Dimension domain when matrix-nginx-proxy is used (depending on matrix_playbook_reverse_proxy_type).
-# If you're not using matrix-nginx-proxy, then this value has no effect.
-etherpad_nginx_proxy_dimension_integration_enabled: false
-
-# Controls the path at which Etherpad will be exposed on the Dimension domain.
-etherpad_nginx_proxy_dimension_integration_path_prefix: "{{ etherpad_path_prefix }}"

roles/custom/etherpad-proxy-connect/tasks/inject_into_nginx_proxy.yml

@@ -1,46 +0,0 @@
----
-
-- name: Fail if matrix-nginx-proxy role already executed
-  ansible.builtin.fail:
-    msg: >-
-      Trying to append Etherpad's reverse-proxying configuration to matrix-nginx-proxy,
-      but it's pointless since the matrix-nginx-proxy role had already executed.
-      To fix this, please change the order of roles in your playbook,
-      so that the matrix-nginx-proxy role would run after the matrix-etherpad role.
-  when: matrix_nginx_proxy_role_executed | default(False) | bool
-
-- name: Generate Etherpad proxying configuration for matrix-nginx-proxy
-  ansible.builtin.set_fact:
-    etherpad_matrix_nginx_proxy_configuration: |
-      rewrite ^{{ etherpad_nginx_proxy_dimension_integration_path_prefix }}$ {{ matrix_nginx_proxy_x_forwarded_proto_value }}://$server_name{{ etherpad_nginx_proxy_dimension_integration_path_prefix }}/ permanent;
-
-      location {{ etherpad_nginx_proxy_dimension_integration_path_prefix }}/ {
-      {% if matrix_nginx_proxy_enabled | default(False) %}
-        {# Use the embedded DNS resolver in Docker containers to discover the service #}
-        resolver 127.0.0.11 valid=5s;
-        proxy_pass http://{{ etherpad_identifier }}:9001/;
-        {# These are proxy directives needed specifically by Etherpad #}
-        proxy_buffering off;
-        proxy_http_version 1.1;  # recommended with keepalive connections
-        proxy_pass_header Server;
-        proxy_set_header Host $host;
-        proxy_set_header X-Forwarded-Proto {{ matrix_nginx_proxy_x_forwarded_proto_value }}; # for EP to set secure cookie flag when https is used
-        # WebSocket proxying - from http://nginx.org/en/docs/http/websocket.html
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection $connection_upgrade;
-      {% else %}
-        {# Generic configuration for use outside of our container setup #}
-        # A good guide for setting up your Etherpad behind nginx:
-        # https://docs.gandi.net/en/cloud/tutorials/etherpad_lite.html
-        proxy_pass http://127.0.0.1:9001/;
-      {% endif %}
-      }
-
-- name: Register Etherpad proxying configuration with matrix-nginx-proxy
-  ansible.builtin.set_fact:
-    matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks: |
-      {{
-        matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks | default([])
-        +
-        [etherpad_matrix_nginx_proxy_configuration]
-      }}