Merge 1e8d4c5ba05616248098f5fd76b8c6ddb163cd51 into ca8c1cf2b5416924c4379d43d5c943928377747d

Add support for Valkey and default to using it instead of KeyDB
Hopefully fixes https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3544
2025-01-30 20:05:01 +01:00 · 2024-11-24 01:04:17 +09:00 · 2024-11-23 14:43:04 +02:00 · 2024-11-23 11:52:48 +02:00 · 2024-11-23 09:59:29 +02:00 · 2024-11-23 07:21:12 +02:00
43 changed files with 646 additions and 179 deletions
--- a/.github/workflows/close-stale-issues.yml
+++ b/.github/workflows/close-stale-issues.yml
@ -0,0 +1,27 @@
+---
+name: 'Close stale issues'
+on:  # yamllint disable-line rule:truthy
+  schedule:
+    - cron: '30 1 * * *'
+
+permissions:
+  issues: write
+
+jobs:
+  stale:
+    if: github.repository == 'spantaleev/matrix-docker-ansible-deploy'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          # Don't process pull requests at all
+          days-before-pr-stale: -1
+          stale-issue-message: 'This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
+          close-issue-message: 'This issue was closed because it has been stalled for 7 days with no activity. If this issue is still reproduced, feel free to provide the issue with up-to-date information.'
+          stale-issue-label: 'stale'
+          # Add this label to exempt the issue from being marked as stale due to inactivity
+          exempt-issue-labels: 'confirmed'
+          # An allow-list of label(s) to only process the issues which contain one of these label(s).
+          any-of-issue-labels: 'question,needs-info'
+          # Use this to do a dry run from a pull request
+          # debug-only: true
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -1,3 +1,45 @@
+# 2024-11-23
+
+## (Backward Compatibility Break) The playbook now defaults to Valkey, instead of KeyDB
+
+**TLDR**: if the playbook installed KeyDB (or Redis) as a dependency for you before, it will now replace it with [Valkey](https://valkey.io/) (a drop-in alternative). We [previously switched from Redis to KeyDB](#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis), but Valkey is a better alternative, so we're switching again.
+
+The playbook used to install Redis or KeyDB if services have a need for a Redis-compatible implementation ([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.).
+
+Earlier this year, we switched from Redis to KeyDB - see [(Backward Compatibility Break) The playbook now defaults to KeyDB, instead of Redis](#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis).
+
+Because Valkey seems to be a better successor to Redis (than KeyDB) and likely doesn't suffer from [issues like this one](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3544), we now replace KeyDB with Valkey.
+
+Valkey (like KeyDB and Redis in the past) is an implicitly enabled dependency - you don't need custom configuration in `vars.yml` to enable it.
+
+Next time your run the playbook (via the `setup-all` tag), **KeyDB will be automatically uninstalled and replaced with Valkey**. 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 Valkey**, nor the Valkey 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 Valkey (or Redis/KeyDB). If Redis is necessary in an `arm32` deployment, disabling Valkey 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 both Valkey and KeyDB.
+#
+# Redis will be auto-enabled if necessary,
+# because there's no other Redis-compatible implementation being enabled.
+valkey_enabled: false
+keydb_enabled: false
+```
+
+**The playbook still supports KeyDB** and you can keep using KeyDB (for now) if you'd like, by adding this additional configuration to your `vars.yml` file:
+
+```yml
+# Explicitly disable Valkey  enable KeyDB.
+#
+# Redis will not be auto-enabled beandcause a Redis-compatible implementation (KeyDB) is enabled.
+valkey_enabled: false
+keydb_enabled: true
+```
+
+At some point in time in the future, we'll remove both KeyDB and Redis from the playbook, so we recommend that you migrate to Valkey earlier anyway.
+
+
 # 2024-11-14

 ## HTTP-compression support for Traefik-based setups
@ -15,8 +57,8 @@ This middleware's configuration can be configured via variables in the Traefik r
 If you're using your own Traefik reverse-proxy server ([Traefik managed by you](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you)) instead of the playbook's integrated Traefik service, you can benefit from the same by:

 - defining a [compress](https://doc.traefik.io/traefik/middlewares/http/compress/) middleware (via the [file](https://doc.traefik.io/traefik/providers/file/) or [Docker](https://doc.traefik.io/traefik/providers/docker/) providers)
- setting `matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled` to `true`
- specifying the middleware's name in `matrix_playbook_reverse_proxy_traefik_middleware_compession_name` (e.g. `matrix_playbook_reverse_proxy_traefik_middleware_compession_name: my-compression-middleware@file`)
+- setting `matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled` to `true`
+- specifying the middleware's name in `matrix_playbook_reverse_proxy_traefik_middleware_compression_name` (e.g. `matrix_playbook_reverse_proxy_traefik_middleware_compression_name: my-compression-middleware@file`)

 ## Timeout adjustments for Traefik-based setups

--- a/README.md
+++ b/README.md
@ -27,6 +27,8 @@ While the [list of supported services](#-supported-services) and documentation i
 - Starting with the basics. You can always add/remove or tweak services later on.
 - Following our guided installation, starting with the [Prerequisites](./docs/prerequisites.md) documentation page

+If you have never configured Matrix services, follow the [**quick start**](./docs/quick-start.md) guide to set up minimum core services on your server.
+
 ## ✔ Supported services

 Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
--- a/docs/README.md
+++ b/docs/README.md
@ -2,6 +2,8 @@

 - [FAQ](faq.md) - lots of questions and answers. Jump to [Prerequisites](prerequisites.md) to avoid reading too much and to just start a guided installation.

+- [Quick start](quick-start.md) - follow the guide to set up minimum core services on your server
+
 - [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook

 - [Configuring your DNS settings](configuring-dns.md)
--- a/docs/configuring-dns.md
+++ b/docs/configuring-dns.md
@ -1,6 +1,6 @@
 # Configuring your DNS settings

-<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
+<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>

 To set up Matrix on your domain, you'd need to do some DNS configuration.

@ -36,7 +36,7 @@ The `element.example.com` subdomain is necessary, because this playbook installs

 Be mindful as to how long it will take for the DNS records to propagate.

-If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
+If you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail.

 ## DNS settings for optional services/features

--- a/docs/configuring-playbook-bot-draupnir.md
+++ b/docs/configuring-playbook-bot-draupnir.md
@ -35,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_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.
+If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](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 itself. If you made Draupnir Admin you can just use the Draupnir token.

--- a/docs/configuring-playbook-bot-mjolnir.md
+++ b/docs/configuring-playbook-bot-mjolnir.md
@ -31,7 +31,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 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_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.
+If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](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 itself. If you made Mjolnir Admin you can just use the Mjolnir token.

--- a/docs/configuring-playbook-bridge-beeper-linkedin.md
+++ b/docs/configuring-playbook-bridge-beeper-linkedin.md
@ -54,7 +54,7 @@ Send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging fo

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

-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
+After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting-by-enabling-appservice-double-puppet-or-shared-secret-auth), if you haven't already done so.


 ## Troubleshooting
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@ -60,7 +60,7 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
 | widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
 | 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 |

-Also see the various `matrix_hookshot_container_labels_*` variables in [default/main.yml](/roles/custom/matrix-bridge-hookshot/default/main.yml), which expose URLs publicly.
+Also see the various `matrix_hookshot_container_labels_*` variables in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly.

 The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.

--- a/docs/configuring-playbook-email.md
+++ b/docs/configuring-playbook-email.md
@ -6,7 +6,7 @@ The email server would attempt to deliver emails directly to their final destina

 By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.

-⚠ **Warning**: On some cloud providers (Google Cloud, etc.), [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible. You will need to [relay email through another SMTP server](#relaying-email-through-another-smtp-server).
+⚠️ **Warning**: On some cloud providers (Google Cloud, etc.), [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so sending email directly from your server is not possible. You will need to [relay email through another SMTP server](#relaying-email-through-another-smtp-server).

 💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.

--- a/docs/configuring-playbook-etherpad.md
+++ b/docs/configuring-playbook-etherpad.md
@ -50,7 +50,7 @@ After configuring the playbook and potentially [adjusting your DNS records](#adj

 The Etherpad UI should be available at `https://etherpad.example.com`, while the admin UI (if enabled) should then be available at `https://etherpad.example.com/admin`.

-If you've [decided on another hostname or path-prefix](#decide-on-a-domain-and-path) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before usage.
+If you've [decided on another hostname or path-prefix](#adjusting-the-etherpad-url) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before usage.


 ### Managing / Deleting old pads
--- a/docs/configuring-playbook-jitsi.md
+++ b/docs/configuring-playbook-jitsi.md
@ -46,7 +46,7 @@ By default, you will need to create a CNAME record for `jitsi`. See [Configuring

 By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.

-If you're fine with such an open Jitsi instance, please skip to [Apply changes](#apply-changes).
+If you're fine with such an open Jitsi instance, please skip to [Installing](#installing).

 If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow the following steps to enable Jitsi's authentication and optionally guests mode.

--- a/docs/configuring-playbook-ma1sd.md
+++ b/docs/configuring-playbook-ma1sd.md
@ -1,15 +1,26 @@
 # Setting up ma1sd Identity Server (optional)

-The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you.
+**⚠️Note**: ma1sd itself has also been unmaintained for years (the latest commit and release being from 2021). The role of identity servers in the Matrix specification also has an uncertain future. **We recommend not bothering with installing it unless it's the only way you can do what you need to do**. For example, certain things like LDAP integration can also be implemented via [the LDAP provider module for Synapse](./configuring-playbook-ldap-auth.md).

-ma1sd, being an Identity Server, is not strictly needed. It is only used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features).
+The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you. It is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.

-This server is private by default, potentially at the expense of user discoverability.
+ma1sd is used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features). It is private by default, potentially at the expense of user discoverability.

-*ma1sd is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.*
+See the project's [documentation](https://github.com/ma1uta/ma1sd) to learn what it does and why it might be useful to you.

 **Note**: enabling ma1sd, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).

+## Adjusting DNS records
+
+To make the ma1sd Identity Server enable its federation features, set up a SRV record that looks like this:
+
+- Name: `_matrix-identity._tcp` (use this text as-is)
+- Content: `10 0 443 matrix.example.com` (replace `example.com` with your own)
+
+See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
+
+**Note**: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
+
 ## Adjusting the playbook configuration

 To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -24,37 +35,34 @@ To ensure maximum discovery, you can make your identity server also forward look

 Enabling this is discouraged and you'd better [learn more](https://github.com/ma1uta/ma1sd/blob/master/docs/features/identity.md#lookups) before proceeding.

-Enabling matrix.org forwarding can happen with the following configuration:
+To enable matrix.org forwarding, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:

 ```yaml
 matrix_ma1sd_matrixorg_forwarding_enabled: true
 ```

-### Customizing email templates
+### Additional features
+
+What this playbook configures for your is some bare minimum Identity Server functionality, so that you won't need to rely on external 3rd party services.
+
+A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
+
+Still, ma1sd can do much more. You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
+
+To use a more custom configuration, you can define a `matrix_ma1sd_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
+
+
+#### Customizing email templates

 If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables (in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.

-## Adjusting DNS records
-
-To make the ma1sd Identity Server enable its federation features, set up an SRV record that looks like this:
- Name: `_matrix-identity._tcp` (use this text as-is)
- Content: `10 0 443 matrix.example.com` (replace `example.com` with your own)
-
-See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
-
-**Note**: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
-
-## Installing
-
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
-
-## ma1sd-controlled Registration
+#### ma1sd-controlled Registration

 To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) feature of ma1sd, you can make use of the following variables:

 - `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse

- `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring_captcha.md) documentation.
+- `matrix_synapse_enable_registration_captcha` - to validate registering users using reCAPTCHA, as described in the [enabling reCAPTCHA](configuring-captcha.md) documentation.

 - `matrix_synapse_registrations_require_3pid` - a list of 3pid types (among `'email'`, `'msisdn'`) required by the Synapse server for registering

@ -65,9 +73,11 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
 **Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).


-## Authentication
+#### Authentication

-[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver. The following configuration can be used to authenticate against an LDAP server:
+[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver.
+
+To enable authentication against an LDAP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:

 ```yaml
 matrix_synapse_ext_password_provider_rest_auth_enabled: true
@ -87,17 +97,7 @@ matrix_ma1sd_configuration_extension_yaml: |
      bindPassword: TheUserPassword
 ```

-## Additional features
-
-What this playbook configures for your is some bare minimum Identity Server functionality, so that you won't need to rely on external 3rd party services.
-
-A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
-
-Still, ma1sd can do much more. You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
-
-To use a more custom configuration, you can define a `matrix_ma1sd_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
-
-## Example: SMS verification
+#### Example: SMS verification

 If your use case requires mobile verification, it is quite simple to integrate ma1sd with [Twilio](https://www.twilio.com/), an online telephony services gateway. Their prices are reasonable for low-volume projects and integration can be done with the following configuration:

@ -113,7 +113,7 @@ matrix_ma1sd_configuration_extension_yaml: |
            number: '+<msisdn-number>'
 ```

-## Example: Open Registration for every Domain
+#### Example: Open Registration for every Domain

 If you want to open registration for any domain, you have to setup the allowed domains with ma1sd's `blacklist` and `whitelist`. The default behavior when neither the `blacklist`, nor the `whitelist` match, is to allow registration. Beware: you can't block toplevel domains (aka `.xy`) because the internal architecture of ma1sd doesn't allow that.

@ -129,13 +129,17 @@ matrix_ma1sd_configuration_extension_yaml: |
            whitelist: ~
 ```

+## Installing
+
+After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+
 ## Troubleshooting

 If email address validation emails sent by ma1sd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md).

 If you'd like additional logging information, temporarily enable verbose logging for ma1sd.

-Example configuration (`inventory/host_vars/matrix.example.com/vars.yml`):
+To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:

 ```yaml
 matrix_ma1sd_verbose_logging: true
--- a/docs/configuring-playbook-matrix-authentication-service.md
+++ b/docs/configuring-playbook-matrix-authentication-service.md
@ -36,9 +36,9 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix

 ## Prerequisites

- ⚠ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
+- ⚠️ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.

- ⚠ **email sending** configured (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
+- ⚠️ **email sending** configured (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.

 - ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.

@ -62,17 +62,17 @@ This section details what you can expect when switching to the Matrix Authentica

 - ❌ **Encrypted appservices** do not work yet (related to [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190) and [PR 17705 for Synapse](https://github.com/element-hq/synapse/pull/17705)), so all bridges/bots that rely on encryption will fail to start (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3658) for Hookshot). You can use these bridges/bots only if you **keep end-to-bridge encryption disabled** (which is the default setting).

- ⚠ **You will need to have email sending configured** (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.
+- ⚠️ **You will need to have email sending configured** (see [Adjusting email-sending settings](./configuring-playbook-email.md)), because **Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working.

- ⚠ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
+- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.

- ⚠ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the "admin" flag for users (as found in the Synapse database). All users are imported as non-admin - see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`)
+- ⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the "admin" flag for users (as found in the Synapse database). All users are imported as non-admin - see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`)

- ⚠ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.
+- ⚠️ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch.

- ⚠ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration).
+- ⚠️ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration).

- ⚠ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed - all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md).
+- ⚠️ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed - all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md).

 - ✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad.

@ -268,9 +268,9 @@ matrix_authentication_service_config_upstream_oauth2_providers:

 💡 Refer to the [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers) for the most up-to-date schema and example for providers. The value shown above here may be out of date.

-⚠ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2.
+⚠️ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2.

-⚠ When [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) which contains OIDC-sourced users, you will need to:
+⚠️ When [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) which contains OIDC-sourced users, you will need to:

 - [Configure upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas)
 - go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process
--- a/docs/configuring-playbook-own-webserver.md
+++ b/docs/configuring-playbook-own-webserver.md
@ -47,8 +47,8 @@ traefik_certs_dumper_ssl_dir_path: "/path/to/your/traefiks/acme.json/directory"
 # For this to work, you will need to define a compress middleware (https://doc.traefik.io/traefik/middlewares/http/compress/) for your Traefik instance
 # using a file (https://doc.traefik.io/traefik/providers/file/) or Docker (https://doc.traefik.io/traefik/providers/docker/) configuration provider.
 #
-# matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled: true
-# matrix_playbook_reverse_proxy_traefik_middleware_compession_name: my-compression-middleware@file
+# matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled: true
+# matrix_playbook_reverse_proxy_traefik_middleware_compression_name: my-compression-middleware@file
 ```

 In this mode all roles will still have Traefik labels attached. You will, however, need to configure your Traefik instance and its entrypoints.
--- a/docs/configuring-playbook-s3-goofys.md
+++ b/docs/configuring-playbook-s3-goofys.md
@ -32,7 +32,7 @@ If you have local media store files and wish to migrate to Backblaze B2 subseque

 ## Migrating from local filesystem storage to S3

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

 After making the backup, follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:

--- a/docs/configuring-playbook-synapse-admin.md
+++ b/docs/configuring-playbook-synapse-admin.md
@ -22,7 +22,7 @@ matrix_synapse_admin_enabled: true

 By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) - the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable.

-⚠ **Warning**: If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all.
+⚠️ **Warning**: If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all.

 ### Adjusting the Synapse Admin URL

--- a/docs/configuring-playbook.md
+++ b/docs/configuring-playbook.md
@ -1,6 +1,6 @@
 # Configuring the playbook

-<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > Configuring the playbook > [Installing](installing.md)</sup>
+<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > Configuring the playbook > [Installing](installing.md)</sup>

 If you've configured your DNS records and retrieved the playbook's source code to your computer, you can start configuring the playbook. To do so, follow these steps inside the playbook directory:

@ -98,7 +98,7 @@ Extend and modify how users are authenticated on your homeserver.

 Use alternative file storage to the default `media_store` folder.

- [Storing Matrix media files on Amazon S3 with Goofys](docs/configuring-playbook-s3-goofys.md)
+- [Storing Matrix media files on Amazon S3 with Goofys](configuring-playbook-s3-goofys.md)

 - [Storing Synapse media files on Amazon S3 or another compatible Object Storage](configuring-playbook-s3.md)

@ -197,7 +197,7 @@ Services that help you in administrating and monitoring your Matrix installation

 - [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md)

- [Enabling metrics and graphs for NginX logs](docs/configuring-playbook-prometheus-nginxlog.md)
+- [Enabling metrics and graphs for NginX logs](configuring-playbook-prometheus-nginxlog.md)

 - [Setting up the rageshake bug report server](configuring-playbook-rageshake.md)

--- a/docs/container-images.md
+++ b/docs/container-images.md
@ -95,7 +95,7 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [mx-puppet-groupme](configuring-playbook-bridge-mx-puppet-groupme.md) | [xangelix/mx-puppet-groupme](https://hub.docker.com/r/xangelix/mx-puppet-groupme) | ❌ | Bridge to [GroupMe](https://groupme.com/) |
 | [mx-puppet-steam](configuring-playbook-bridge-mx-puppet-steam.md) | [icewind1991/mx-puppet-steam](https://hub.docker.com/r/icewind1991/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) |
 | [Email2Matrix](configuring-playbook-email2matrix.md) | [devture/email2matrix](https://hub.docker.com/r/devture/email2matrix/) | ❌ | Bridge for relaying emails to Matrix rooms |
-| [Postmoogle](docs/configuring-playbook-bridge-postmoogle.md) | [etke.cc/postmoogle](https://github.com/etkecc/postmoogle/container_registry) | ❌ | Email to Matrix bridge |
+| [Postmoogle](configuring-playbook-bridge-postmoogle.md) | [etke.cc/postmoogle](https://github.com/etkecc/postmoogle/container_registry) | ❌ | Email to Matrix bridge |

 ## Bots

--- a/docs/faq.md
+++ b/docs/faq.md
@ -80,6 +80,16 @@ Alternatively, you can download Ansible and the playbook itself directly on the

 To learn more, see our [dedicated Ansible documentation page](ansible.md).

+### What is `just`?
+
+[`just`](https://github.com/casey/just) is a modern command-runner alternative to [make](https://www.gnu.org/software/make/). It can be used to invoke commands with less typing.
+
+The `just` utility executes shortcut commands (called "recipes"), which invoke `ansible-playbook`, `ansible-galaxy` or [`agru`](https://github.com/etkecc/agru) (depending on what is available in your system). The targets of the recipes are defined in [`justfile`](../justfile).
+
+For details about `just` commands, take a look at: [Running `just` commands](just.md).
+
+The playbook also contains a `Makefile` for the `make` tool, but most of the just recipes are not available as targets in the `Makefile`.
+
 ### 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/element-hq/synapse).
@ -226,15 +236,15 @@ Using a separate domain name is easier to manage (although it's a little hard to

 We allow `matrix.example.com` to be the Matrix server handling Matrix stuff for `example.com` by [Server Delegation](howto-server-delegation.md). During the installation procedure, we recommend that you set up server delegation using the [.well-known](configuring-well-known.md) method.

-If you'd really like to install Matrix services directly on the base domain, see [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain)
+If you'd really like to install Matrix services directly on the base domain, see [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain)

 ### I don't control anything on the base domain and can't set up delegation to matrix.example.com. What do I do?

-If you're not in control of your base domain (or the server handling it) at all, you can take a look at [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain)
+If you're not in control of your base domain (or the server handling it) at all, you can take a look at [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain)

 ### I can't set up HTTPS on the base domain. How will I get Matrix federating?

-If you really can't obtain an HTTPS certificate for your base domain, you can take a look at [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain)
+If you really can't obtain an HTTPS certificate for your base domain, you can take a look at [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain)

 ### How do I install on matrix.example.com without involving the base domain?

@ -371,7 +381,7 @@ Yes, you can.

 You generally need to do a playbook installation (start at the [Prerequisites](prerequisites.md) page), followed by importing your existing data into it.

-This Ansible playbook guides you into installing a server for `example.com` (user identifiers are like this: `@user:example.com`), while the server is at `matrix.example.com`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `example.com`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup - [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain)
+This Ansible playbook guides you into installing a server for `example.com` (user identifiers are like this: `@user:example.com`), while the server is at `matrix.example.com`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `example.com`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup - [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain)

 After configuring the playbook and installing and **before starting** services (done with `ansible-playbook ... --tags=start`) you'd import [your SQLite](importing-synapse-sqlite.md) (or [Postgres](importing-postgres.md)) database and also [import your media store](importing-synapse-media-store.md).

@ -451,7 +461,7 @@ You can later restore these roughly like this:
 - restore the `/matrix` directory and files on the new server manually
 - run the playbook again (see [Installing](installing.md)), but **don't** start services yet (**don't run** `... --tags=start`). This step will fix any file permission mismatches and will also set up additional software (Docker, etc.) and files on the server (systemd service, etc.).
 - perform a Postgres database import (see [Importing Postgres](importing-postgres.md)) to restore your database backup
- start services (see [Starting the services](installing.md#starting-the-services))
+- start services (see [Finalize the installation](installing.md#finalize-the-installation))

 If your server's IP address has changed, you may need to [set up DNS](configuring-dns.md) again.

--- a/docs/getting-the-playbook.md
+++ b/docs/getting-the-playbook.md
@ -1,6 +1,6 @@
 # Getting the playbook

-<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > Getting the playbook > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
+<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > Getting the playbook > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>

 This Ansible playbook is meant to be executed on your own computer (not the Matrix server).

--- a/docs/howto-srv-server-delegation.md
+++ b/docs/howto-srv-server-delegation.md
@ -73,7 +73,7 @@ traefik_configuration_extension_yaml: |
        storage: {{ traefik_config_certificatesResolvers_acme_storage | to_json }}

 # 2. Configure the environment variables needed by Rraefik to automate the ACME DNS Challenge (example for Cloudflare)
-traefik_environment_variables: |
+traefik_environment_variables_additional_variables: |
  CF_API_EMAIL=redacted
  CF_ZONE_API_TOKEN=redacted
  CF_DNS_API_TOKEN=redacted
@ -91,7 +91,7 @@ By default, Coturn is configured to wait on the certificate for the `matrix.` su

 We also need to indicate to Coturn where the wildcard certificate is.

-**⚠ WARNING ⚠** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`).
+**⚠️ WARNING ⚠️** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`).

 This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the Coturn service is setup to restart periodically.

@ -153,7 +153,7 @@ traefik_configuration_extension_yaml: |
 traefik_certResolver_primary: "dns"

 # Configure the environment variables needed by Traefik to automate the ACME DNS Challenge (example for Cloudflare)
-traefik_environment_variables: |
+traefik_environment_variables_additional_variables: |
  CF_API_EMAIL=redacted
  CF_ZONE_API_TOKEN=redacted
  CF_DNS_API_TOKEN=redacted
--- a/docs/installing.md
+++ b/docs/installing.md
@ -1,16 +1,21 @@
 # Installing

-<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > Installing</sup>
+<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > Installing</sup>

 If you've configured your DNS records and the playbook, you can start the installation procedure.

 ## Update Ansible roles

-Before installing, you need to update the Ansible roles in this playbook by running `just roles`.
+Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.

-`just roles` is a shortcut (a `roles` target defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately runs [agru](https://github.com/etkecc/agru) or [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) (depending on what is available in your system) to download Ansible roles. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`.
+To update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file), run:

-There's another shortcut (`just update`) which updates the playbook (`git pull`) and updates roles (`just roles`) at the same time.
+- either: `just update`
+- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
+
+If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
+
+For details about `just` commands, take a look at: [Running `just` commands](just.md).

 ## Install Matrix server and services

@ -48,7 +53,7 @@ To do the installation **without** starting services, run `ansible-playbook` wit
 ansible-playbook -i inventory/hosts setup.yml --tags=install-all
 ```

-**Note**: do not run the just "recipe" `just install-all` instead, because it automatically starts services at the end of execution.
+**Note**: do not run the just "recipe" `just install-all` instead, because it automatically starts services at the end of execution. See: [Difference between playbook tags and shortcuts](just.md#difference-between-playbook-tags-and-shortcuts)

 When this command completes, services won't be running yet.

@ -66,26 +71,52 @@ You can now:
 ansible-playbook -i inventory/hosts setup.yml --tags=ensure-matrix-users-created,start
 ```

+## Create your user account
+
+ℹ️ *You can skip this step if you have installed a server and imported old data to it.*
+
+As you have configured your brand new server and the client, you need to **create your user account** on your Matrix server.
+
+After creating the user account, you can log in to it with [Element Web](configuring-playbook-client-element-web.md) that this playbook has installed for you at this URL: `https://element.example.com/`.
+
+To create your user account (as an administrator of the server) via this Ansible playbook, run the command below on your local computer.
+
+**Notes**:
+- Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
+- For `YOUR_USERNAME_HERE`, use a plain username like `john`, not your full identifier (`@user:example.com`)
+- Use `admin=yes` to make your user account an administrator of the Matrix server
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user
+
+# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
+```
+
+Feel free to create as many accounts (for friends, family, etc.) as you want. Still, perhaps you should grant full administrative access to your account only (with `admin=yes`), and others should be created with `admin=no`.
+
+For more information, see the documentation for [registering users](registering-users.md).
+
 ## Finalize the installation

-Now that services are running, you need to **finalize the installation process** by [delegating (redirecting) the server](howto-server-delegation.md) to your base domain (`example.com`).
+Now you've configured Matrix services and your user account, you need to **finalize the installation process** by [setting up Matrix delegation (redirection)](howto-server-delegation.md), so that your Matrix server (`matrix.example.com`) can present itself as the base domain (`example.com`) in the Matrix network.

 This is required for federation to work! Without a proper configuration, your server will effectively not be part of the Matrix network.

-If you need the base domain for anything else such as hosting a website, you have to configure it manually, following the procedure described on the linked documentation.
+To configure the delegation, you have these two options. Choose one of them according to your situation.

-However, if you do not need the base domain for anything else, the easiest way of configuring it is to [serve the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user identifier like `@<username>:example.com` while hosting services on a subdomain like `matrix.example.com`.
+- If you can afford to point the base domain at the Matrix server, follow the instructions below which guide you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user identifier like `@<username>:example.com` while hosting services on a subdomain like `matrix.example.com`.
+- Alternatively, if you're using the base domain for other purposes and cannot point it to the Matrix server (and thus cannot "serve the base domain" from it), you most likely need to [manually install well-known files on the base domain's server](configuring-well-known.md#manually-installing-well-known-files-on-the-base-domains-server), but feel free to familiarize yourself with all [server delegation (redirection) options](howto-server-delegation.md).

-To configure server delegation in this way, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To have the base domain served from the integrated web server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:

 ```yaml
 matrix_static_files_container_labels_base_domain_enabled: true
 ```

-After configuring the playbook, run the installation command:
+After configuring the playbook, run the command below:

 ```sh
-ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+ansible-playbook -i inventory/hosts setup.yml --tags=install-matrix-static-files,start
 ```

 ## Things to do next
@ -93,7 +124,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
 After finilizing the installation, you can:

 - [check if services work](maintenance-checking-services.md)
- or [create your first Matrix user account](registering-users.md)
 - or [set up additional services](configuring-playbook.md#other-configuration-options) (bridges to other chat networks, bots, etc.)
 - or learn how to [upgrade services when new versions are released](maintenance-upgrading-services.md)
 - or learn how to [maintain your server](faq.md#maintenance)
@ -104,8 +134,12 @@ After finilizing the installation, you can:

 ### Maintaining your setup in the future

-Feel free to **re-run the setup command any time** you think something is off with the server configuration. Ansible will take your configuration and update your server to match. To update the playbook and the Ansible roles in the playbook, simply run `just roles`.
+While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.

-Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [this page on the playbook tags](playbook-tags.md) for more information.
+The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities.

-A way to invoke these `ansible-playbook` commands with less typing in the future is to use [just](https://github.com/casey/just) to run the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information.
+Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
+
+For more information about upgrading or maintaining services with the playbook, take at look at this page: [Upgrading the Matrix services](maintenance-upgrading-services.md)
+
+Feel free to **re-run the setup command any time** you think something is off with the server configuration. Ansible will take your configuration and update your server to match.
--- a/docs/just.md
+++ b/docs/just.md
@ -0,0 +1,38 @@
+# Running `just` commands
+
+We have previously used [make](https://www.gnu.org/software/make/) for easily running some playbook commands (e.g. `make roles` which triggers [`ansible-galaxy`](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html)). Our [`Makefile`](../Makefile) is still around, and you can still run these commands.
+
+In addition, we have added support for running commands via [`just`](https://github.com/casey/just) - a more modern command-runner alternative to `make`. It can be used to invoke `ansible-playbook` commands with less typing.
+
+The `just` utility executes shortcut commands (called as "recipes"), which invoke `ansible-playbook`, `ansible-galaxy` or [`agru`](https://github.com/etkecc/agru) (depending on what is available in your system). The targets of the recipes are defined in [`justfile`](../justfile). Most of the just recipes have no corresponding `Makefile` targets.
+
+For some recipes such as `just update`, our `justfile` recommends installing [`agru`](https://github.com/etkecc/agru) (a faster alternative to `ansible-galaxy`) to speed up the process.
+
+Here are some examples of shortcuts:
+
+| Shortcut                                      | Result                                                                                                         |
+|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| `just roles`                                  | Install the necessary Ansible roles pinned in [`requirements.yml`](../requirements.yml)                        |
+| `just update`                                 | Run `git pull` (to update the playbook) and install the Ansible roles                                          |
+| `just install-all`                            | Run `ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start`       |
+| `just setup-all`                              | Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start`         |
+| `just install-all --ask-vault-pass`           | Run commands with additional arguments (`--ask-vault-pass` will be appended to the above installation command) |
+| `just run-tags install-mautrix-slack,start`   | Run specific playbook tags (here `install-mautrix-slack` and `start`)                                          |
+| `just install-service mautrix-slack`          | Run `just run-tags install-mautrix-slack,start` with even less typing                                          |
+| `just start-all`                              | (Re-)starts all services                                                                                       |
+| `just stop-group postgres`                    | Stop only the Postgres service                                                                                 |
+| `just register-user john secret-password yes` | Registers a `john` user with the `secret-password` password and admin access (admin = `yes`)                   |
+
+While [our documentation on prerequisites](prerequisites.md) lists `just` as one of the requirements for installation, using `just` is optional. If you find it difficult to install it, do not find it useful, or want to prefer raw `ansible-playbook` commands for some reason, feel free to run all commands manually. For example, you can run `ansible-galaxy` directly to install the Ansible roles: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`.
+
+## Difference between playbook tags and shortcuts
+
+It is worth noting that `just` "recipes" are different from [playbook tags](playbook-tags.md). The recipes are shortcuts of commands defined in `justfile` and can be executed by the `just` program only, while the playbook tags are available for the raw `ansible-playbook` commands as well. Please be careful not to confuse them.
+
+For example, these two commands are different:
+- `just install-all`
+- `ansible-playbook -i inventory/hosts setup.yml --tags=install-all`
+
+The just recipe runs `ensure-matrix-users-created` and `start` tags after `install-all`, while the latter runs only `install-all` tag. The correct shortcut of the latter is `just run-tags install-all`.
+
+Such kind of difference sometimes matters. For example, when you install a Matrix server into which you will import old data (see [here](installing.md#installing-a-server-into-which-youll-import-old-data)), you are not supposed to run `just install-all` or `just setup-all`, because these commands start services immediately after installing components which may prevent your from importing old data.
--- a/docs/maintenance-checking-services.md
+++ b/docs/maintenance-checking-services.md
@ -10,4 +10,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=self-check

 If it's all green, everything is probably running correctly.

-Besides this self-check, you can also check your server using the [Federation Tester](https://federationtester.matrix.org/).
+Besides this self-check, you can also check whether your server federates with the Matrix network by using the [Federation Tester](https://federationtester.matrix.org/) against your base domain (`example.com`), not the `matrix.example.com` subdomain.
--- a/docs/maintenance-synapse.md
+++ b/docs/maintenance-synapse.md
@ -65,7 +65,7 @@ docker run --rm --publish 1799:8080 --link matrix-postgres --net matrix adminer

 You should then be able to browse the adminer database administration GUI at http://localhost:1799/ after entering your DB credentials (found in the `host_vars` or on the server in `{{matrix_synapse_config_dir_path}}/homeserver.yaml` under `database.args`)

-⚠️ Be **very careful** with this, there is **no undo** for impromptu DB operations.
+⚠️️ Be **very careful** with this, there is **no undo** for impromptu DB operations.

 ## Make Synapse faster

--- a/docs/maintenance-upgrading-services.md
+++ b/docs/maintenance-upgrading-services.md
@ -2,17 +2,39 @@

 This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available.

+While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
+
+The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities (for example, see [here](https://github.com/element-hq/element-web/security) for known ones on Element Web).
+
+Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
+
+The developers of this playbook strive to maintain the playbook updated, so that you can re-run the playbook to address such vulnerabilities. It is **your responsibility** to keep your server and the services on it up-to-date.
+
 If you want to be notified when new versions of Synapse are released, you should join the Synapse Homeowners room: [#homeowners:matrix.org](https://matrix.to/#/#homeowners:matrix.org).

-To upgrade services:
+## Steps to upgrade the Matrix services
+
+Before updating the playbook and the Ansible roles in the playbook, take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of.
+
+If it looks good to you, go to the `matrix-docker-ansible-deploy` directory, then:

 - update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using:

  - either: `just update`
-  - or: a combination of `git pull` and `just roles` (or `make roles`)
+  - or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)

- take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of
+  If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`

- re-run the [playbook setup](installing.md) and restart all services: `just install-all` or `just setup-all`
+  For details about `just` commands, take a look at: [Running `just` commands](just.md).
+
+- re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services:
+
+  ```sh
+  ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+  ```
+
+Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [this page on the playbook tags](playbook-tags.md) for more information.
+
+A way to invoke these `ansible-playbook` commands with less typing is to run the `just` "recipe": `just install-all` or `just setup-all`.

 **Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).
--- a/docs/playbook-tags.md
+++ b/docs/playbook-tags.md
@ -20,4 +20,6 @@ Here are some playbook tags that you should be familiar with:

 - `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created

-`setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc.
+**Notes**:
+- `setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc.
+- Please be careful not to confuse the playbook tags with the `just` shortcut commands ("recipes"). For details about `just` commands, see: [Running `just` commands](just.md)
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
@ -1,8 +1,24 @@
 # Prerequisites

-<sup>⚡️[Quick start](README.md) | Prerequisites > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
+<sup>⚡️[Quick start](quick-start.md) | Prerequisites > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>

-To install Matrix services using this Ansible playbook, you need:
+To install Matrix services using this Ansible playbook, you need to prepare several requirements both on your local computer (where you will run the playbook to configure the server) and the server (where the playbook will install the Matrix services for you). **These requirements need to be set up manually** before proceeding to the next step.
+
+We will be using `example.com` as the domain in the following instruction. Please remember to replace it with your own domain before running any commands.
+
+## Your local computer
+
+- [Ansible](http://ansible.com/) program. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible.
+
+- [passlib](https://passlib.readthedocs.io/en/stable/index.html) Python library. See [this official documentation](https://passlib.readthedocs.io/en/stable/install.html#installation-instructions) for an instruction to install it. On most distros, you need to install some `python-passlib` or `py3-passlib` package, etc.
+
+- [`git`](https://git-scm.com/) as the recommended way to download the playbook. `git` may also be required on the server if you will be [self-building](self-building.md) components.
+
+- [`just`](https://github.com/casey/just) for running `just roles`, `just update`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually. Take at look at this documentation for more information: [Running `just` commands](just.md).
+
+- Strong password (random strings) generator. The playbook often requires you to create a strong password and use it for settings on `vars.yml`, components, etc. As any tools should be fine, this playbook has adopted [`pwgen`](https://linux.die.net/man/1/pwgen) (running `pwgen -s 64 1`). [Password Tech](https://pwgen-win.sourceforge.io/), formerly known as "PWGen for Windows", is available as free and open source password generator for Windows. Generally, using a random generator available on the internet is not recommended.
+
+## Server

 - (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**
@ -18,17 +34,9 @@ To install Matrix services using this Ansible playbook, you need:

 - `root` access to your server (or a user capable of elevating to `root` via `sudo`).

- [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python3`). On some distros, Ansible may incorrectly [detect the Python version](https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html) (2 vs 3) and you may need to explicitly specify the interpreter path in `inventory/hosts` during installation (e.g. `ansible_python_interpreter=/usr/bin/python3`)
+- [Python](https://www.python.org/). Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python3`). On some distros, Ansible may incorrectly [detect the Python version](https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html) (2 vs 3) and you may need to explicitly specify the interpreter path in `inventory/hosts` during installation (e.g. `ansible_python_interpreter=/usr/bin/python3`)

- [sudo](https://www.sudo.ws/) being installed on the server, even when you've configured Ansible to log in as `root`. Some distributions, like a minimal Debian net install, do not include the `sudo` package by default.
-
- The [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible.
-
- the [passlib](https://passlib.readthedocs.io/en/stable/index.html) Python library installed on the computer you run Ansible. On most distros, you need to install some `python-passlib` or `py3-passlib` package, etc.
-
- [`git`](https://git-scm.com/) is the recommended way to download the playbook to your computer. `git` may also be required on the server if you will be [self-building](self-building.md) components.
-
- [`just`](https://github.com/casey/just) for running `just roles`, `just update`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually
+- [sudo](https://www.sudo.ws/), even when you've configured Ansible to log in as `root`. Some distributions, like a minimal Debian net install, do not include the `sudo` package by default.

 - An HTTPS-capable web server at the base domain name (`example.com`) which is capable of serving static files. Unless you decide to [Serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md) or alternatively, to use DNS SRV records for [Server Delegation](howto-server-delegation.md).

--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@ -0,0 +1,202 @@
+# Quick start
+
+<!--
+NOTE:
+- Let's keep it as tidy and simple as possible.
+- Because this documentation is intended to be referred by those who have not configured a Matrix server and services by using the playbook, from the educational point of view it intentionally avoids instructions based on just program's "recipes" in favor of ansible-playbook commands in most cases.
+-->
+
+This page explains how to use this Ansible playbook to install Matrix services on your server with a minimal set of core services.
+
+We will be using `example.com` as the "base domain" in the following instruction.
+
+By following the instruction on this page, you will set up:
+
+- **your own Matrix server** on a `matrix.example.com` server, which is configured to present itself as `example.com`
+- **your user account** like `@user:example.com` on the server
+- a **self-hosted Matrix client**, [Element Web](configuring-playbook-client-element-web.md) with the default subdomain at `element.example.com`
+- Matrix delegation, so that your `matrix.example.com` server (presenting itself as `example.com`) can join the Matrix Federation and communicate with any other server in the Matrix network
+
+Please remember to replace `example.com` with your own domain before running any commands.
+
+## Prerequisites
+
+<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Prerequisites](prerequisites.md)</sup>
+
+At first, **check prerequisites** and prepare for installation by setting up programs [on your own computer](prerequisites.md#your-local-computer) and [your server](prerequisites.md#server). You also need `root` access on your server (a user that could elevate to `root` via `sudo` also works).
+
+<!--
+TODO: Add one liners (or instructions, a script, etc.) for easy and consistent installation of required software. See: https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3757
+-->
+
+If you encounter an error during installation, please make sure that you have installed and configured programs correctly.
+
+One of the main reasons of basic errors is using an incompatible version of required software such as Ansible. Take a look at [our guide about Ansible](ansible.md) for more information. In short: installing the latest available version is recommended.
+
+## Configure your DNS settings
+
+<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Configuring your DNS settings](configuring-dns.md)</sup>
+
+After installing and configuring prerequisites, you will need to **configure DNS records**.
+
+To configure Matrix services in the default settings, go to your DNS service provider, and adjust DNS records as below.
+
+| Type  | Host                         | Priority | Weight | Port | Target               |
+| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------|
+| A     | `matrix`                     | -        | -      | -    | `matrix-server-IP`   |
+| CNAME | `element`                    | -        | -      | -    | `matrix.example.com` |
+
+As the table illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your server's IP address (DNS `A` record or `CNAME` record is fine).
+
+It might take some time for the DNS records to propagate after creation.
+
+**💡 Note**: if you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only"
+
+## Get the playbook
+
+<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Getting the playbook](getting-the-playbook.md)</sup>
+
+Next, let's **get the playbook's source code**.
+
+We recommend to do so with [git](https://git-scm.com/) as it enables you to keep it up to date with the latest source code. While it is possible to download the playbook as a ZIP archive, it is not recommended.
+
+To get the playbook with git, install git on your computer, go to a directory, and run the command:
+
+```sh
+git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
+```
+
+It will fetch the playbook to a new `matrix-docker-ansible-deploy` directory underneath the directory you are currently in.
+
+## Configure the playbook
+
+<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Configuring the playbook](configuring-playbook.md)</sup>
+
+Now that the playbook was fetched, it is time to **configure** it per your needs.
+
+To install Matrix services with this playbook, you would at least need 2 configuration files.
+
+For your convenience, we have prepared example files of them ([`vars.yml`](../examples/vars.yml) and [`hosts`](../examples/hosts)).
+
+To start quickly based on these example files, go into the `matrix-docker-ansible-deploy` directory and follow the instructions below:
+
+1. Create a directory to hold your configuration: `mkdir -p inventory/host_vars/matrix.example.com` where `example.com` is your "base domain"
+2. Copy the sample configuration file: `cp examples/vars.yml inventory/host_vars/matrix.example.com/vars.yml`
+3. Copy the sample inventory hosts file: `cp examples/hosts inventory/hosts`
+4. Edit the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`)
+5. Edit the inventory hosts file (`inventory/hosts`)
+
+Before editing these 2 files, make sure to read explanations on them to understand what needs to be configured.
+
+**💡 Notes:**
+- If you are not in control of anything on the base domain, you would need to set additional configuration on `vars.yml`. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ.
+- Certain configuration decisions (like the base domain configured in `matrix_domain` and homeserver implementation configured in `matrix_homeserver_implementation`) are final. If you make the wrong choice and wish to change it, you'll have to run the Uninstalling step and start over.
+- Instead of configuring a lot of things all at once, we recommend starting with the basic (default) settings in order to get yourself familiar with how the playbook works. After making sure that everything works as expected, you can add (and remove) advanced settings / features and run the playbook as many times as you wish.
+
+## Install
+
+<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Installing](installing.md)</sup>
+
+After editing `vars.yml` and `hosts` files, let's start the **installation** procedure.
+
+### Update Ansible roles
+
+Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.
+
+To update your playbook directory and all upstream Ansible roles, run:
+
+- either: `just update`
+- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
+
+If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
+
+### Run installation command
+
+Then, run the command below to start installation:
+
+````sh
+ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start
+````
+
+If you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the command.
+
+If you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to the command.
+
+Wait until the command completes. If it's all green, everything should be running properly.
+
+## Create your user account
+
+<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Registering users](registering-users.md)</sup>
+
+As you have configured your brand new server and the client, you need to **create your user account** on your Matrix server.
+
+To create your user account (as an administrator of the server) via this Ansible playbook, run the command below on your local computer.
+
+**💡 Notes**:
+- Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
+- For `YOUR_USERNAME_HERE`, use a plain username like `john`, not your full identifier (`@user:example.com`)
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user
+
+# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
+```
+
+<!--
+NOTE: detailed instruction to add users can be found on docs/registering-users.md and installing.md, which include a note about usage of admin=yes and admin=no variables. In order to keep this guide as reasonably short as possible, let's not repeat the same instruction here.
+-->
+
+## Finalize server installation
+
+<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Server Delegation](howto-server-delegation.md)</sup>
+
+Now that you've configured Matrix services and your user account, you need to **finalize the installation process** by [setting up Matrix delegation (redirection)](howto-server-delegation.md), so that your Matrix server (`matrix.example.com`) can present itself as the base domain (`example.com`) in the Matrix network.
+
+**This is required for federation to work!** Without a proper configuration, your server will effectively not be part of the Matrix network.
+
+To configure the delegation, you have these two options. Choose one of them according to your situation.
+
+- If you can afford to point the base domain at the Matrix server, follow the instruction below which guides you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server.
+- Alternatively, if you're using the base domain for other purposes and cannot point it to the Matrix server (and thus cannot "serve the base domain" from it), you most likely need to [manually install well-known files on the base domain's server](configuring-well-known.md#manually-installing-well-known-files-on-the-base-domains-server).
+
+To have the base domain served from the integrated web server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_static_files_container_labels_base_domain_enabled: true
+```
+
+After configuring the playbook, run the command below and wait until it finishes:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=install-matrix-static-files,start
+```
+
+💡 Running the `install-matrix-static-files` playbook tag (as done here) is an optimized version of running [the full setup command](#run-the-installation-command).
+
+After the command finishes, you can also check whether your server federates with the Matrix network by using the [Federation Tester](https://federationtester.matrix.org/) against your base domain (`example.com`), not the `matrix.example.com` subdomain.
+
+If you think something is off with the server configuration, feel free to [re-run the full setup command](#run-the-installation-command) any time.
+
+## Log in to your user account
+
+Finally, let's make sure that you can log in to the created account with the specified password.
+
+You should be able to log in to it with your own [Element Web](configuring-playbook-client-element-web.md) client which you have set up at `element.example.com` by running the playbook. Open the URL (`https://element.example.com`) in a web browser and enter your credentials to log in.
+
+**If you successfully logged in to your account, installing and configuring is complete**🎉
+
+Come say Hi👋 in our support room - [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting.
+
+## Things to do next
+
+Once you get familiar with the playbook, you might probably want to set up additional services such as a bridge on your server.
+
+As this page intends to be a quick start guide which explains how to start the core Matrix services, it does not cover a topic like how to set them up. Take a look at the list of [things to do next](installing.md#things-to-do-next) to learn more.
+
+### ⚠️Keep the playbook and services up-to-date
+
+While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
+
+Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
+
+For more information about upgrading or maintaining services with the playbook, take at look at this page: [Upgrading the Matrix services](maintenance-upgrading-services.md)
--- a/docs/registering-users.md
+++ b/docs/registering-users.md
@ -1,6 +1,6 @@
 # Registering users

-This documentation page tells you how to create user account on your Matrix server.
+This documentation page tells you how to create user accounts on your Matrix server.

 Table of contents:

@ -9,12 +9,15 @@ Table of contents:
 	- [Managing users via a Web UI](#managing-users-via-a-web-ui)
 	- [Letting certain users register on your private server](#letting-certain-users-register-on-your-private-server)
 	- [Enabling public user registration](#enabling-public-user-registration)
-	- [Adding/Removing Administrator privileges to an existing Synapse user](#addingremoving-administrator-privileges-to-an-existing-synapse-user)
+	- [Adding/Removing Administrator privileges to an existing user](#addingremoving-administrator-privileges-to-an-existing-user)


 ## Registering users manually

-**Note**: in the commands below, `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier.
+**Notes**:
+- Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
+- For `USERNAME_HERE`, use a plain username like `john`, not a full identifier (`@user:example.com`)
+- Use `admin=yes` or `admin=no` depending on whether you wish to make the user an administrator of the Matrix server

 After registering a user (using one of the methods below), **you can log in with that user** via the [Element Web](configuring-playbook-client-element-web.md) service that this playbook has installed for you at a URL like this: `https://element.example.com/`.

@ -22,10 +25,10 @@ After registering a user (using one of the methods below), **you can log in with

 It's best to register users via the Ansible playbook, because it works regardless of homeserver implementation (Synapse, Dendrite, etc) or usage of [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) (MAS).

-To register a user via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
+To register a user via this Ansible playbook:

 ```sh
-just register-user <your-username> <your-password> <admin access: yes or no>
+just register-user USERNAME_HERE PASSWORD_HERE <admin access: yes or no>

 # Example: `just register-user john secret-password yes`
 ```
@ -33,39 +36,41 @@ just register-user <your-username> <your-password> <admin access: yes or no>
 **or** by invoking `ansible-playbook` manually:

 ```sh
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HERE password=PASSWORD_HERE admin=<yes|no>' --tags=register-user

-# Example: `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user`
+# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
 ```

-⚠ **Warning**: If you're registering users against Matrix Authentication Service, do note that it [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
+Feel free to register as many users (for friends, family, etc.) as you want. Still, perhaps you should grant full administrative access to your user account only (with `admin=yes`), and others should be created with `admin=no`.
+
+⚠️ **Warning**: If you're registering users against Matrix Authentication Service, do note that it [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.

 ### Registering users manually for Synapse

-If you're using the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default), you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
+If you're using the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default), you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):

 ```sh
-/matrix/synapse/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
+/matrix/synapse/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>

 # Example: `/matrix/synapse/bin/register-user john secret-password 1`
 ```

 ### Registering users manually for Dendrite

-If you're using the [Dendrite](./configuring-playbook-dendrite.md) homeserver implementation, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
+If you're using the [Dendrite](./configuring-playbook-dendrite.md) homeserver implementation, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):

 ```sh
-/matrix/dendrite/bin/create-account <your-username> <your-password> <admin access: 0 or 1>
+/matrix/dendrite/bin/create-account USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>

 # Example: `/matrix/dendrite/bin/create-account john secret-password 1`
 ```

 ### Registering users manually for Matrix Authentication Service

-If you're using the [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) and your existing homeserver (most likely [Synapse](./configuring-playbook-synapse.md)) is delegating authentication to it, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
+If you're using the [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) and your existing homeserver (most likely [Synapse](./configuring-playbook-synapse.md)) is delegating authentication to it, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):

 ```sh
-/matrix/matrix-authentication-service/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
+/matrix/matrix-authentication-service/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>

 # Example: `/matrix/matrix-authentication-service/bin/register-user john secret-password 1`
 ```
@ -76,19 +81,14 @@ This `register-user` script actually invokes the `mas-cli manage register-user`
 /matrix/matrix-authentication-service/bin/mas-cli manage register-user --help
 ```

-⚠ **Warning**: Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
-
-
-## Things to do after registering users
-
-If you've just installed Matrix and created some users, **to finalize the installation process** it's best if you proceed with [Configuring service discovery via .well-known](configuring-well-known.md)
+⚠️ **Warning**: Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.


 ## Managing users via a Web UI

 To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).

-⚠ **Warning**: If you're using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), note that user management via synapse-admin is not fully working yet. See the [Expectations](configuring-playbook-matrix-authentication-service.md#expectations) section for more information.
+⚠️ **Warning**: If you're using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), note that user management via synapse-admin is not fully working yet. See the [Expectations](configuring-playbook-matrix-authentication-service.md#expectations) section for more information.


 ## Letting certain users register on your private server
--- a/docs/updating-users-passwords.md
+++ b/docs/updating-users-passwords.md
@ -2,20 +2,22 @@

 ## Option 1 (if you are using the integrated Postgres database):

-You can reset a user's password via the Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
+**Notes**:
+- Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
+- For `USERNAME_HERE`, use a plain username like `john`, not a full identifier (`@user:example.com`)
+
+You can reset a user's password via the Ansible playbook:

 ```
-ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password>' --tags=update-user-password
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HERE password=PASSWORD_HERE' --tags=update-user-password
 ```

-**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier.
-
 **You can then log in with that user** via Element Web that this playbook has created for you at a URL like this: `https://element.example.com/`.


 ## Option 2 (if you are using an external Postgres server):

-You can manually generate the password hash by using the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#starting-the-services)):
+You can manually generate the password hash by using the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#finalize-the-installation):

 ```
 docker exec -it matrix-synapse /usr/local/bin/hash_password -c /data/homeserver.yaml
@ -36,7 +38,7 @@ Use the Synapse User Admin API as described here: https://github.com/element-hq/

 This requires an [access token](obtaining-access-tokens.md) from a server admin account. *This method will also log the user out of all of their clients while the other options do not.*

-If you didn't make your account a server admin when you created it, you can learn how to switch it now by reading about it in [Adding/Removing Administrator privileges to an existing Synapse user](registering-users.md#addingremoving-administrator-privileges-to-an-existing-synapse-user).
+If you didn't make your account a server admin when you created it, you can learn how to switch it now by reading about it in [Adding/Removing Administrator privileges to an existing user in Synapse](registering-users.md#addingremoving-administrator-privileges-to-an-existing-user-in-synapse).

 ### Example:
 To set @user:example.com's password to `correct_horse_battery_staple` you could use this curl command:
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@ -35,8 +35,8 @@ matrix_playbook_traefik_labels_enabled: "{{ matrix_playbook_reverse_proxy_type i
 matrix_playbook_reverse_proxy_container_network: "{{ traefik_container_network if traefik_enabled else 'traefik' }}"
 matrix_playbook_reverse_proxy_hostname: "{{ traefik_identifier if traefik_enabled else 'traefik' }}"

-matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled: "{{ traefik_config_http_middlewares_compression_enabled if (traefik_enabled and traefik_config_http_middlewares_compression_enabled) else false }}"
-matrix_playbook_reverse_proxy_traefik_middleware_compession_name: "{{ (traefik_config_http_middlewares_compression_middleware_name + '@file') if traefik_enabled else '' }}"
+matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled: "{{ traefik_config_http_middlewares_compression_enabled if (traefik_enabled and traefik_config_http_middlewares_compression_enabled) else false }}"
+matrix_playbook_reverse_proxy_traefik_middleware_compression_name: "{{ (traefik_config_http_middlewares_compression_middleware_name + '@file') if traefik_enabled else '' }}"

 # A separate Matrix Federation entrypoint is always enabled, unless the federation port matches one of the ports for existing (default) entrypoints
 matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled: "{{ matrix_federation_public_port not in [traefik_config_entrypoint_web_port, traefik_config_entrypoint_web_secure_port] }}"
@ -436,6 +436,8 @@ devture_systemd_service_manager_services_list_auto: |
    +
    ([{'name': (keydb_identifier + '.service'), 'priority': 750, 'groups': ['matrix', 'keydb']}] if keydb_enabled else [])
    +
+    ([{'name': (valkey_identifier + '.service'), 'priority': 750, 'groups': ['matrix', 'valkey']}] if valkey_enabled else [])
+    +
    ([{'name': 'matrix-pantalaimon.service', 'priority': 4000, 'groups': ['matrix', 'pantalaimon']}] if matrix_pantalaimon_enabled else [])
    +
    ([{'name': 'matrix-registration.service', 'priority': 4000, 'groups': ['matrix', 'registration', 'matrix-registration']}] if matrix_registration_enabled else [])
@ -2212,12 +2214,14 @@ matrix_hookshot_systemd_wanted_services_list: |
    ([(redis_identifier + '.service')] if redis_enabled and matrix_hookshot_cache_redis_host == redis_identifier else [])
    +
    ([(keydb_identifier + '.service')] if keydb_enabled and matrix_hookshot_cache_redis_host == keydb_identifier else [])
+    +
+    ([(valkey_identifier + '.service')] if valkey_enabled and matrix_hookshot_cache_redis_host == valkey_identifier else [])
  }}

 # Hookshot's experimental encryption feature (and possibly others) may benefit from Redis, if available.
 # We only connect to Redis if encryption is enabled (not for everyone who has Redis enabled),
 # because connectivity is still potentially troublesome and is to be investigated.
-matrix_hookshot_cache_redis_host: "{{ redis_identifier if redis_enabled and matrix_hookshot_experimental_encryption_enabled else (keydb_identifier if keydb_enabled and matrix_hookshot_experimental_encryption_enabled else '') }}"
+matrix_hookshot_cache_redis_host: "{{ valkey_identifier if valkey_enabled else (redis_identifier if redis_enabled else (keydb_identifier if keydb_enabled else '')) }}"

 matrix_hookshot_container_network: "{{ matrix_addons_container_network }}"

@ -2230,6 +2234,8 @@ matrix_hookshot_container_additional_networks_auto: |
      +
      ([keydb_container_network] if keydb_enabled and matrix_hookshot_cache_redis_host == keydb_identifier else [])
      +
+      ([valkey_container_network] if valkey_enabled and matrix_hookshot_cache_redis_host == valkey_identifier else [])
+      +
      ([matrix_playbook_reverse_proxyable_services_additional_network] if matrix_playbook_reverse_proxyable_services_additional_network and matrix_hookshot_container_labels_traefik_enabled else [])
    ) | unique
  }}
@ -4402,11 +4408,11 @@ ntfy_visitor_request_limit_exempt_hosts_hostnames_auto: |

 ######################################################################
 #
-# etke/redis
+# redis
 #
 ######################################################################

-redis_enabled: "{{ not keydb_enabled and (matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled)) }}"
+redis_enabled: "{{ not (keydb_enabled or valkey_enabled) and (matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled)) }}"

 redis_identifier: matrix-redis

@ -4417,7 +4423,7 @@ redis_base_path: "{{ matrix_base_data_path }}/redis"

 ######################################################################
 #
-# /etke/redis
+# /redis
 #
 ######################################################################

@ -4427,7 +4433,7 @@ redis_base_path: "{{ matrix_base_data_path }}/redis"
 #
 ######################################################################

-keydb_enabled: "{{ matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled) }}"
+keydb_enabled: false

 keydb_identifier: matrix-keydb

@ -4451,6 +4457,31 @@ keydb_arch: |-
 #
 ######################################################################

+
+######################################################################
+#
+# valkey
+#
+######################################################################
+
+valkey_enabled: "{{ matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled) }}"
+
+valkey_identifier: matrix-valkey
+
+valkey_uid: "{{ matrix_user_uid }}"
+valkey_gid: "{{ matrix_user_gid }}"
+
+valkey_base_path: "{{ matrix_base_data_path }}/valkey"
+
+valkey_arch: "{{ matrix_architecture }}"
+
+######################################################################
+#
+# valkey
+#
+######################################################################
+
+
 ######################################################################
 #
 # matrix-client-element
@ -4476,8 +4507,8 @@ matrix_client_element_container_labels_traefik_docker_network: "{{ matrix_playbo
 matrix_client_element_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
 matrix_client_element_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"

-matrix_client_element_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled }}"
-matrix_client_element_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_name if matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled else '' }}"
+matrix_client_element_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_client_element_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"

 matrix_client_element_default_hs_url: "{{ matrix_homeserver_url }}"
 matrix_client_element_default_is_url: "{{ matrix_identity_server_url }}"
@ -4528,8 +4559,8 @@ matrix_client_hydrogen_container_labels_traefik_docker_network: "{{ matrix_playb
 matrix_client_hydrogen_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
 matrix_client_hydrogen_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"

-matrix_client_hydrogen_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled }}"
-matrix_client_hydrogen_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_name if matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled else '' }}"
+matrix_client_hydrogen_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_client_hydrogen_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"

 matrix_client_hydrogen_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"

@ -4564,8 +4595,8 @@ matrix_client_cinny_container_labels_traefik_docker_network: "{{ matrix_playbook
 matrix_client_cinny_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
 matrix_client_cinny_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"

-matrix_client_cinny_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled }}"
-matrix_client_cinny_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_name if matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled else '' }}"
+matrix_client_cinny_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_client_cinny_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"

 matrix_client_cinny_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"

@ -4673,6 +4704,8 @@ matrix_synapse_container_additional_networks_auto: |
      +
      ([keydb_container_network] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == keydb_identifier else [])
      +
+      ([valkey_container_network] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == valkey_identifier else [])
+      +
      ([exim_relay_container_network] if (exim_relay_enabled and matrix_synapse_email_enabled and matrix_synapse_email_smtp_host == exim_relay_identifier and matrix_synapse_container_network != exim_relay_container_network) else [])
      +
      ([matrix_ma1sd_container_network] if (matrix_ma1sd_enabled and matrix_synapse_account_threepid_delegates_msisdn == matrix_synapse_account_threepid_delegates_msisdn_mas1sd_url and matrix_synapse_container_network != matrix_ma1sd_container_network) else [])
@ -4685,8 +4718,8 @@ matrix_synapse_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_prim
 matrix_synapse_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
 matrix_synapse_container_labels_traefik_hostname: "{{ matrix_server_fqn_matrix }}"

-matrix_synapse_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled }}"
-matrix_synapse_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_name if matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled else '' }}"
+matrix_synapse_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_synapse_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"

 matrix_synapse_container_labels_matrix_labels_enabled: "{{ not matrix_synapse_workers_enabled }}"

@ -4760,6 +4793,8 @@ matrix_synapse_systemd_required_services_list_auto: |
    +
    ([keydb_identifier ~ '.service'] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == keydb_identifier else [])
    +
+    ([valkey_identifier ~ '.service'] if matrix_synapse_redis_enabled and matrix_synapse_redis_host == valkey_identifier else [])
+    +
    (['matrix-goofys.service'] if matrix_s3_media_store_enabled else [])
    +
    (['matrix-authentication-service.service'] if (matrix_authentication_service_enabled and matrix_synapse_experimental_features_msc3861_enabled) else [])
@ -4773,9 +4808,9 @@ matrix_synapse_systemd_wanted_services_list_auto: |
  }}

 # Synapse workers (used for parallel load-scaling) need Redis for IPC.
-matrix_synapse_redis_enabled: "{{ redis_enabled or keydb_enabled }}"
-matrix_synapse_redis_host: "{{ redis_identifier if redis_enabled else (keydb_identifier if keydb_enabled else '') }}"
-matrix_synapse_redis_password: "{{ redis_connection_password if redis_enabled else (keydb_connection_password if keydb_enabled else '') }}"
+matrix_synapse_redis_enabled: "{{ redis_enabled or keydb_enabled or valkey_enabled }}"
+matrix_synapse_redis_host: "{{ valkey_identifier if valkey_enabled else (redis_identifier if redis_enabled else (keydb_identifier if keydb_enabled else '')) }}"
+matrix_synapse_redis_password: "{{ valkey_connection_password if valkey_enabled else (redis_connection_password if redis_enabled else (keydb_connection_password if keydb_enabled else '')) }}"

 matrix_synapse_container_extra_arguments_auto: "{{ matrix_homeserver_container_extra_arguments_auto }}"
 matrix_synapse_app_service_config_files_auto: "{{ matrix_homeserver_app_service_config_files_auto }}"
@ -4878,8 +4913,8 @@ matrix_synapse_reverse_proxy_companion_container_labels_traefik_entrypoints: "{{
 matrix_synapse_reverse_proxy_companion_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
 matrix_synapse_reverse_proxy_companion_container_labels_traefik_hostname: "{{ matrix_server_fqn_matrix }}"

-matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled }}"
-matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compession_name if matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled else '' }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_enabled: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled }}"
+matrix_synapse_reverse_proxy_companion_container_labels_traefik_compression_middleware_name: "{{ matrix_playbook_reverse_proxy_traefik_middleware_compression_name if matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled else '' }}"

 matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_client_api_enabled: "{{ matrix_synapse_container_labels_public_client_synapse_client_api_enabled }}"
 matrix_synapse_reverse_proxy_companion_container_labels_public_client_synapse_admin_api_enabled: "{{ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled }}"
--- a/requirements.yml
+++ b/requirements.yml
@ -4,13 +4,13 @@
  version: v1.0.0-5
  name: auxiliary
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg.git
-  version: v1.4.0-1.9.1-0
+  version: v1.4.0-1.9.2-1
  name: backup_borg
 - src: git+https://github.com/devture/com.devture.ansible.role.container_socket_proxy.git
  version: v0.2.0-0
  name: container_socket_proxy
 - src: git+https://github.com/geerlingguy/ansible-role-docker
-  version: 7.4.1
+  version: 7.4.2
  name: docker
 - src: git+https://github.com/devture/com.devture.ansible.role.docker_sdk_for_python.git
  version: 129c8590e106b83e6f4c259649a613c6279e937a
@ -22,7 +22,7 @@
  version: v4.98-r0-1-1
  name: exim_relay
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-grafana.git
-  version: v11.3.0-0
+  version: v11.3.1-0
  name: grafana
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-jitsi.git
  version: v9823-1
@ -43,7 +43,7 @@
  version: ff2fd42e1c1a9e28e3312bbd725395f9c2fc7f16
  name: playbook_state_preserver
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-postgres.git
-  version: v17.0-1
+  version: v17.0-2
  name: postgres
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-postgres-backup.git
  version: v16-0
@ -70,8 +70,11 @@
  version: v1.0.0-0
  name: timesync
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik.git
-  version: v3.2.0-1
+  version: v3.2.1-0
  name: traefik
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-traefik-certs-dumper.git
  version: v2.8.3-5
  name: traefik_certs_dumper
+- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-valkey.git
+  version: v8.0.1-0
+  name: valkey
--- a/roles/custom/matrix-alertmanager-receiver/defaults/main.yml
+++ b/roles/custom/matrix-alertmanager-receiver/defaults/main.yml
@ -6,7 +6,7 @@
 matrix_alertmanager_receiver_enabled: true

 # renovate: datasource=docker depName=docker.io/metio/matrix-alertmanager-receiver
-matrix_alertmanager_receiver_version: 2024.10.30
+matrix_alertmanager_receiver_version: 2024.11.20

 matrix_alertmanager_receiver_scheme: https

--- a/roles/custom/matrix-base/defaults/main.yml
+++ b/roles/custom/matrix-base/defaults/main.yml
@ -240,11 +240,11 @@ matrix_playbook_reverse_proxy_container_network: 'traefik'
 matrix_playbook_reverse_proxy_hostname: 'matrix-traefik'

 # Specifies whether the Traefik reverse-proxy (if `matrix_playbook_reverse_proxy_type` indicates that Traefik is being used) defines a compression middleware.
-matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled: false
+matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled: false

 # Specifies the name of the compression middleware defined for the Traefik reverse-proxy (if `matrix_playbook_reverse_proxy_type` indicates that Traefik is being used).
 # It's better to use a fully-qualified middleware name (e.g. `compression@docker` or `compression@file`) here to prevent ambiguity.
-matrix_playbook_reverse_proxy_traefik_middleware_compession_name: ''
+matrix_playbook_reverse_proxy_traefik_middleware_compression_name: ''

 # Controls the additional network that reverse-proxyable services will be connected to.
 matrix_playbook_reverse_proxyable_services_additional_network: "{{ matrix_playbook_reverse_proxy_container_network }}"
--- a/roles/custom/matrix-bot-baibot/defaults/main.yml
+++ b/roles/custom/matrix-bot-baibot/defaults/main.yml
@ -11,7 +11,7 @@ matrix_bot_baibot_container_repo_version: "{{ 'main' if matrix_bot_baibot_versio
 matrix_bot_baibot_container_src_files_path: "{{ matrix_base_data_path }}/baibot/container-src"

 # renovate: datasource=docker depName=ghcr.io/etkecc/baibot
-matrix_bot_baibot_version: v1.3.2
+matrix_bot_baibot_version: v1.4.0
 matrix_bot_baibot_container_image: "{{ matrix_bot_baibot_container_image_name_prefix }}etkecc/baibot:{{ matrix_bot_baibot_version }}"
 matrix_bot_baibot_container_image_name_prefix: "{{ 'localhost/' if matrix_bot_baibot_container_image_self_build else 'ghcr.io/' }}"
 matrix_bot_baibot_container_image_force_pull: "{{ matrix_bot_baibot_container_image.endswith(':latest') }}"
--- a/roles/custom/matrix-client-element/defaults/main.yml
+++ b/roles/custom/matrix-client-element/defaults/main.yml
@ -11,7 +11,7 @@ matrix_client_element_container_image_self_build_repo: "https://github.com/eleme
 matrix_client_element_container_image_self_build_low_memory_system_patch_enabled: "{{ ansible_memtotal_mb < 4096 }}"

 # renovate: datasource=docker depName=vectorim/element-web
-matrix_client_element_version: v1.11.85
+matrix_client_element_version: v1.11.86

 matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:{{ matrix_client_element_version }}"
 matrix_client_element_docker_image_name_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else matrix_container_global_registry_prefix }}"
--- a/roles/custom/matrix-synapse-admin/defaults/main.yml
+++ b/roles/custom/matrix-synapse-admin/defaults/main.yml
@ -14,7 +14,7 @@ matrix_synapse_admin_container_image_self_build: false
 matrix_synapse_admin_container_image_self_build_repo: "https://github.com/etkecc/synapse-admin.git"

 # renovate: datasource=docker depName=ghcr.io/etkecc/synapse-admin
-matrix_synapse_admin_version: v0.10.3-etke30
+matrix_synapse_admin_version: v0.10.3-etke31
 matrix_synapse_admin_docker_image: "{{ matrix_synapse_admin_docker_image_name_prefix }}etkecc/synapse-admin:{{ matrix_synapse_admin_version }}"
 matrix_synapse_admin_docker_image_name_prefix: "{{ 'localhost/' if matrix_synapse_admin_container_image_self_build else 'ghcr.io/' }}"
 matrix_synapse_admin_docker_image_force_pull: "{{ matrix_synapse_admin_docker_image.endswith(':latest') }}"
--- a/roles/custom/matrix-synapse/defaults/main.yml
+++ b/roles/custom/matrix-synapse/defaults/main.yml
@ -370,6 +370,27 @@ matrix_synapse_media_retention_remote_media_lifetime:
 # Controls the list of additional oembed providers to be added to the homeserver.
 matrix_synapse_oembed_additional_providers: []

+# Controls message retention policies
+matrix_synapse_retention_enabled: false
+# "A single var to control them all" - applied to all retention period vars, applied only if a value is set, e.g. : "1d", "1w", "1m", "1y"
+matrix_synapse_retention_period: ""
+# The default min lifetime, applied only if a value is set, e.g. : "1d", "1w", "1m", "1y"
+matrix_synapse_retention_default_policy_min_lifetime: "{{ matrix_synapse_retention_period }}"
+# The default max lifetime, applied only if a value is set, e.g. : "1d", "1w", "1m", "1y"
+matrix_synapse_retention_default_policy_max_lifetime: "{{ matrix_synapse_retention_period }}"
+# The allowed min lifetime, applied only if a value is set, e.g. : "1d", "1w", "1m", "1y"
+matrix_synapse_retention_allowed_lifetime_min: "{{ matrix_synapse_retention_period }}"
+# The allowed max lifetime, applied only if a value is set, e.g. : "1d", "1w", "1m", "1y"
+matrix_synapse_retention_allowed_lifetime_max: "{{ matrix_synapse_retention_period }}"
+# The list of the purge jobs, structure (all fields are optional, example below contains all available variants):
+# - longest_max_lifetime: "1d"
+#   shortest_max_lifetime: "1d"
+#   interval: "12h"
+# - longest_max_lifetime: "1d"
+# - shortest_max_lifetime: "1d"
+# - interval: "12h"
+matrix_synapse_retention_purge_jobs: []
+
 # The tmpfs at /tmp needs to be large enough to handle multiple concurrent file uploads.
 matrix_synapse_tmp_directory_size_mb: "{{ matrix_synapse_max_upload_size_mb * 50 }}"

--- a/roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2
+++ b/roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2
@ -590,26 +590,37 @@ templates:
 # purged are ignored and not stored again.
 #
 retention:
+  {% if matrix_synapse_retention_enabled %}
  # The message retention policies feature is disabled by default. Uncomment the
  # following line to enable it.
  #
-  #enabled: true
+  enabled: {{ matrix_synapse_retention_enabled|to_json }}

  # Default retention policy. If set, Synapse will apply it to rooms that lack the
  # 'm.room.retention' state event. Currently, the value of 'min_lifetime' doesn't
  # matter much because Synapse doesn't take it into account yet.
  #
-  #default_policy:
-  #  min_lifetime: 1d
-  #  max_lifetime: 1y
+  {% if matrix_synapse_retention_default_policy_min_lifetime | length > 0 or matrix_synapse_retention_default_policy_max_lifetime | length > 0 %}
+  default_policy:
+  {% if matrix_synapse_retention_default_policy_min_lifetime | length > 0 %}
+    min_lifetime: {{ matrix_synapse_retention_default_policy_min_lifetime|to_json }}
+  {% endif %}
+  {% if matrix_synapse_retention_default_policy_max_lifetime | length > 0 %}
+    max_lifetime: {{ matrix_synapse_retention_default_policy_max_lifetime|to_json }}
+  {% endif %}
+  {% endif %}

  # Retention policy limits. If set, and the state of a room contains a
  # 'm.room.retention' event in its state which contains a 'min_lifetime' or a
  # 'max_lifetime' that's out of these bounds, Synapse will cap the room's policy
  # to these limits when running purge jobs.
  #
-  #allowed_lifetime_min: 1d
-  #allowed_lifetime_max: 1y
+  {% if matrix_synapse_retention_allowed_lifetime_min | length > 0 %}
+  allowed_lifetime_min: {{ matrix_synapse_retention_allowed_lifetime_min|to_json }}
+  {% endif %}
+  {% if matrix_synapse_retention_allowed_lifetime_max | length > 0 %}
+  allowed_lifetime_max: {{ matrix_synapse_retention_allowed_lifetime_max|to_json }}
+  {% endif %}

  # Server admins can define the settings of the background jobs purging the
  # events which lifetime has expired under the 'purge_jobs' section.
@ -640,12 +651,8 @@ retention:
  # room's policy to these values is done after the policies are retrieved from
  # Synapse's database (which is done using the range specified in a purge job's
  # configuration).
-  #
-  #purge_jobs:
-  #  - longest_max_lifetime: 3d
-  #    interval: 12h
-  #  - shortest_max_lifetime: 3d
-  #    interval: 1d
+  purge_jobs: {{ matrix_synapse_retention_purge_jobs | to_json }}
+  {% endif %}


 ## TLS ##
--- a/roles/custom/matrix_playbook_migration/tasks/validate_config.yml
+++ b/roles/custom/matrix_playbook_migration/tasks/validate_config.yml
@ -56,6 +56,7 @@
    - {'old': 'matrix_prometheus_scraper_hookshot_targets', 'new': '<superseded by matrix_prometheus_services_connect_scraper_hookshot_static_configs_target>'}
    - {'old': 'matrix_prometheus_scraper_nginxlog_enabled', 'new': 'matrix_prometheus_services_connect_scraper_nginxlog_enabled'}
    - {'old': 'matrix_prometheus_scraper_nginxlog_server_port', 'new': 'matrix_prometheus_services_connect_scraper_nginxlog_static_configs_target'}
+
    - {'old': 'matrix_prosody_jitsi_max_participants', 'new': 'jitsi_prosody_max_participants'}
    - {'old': 'jitsi_require_well_known', 'new': 'jitsi_web_well_known_element_jitsi_enabled'}
    - {'old': 'jitsi_wellknown_element_jitsi_json', 'new': 'jitsi_web_well_known_element_jitsi_json'}
@ -63,6 +64,9 @@
    - {'old': 'exim_relay_docker_image_name_prefix', 'new': 'exim_relay_container_image_name_prefix'}
    - {'old': 'exim_relay_docker_image_force_pull', 'new': 'exim_relay_container_image_force_pull'}

+    - {'old': 'matrix_playbook_reverse_proxy_traefik_middleware_compession_enabled', 'new': 'matrix_playbook_reverse_proxy_traefik_middleware_compression_enabled'}
+    - {'old': 'matrix_playbook_reverse_proxy_traefik_middleware_compession_name', 'new': 'matrix_playbook_reverse_proxy_traefik_middleware_compression_name'}
+
 - name: (Deprecation) Catch and report matrix_postgres variables
  ansible.builtin.fail:
    msg: |-
--- a/setup.yml
+++ b/setup.yml
@ -49,6 +49,8 @@

    - galaxy/redis
    - galaxy/keydb
+    - galaxy/valkey
+
    - role: custom/matrix-authentication-service
    - custom/matrix-corporal
    - custom/matrix-appservice-draupnir-for-all