Merge 9cb2a3d9270192a779cb2287ed7be0f607a1f61d into d1fa7378f73f58fd8d89948af8d6de177f55caf7

* set localpart of hookshot bot in main.yml

* set sender_localpart in registration.yml.j2 template to variable

* prettier location for bot localpart in main.yml

* Update main.yml

* Update registration.yml.j2

---------

Co-authored-by: Slavi Pantaleev <slavi@devture.com>

.github/workflows/close-stale-issues.yml

@@ -1,11 +1,14 @@
 ---
-name: 'Close stale issues'
+name: 'Close stale issues and PRs'
 on:  # yamllint disable-line rule:truthy
+  # Use this to do a dry run from a pull request
+  # pull_request:
   schedule:
     - cron: '30 1 * * *'
 
 permissions:
   issues: write
+  pull-requests: write
 
 jobs:
   stale:
@@ -14,14 +17,34 @@ jobs:
     steps:
       - uses: actions/stale@v9
         with:
-          # Don't process pull requests at all
+          ######################################################################
-          days-before-pr-stale: -1
+          # Issues/PRs
-          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.'
+          ######################################################################
+          exempt-assignees: 'spantaleev,aine-etke'
+          operations-per-run: 100
+          # Use this to do a dry run from a pull request
+          # debug-only: true
+          ######################################################################
+          # Issues
+          ######################################################################
+          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. To exempt the issue from being marked as stale again due to inactivity, add "confirmed" label.'
           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'
+          any-of-issue-labels: 'needs-info,question'
-          # Use this to do a dry run from a pull request
+          ######################################################################
-          # debug-only: true
+          # PRs
+          ######################################################################
+          days-before-pr-stale: '365'
+          days-before-pr-close: '30'
+          stale-pr-message: 'This PR is stale because it has not been provided with required information or its conflicts have not been fixed over a year. Remove stale label or this will be closed in 30 days. To exempt the PR from being marked as stale again due to inactivity, add "confirmed" label.'
+          close-pr-message: 'This PR was closed because it has been stalled for 30 days with no activity.'
+          stale-pr-label: 'stale'
+          # Add this label to exempt the PR from being marked as stale due to inactivity
+          exempt-pr-labels: 'confirmed'
+          # An allow-list of label(s) to only process the PRs which contain one of these label(s).
+          any-of-pr-labels: 'needs-info,needs-rebase'
+          # Use this to ignore updates such as comments (only to keep the PR alive by bumping)
+          ignore-pr-updates: true

CHANGELOG.md

@@ -1,3 +1,64 @@
+# 2024-11-26
+
+## (Backward Compatibility Break) Synapse now defaults to enabling authenticated media
+
+**TLDR**: with this update, your Synapse homeserver will start requiring authentication for newly-uploaded media files. While the majority of the ecosystem (clients, bots, etc.) should support this, certain software may lack support for it (and you may wish to turn it off, if it's causing issues).
+
+The default configuration for the Synapse homeserver now [enforces Authenticated media by default](https://element-hq.github.io/synapse/v1.120/upgrade.html#authenticated-media-is-now-enforced-by-default).
+
+Servers like `matrix.org` have already [sunset unauthenticated media](https://matrix.org/blog/2024/06/26/sunsetting-unauthenticated-media/) months ago.
+
+Now that **various clients, bots, bridges and extra services have caught up with authenticated media support**, Synapse developers seem confident that it's time to enable authenticated media by default.
+
+We're changing the playbook configuration for authenticated media to keep up with upstream defaults changing.
+
+Old and unmaintained bridges (like all mx-puppet bridges, etc.) do not support authenticated media. Other software may be similarly affected. If you experience issues with some Matrix-related software, you may wish to disable authenticated media and contact the software maintainers to let them know.
+
+You can disable authenticated media at any time by setting `matrix_synapse_enable_authenticated_media: false` in your `vars.yml` configuration file and re-running the playbook.
+
+
+# 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
@@ -102,7 +163,6 @@ It's designed as a more private and [✨ featureful](https://github.com/etkecc/b
 
 To get started, see the [Setting up baibot](./docs/configuring-playbook-bot-baibot.md) documentation page.
 
-
 ## Switching synapse-admin to etke.cc's fork
 
 The playbook now installs [etke.cc](https://etke.cc/)'s [fork](https://github.com/etkecc/synapse-admin) of [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) (originally developed by [Awesome-Technologies](https://github.com/Awesome-Technologies)). This fork is a drop-in replacement for the original software.
@@ -113,7 +173,7 @@ If upstream synapse-admin picks up the pace and improves, the etke.cc fork may d
 
 If you'd like to switch back to the original synapse-admin software, you can do so by adding the following configuration to your `vars.yml` file:
 
-```yml
+```yaml
 matrix_synapse_admin_docker_image: "{{ matrix_synapse_admin_docker_image_name_prefix }}awesometechnologies/synapse-admin:{{ matrix_synapse_admin_version }}"
 matrix_synapse_admin_docker_image_name_prefix: "{{ 'localhost/' if matrix_synapse_admin_container_image_self_build else matrix_container_global_registry_prefix }}"
 
@@ -138,7 +198,7 @@ All non-deprecated mautrix bridges in the playbook have been reworked to support
 
 We recommend **enabling double-puppeting via the new Appservice method** by adding the following configuration to your `vars.yml` file:
 
-```yml
+```yaml
 matrix_appservice_double_puppet_enabled: true
 ```
 
@@ -170,7 +230,7 @@ This upgrade necessitates configuration policy changes as described in [matrix-c
 
 If you'd like to remain on the old (v2) version of matrix-corporal, you can do so by adding the following configuration to your `vars.yml` file:
 
-```yml
+```yaml
 matrix_corporal_version: 2.8.0
 ```
 
@@ -191,7 +251,6 @@ For those wishing to more easily integrate [Prometheus](https://prometheus.io/)'
 
 See [Setting up Prometheus Alertmanager integration via matrix-alertmanager-receiver](./docs/configuring-playbook-alertmanager-receiver.md) for more details.
 
-
 ## Traefik v3 and HTTP/3 are here now
 
 **TLDR**: Traefik was migrated from v2 to v3. Minor changes were done to the playbook. Mostly everything else worked out of the box. Most people will not have to do any tweaks to their configuration. In addition, [HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) support is now auto-enabled for the `web-secure` (port 443) and `matrix-federation` (port `8448`) entrypoints. If you have a firewall in front of your server and you wish to benefit from `HTTP3`, you will need to open the `443` and `8448` UDP ports in it.
@@ -212,7 +271,6 @@ If you've tweaked any of this playbook's `_path_prefix` variables and made them
 
 If you're not using [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) (the only role we had to tweak to adapt it to Traefik v3), you **may potentially downgrade to Traefik v2** (if necessary) by adding `traefik_verison: v2.11.4` to your configuration. People using `matrix-media-repo` cannot downgrade this way, because `matrix-media-repo` has been adjusted to use `PathRegexp` - a [routing matcher](https://doc.traefik.io/traefik/v2.11/routing/routers/#rule) that Traefik v2 does not understand.
 
-
 ### HTTP/3 is enabled by default
 
 In Traefik v3, [HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) support is no longer considered experimental now.
@@ -226,7 +284,7 @@ Still, if HTTP/3 cannot function correctly in your setup, it's best to disable a
 
 To **disable HTTP/3**, you can use the following configuration:
 
-```yml
+```yaml
 traefik_config_entrypoint_web_secure_http3_enabled: false
 
 # Disabling HTTP/3 for the web-secure entrypoint (above),
@@ -240,7 +298,7 @@ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_http3_ena
 
 If you are using [your own webserver](./docs/configuring-playbook-own-webserver.md) (in front of Traefik), port binding on UDP port `8448` by default due to HTTP/3 is either unnecessary or [may get in the way](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3402). If it does, you can disable it:
 
-```yml
+```yaml
 # Disable HTTP/3 for the federation entrypoint.
 # If you'd like HTTP/3, consider configuring it for your other reverse-proxy.
 #
@@ -261,7 +319,7 @@ The playbook has just started making use of this feature. **From now on, your sy
 
 If you'd like **to go back to the old unrestricted behavior**, use the following configuration:
 
-```yml
+```yaml
 # Use this configuration to allow synapse-admin to manage any homeserver instance.
 matrix_synapse_admin_config_restrictBaseUrl: []
 ```
@@ -281,12 +339,11 @@ To avoid future problems, we've [reconfigured](https://github.com/spantaleev/mat
 
 When generating new webhooks, you should start seeing the new URLs being used.
 
-**For now**, **both** old URLs (`/hookshot/webhooks/:hookId`) and new URLs (`/hookshot/webhooks/webhook/:hookId`) **continue to work***, so your webhooks will not break just yet.
+**For now**, **both** old URLs (`/hookshot/webhooks/:hookId`) and new URLs (`/hookshot/webhooks/webhook/:hookId`) **continue to work**, so your webhooks will not break just yet.
 
 However, **we recommend that you update all your old webhook URLs** (configured in other systems) to include the new `/webhook` path component, so that future Hookshot changes (whenever they come) will not break your webhooks. You don't need to do anything on the Hookshot side - you merely need to reconfigure the remote systems that use your webhook URLs.
 
 
-
 # 2024-06-22
 
 ## The maubot user is now managed by the playbook
@@ -326,14 +383,13 @@ Users on `arm32` should be aware that there's **neither a prebuilt `arm32` conta
 
 **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
+```yaml
 # Explicitly disable KeyDB, which will auto-enable Redis
 # if the playbook requires it as a dependency for its operation.
 keydb_enabled: false
 ```
 
 
-
 # 2024-03-24
 
 ## Initial work on IPv6 support
@@ -503,7 +559,6 @@ Due to complexity and the playbook's flexibility (trying to accommodate a mix of
 
 After **a ton of work** in the last weeks (200+ commits, which changed 467 files - 8684 insertions and 8913 deletions), **we're finally saying goodbye** to `matrix-nginx-proxy`.
 
-
 ### Going Traefik-native and cutting out all middlemen
 
 In our new setup, you'll see the bare minimum number of reverse-proxies.
@@ -513,7 +568,6 @@ In most cases, there's only Traefik and all services being registered directly w
 This reduces "network" hops (improving performance) and also decreases the number of components (containers).
 Each Ansible role in our setup is now independent and doesn't need to interact with other roles during runtime.
 
-
 ### Traefik now has an extra job
 
 Previously, **Traefik had a single purpose** - being the main reverse-proxy. It was either front-most (terminating SSL, etc.) or you were [fronting Traefik with your own other reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy). In any case - it had this central (yet decentralized) job.
@@ -539,21 +593,18 @@ People running the default Traefik setup do not need to do anything to make Trae
 
 You may disable Traefik acting as an intermediary by explicitly setting `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled` to `false`. Services would then be configured to talk to the homeserver directly, giving you a slight performance boost and a "simpler" Traefik setup. However, such a configuration is less tested and will cause troubles, especially if you enable more services (like `matrix-media-repo`, etc.) in the future. As such, it's not recommended.
 
-
 ### People managing their own Traefik instance need to do minor changes
 
 This section is for people [managing their own Traefik instance on the Matrix server](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you). Those [using Traefik managed by the playbook](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-the-playbook) don't need to do any changes.
 
 Because [Traefik has an extra job now](#traefik-now-has-an-extra-job), you need to adapt your configuration to add the additional `matrix-internal-matrix-client-api` entrypoint and potentially configure the `matrix_playbook_reverse_proxy_container_network` variable. See the [Traefik managed by you](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you) documentation section for more details.
 
-
 ### People fronting Traefik with another reverse proxy need to do minor changes
 
 We've already previously mentioned that you need to do some minor [configuration changes related to `traefik_additional_entrypoints_auto`](#backward-compatibility-configuration-changes-required-for-people-fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy).
 
 If you don't do these changes (switching from `traefik_additional_entrypoints_auto` to multiple other variables), your Traefik setup will not automatically receive the new `matrix-internal-matrix-client-api` Traefik entrypoint and Traefik would not be able to perform [its new duty of connecting addons with the homeserver](#traefik-now-has-an-extra-job).
 
-
 ### Supported reverse proxy types are now fewer
 
 This section is for people using a more custom reverse-proxy setup - those having `matrix_playbook_reverse_proxy_type` set to a value different than the default (`playbook-managed-traefik`).
@@ -575,7 +626,6 @@ If you were using these values as a way to stay away from Traefik, you now have
 - (recommended) [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy)
 - (not recommended) [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all) and reverse-proxying to each and every service manually
 
-
 ### Container networking changes
 
 Now that `matrix-nginx-proxy` is not in the mix, it became easier to clear out some other long-overdue technical debt.
@@ -590,7 +640,6 @@ Carrying out these container networking changes necessitated modifying many comp
 
 We've refrained from creating too many container networks (e.g. one for each component), to avoid exhausting Docker's default network pool and contaminating the container networks list too much.
 
-
 ### Metrics exposure changes
 
 This section is for people who are exposing monitoring metrics publicly, to be consumed by an external Prometheus server.
@@ -603,7 +652,6 @@ From now on, there are new variables for doing roughly the same - `matrix_metric
 
 The playbook will tell you about all variables that you need to migrate during runtime, so rest assured - you shouldn't be able to miss anything!
 
-
 ### Matrix static files
 
 As mentioned above, static files like `/.well-known/matrix/*` or your base domain's `index.html` file (when [serving the base domain via the Matrix server](./docs/configuring-playbook-base-domain-serving.md) was enabled) were generated by the `matrix-base` or `matrix-nginx-proxy` roles and put into a `/matrix/static-files` directory on the server. Then `matrix-nginx-proxy` was serving all these static files.
@@ -612,7 +660,6 @@ All of this has been extracted into a new `matrix-static-files` Ansible role tha
 
 The playbook will migrate and update the `/.well-known/matrix/*` files automatically but not your own files in `nginx-proxy/data/matrix-domain/` you will need to back these up yourself otherwise they will be lost. It will also warn you about usage of old variable names, so you can adapt to the new names.
 
-
 ### A note on performance
 
 Some of you have been voicing their concerns (for a long time) about Traefik being too slow and nginx being better.
@@ -627,7 +674,6 @@ Even our previously mentioned benchmarks (yielding ~1300 rps) are synthetic - hi
 
 If this is still not convincing enough for you and you want the best possible performance, consider [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) (thus having the slowest part - SSL termination - happen elsewhere) or [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all). The playbook will not get in your way of doing that, but these options may make your life much harder. Performance comes at a cost, after all.
 
-
 ### Migration procedure
 
 The updated playbook will automatically perform some migration tasks for you:
@@ -649,7 +695,6 @@ We don't recommend changing these variables and suppressing warnings, unless you
 **Most people should just upgrade as per-normal**, bearing in mind that a lot has changed and some issues may arise.
 The playbook would guide you through renamed variables automatically.
 
-
 ### Conclusion
 
 Thousands of lines of code were changed across hundreds of files.
@@ -1177,7 +1222,6 @@ Some services (like [Coturn](docs/configuring-playbook-turn.md) and [Postmoogle]
 
 Our Traefik setup mostly works, but certain esoteric features may not work. If you have a default setup, we expect you to have a good experience.
 
-
 ### Where we're going in the near future?
 
 The `matrix-nginx-proxy` role is quite messy. It manages both nginx and Certbot and its certificate renewal scripts and timers. It generates configuration even when the role is disabled (weird). Although it doesn't directly reach into variables from other roles, it has explicit awareness of various other services that it reverse-proxies to (`roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2`, etc.). We'd like to clean this up. The only way is probably to just get rid of the whole thing at some point.
@@ -1210,7 +1254,6 @@ Thanks to [Jakob S.](https://github.com/jakicoll) ([zakk gGmbH](https://github.c
 
 Additional details are available in the [Authenticate using Matrix OpenID (Auth-Type 'matrix')](docs/configuring-playbook-jitsi.md#authenticate-using-matrix-openid-auth-type-matrix).
 
-
 ## Draupnir moderation tool (bot) support
 
 Thanks to [FSG-Cat](https://github.com/FSG-Cat), the playbook can now install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool (bot). Draupnir is a fork of [Mjolnir](docs/configuring-playbook-bot-mjolnir.md) (which the playbook has supported for a long time) maintained by Mjolnir's former lead developer.
@@ -1250,7 +1293,6 @@ This, however, means that **you will need to ensure these ports are open** in yo
 
 Thanks to us [tightening Coturn security](#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues), running Coturn with host-networking should be safe and not expose neither other services running on the host, nor other services running on the local network.
 
-
 ## (Backward Compatibility) Tightening Coturn security can lead to connectivity issues
 
 **TLDR**: users who run and access their Matrix server on a private network (likely a small minority of users) may experience connectivity issues with our new default Coturn blocklists. They may need to override `matrix_coturn_denied_peer_ips` and remove some IP ranges from it.
@@ -1293,7 +1335,7 @@ Our [justfile](justfile) already defines some additional helpful **shortcut** co
 - `just run-tags install-mautrix-slack,start` - to run specific playbook tags
 - `just start-all` - (re-)starts all services
 - `just stop-group postgres` - to stop only the Postgres service
-- `just register-user john secret-password yes` - registers a `john` user with the `secret-password` password and admin access (admin = `yes`)
+- `just register-user alice secret-password yes` - registers an `alice` user with the `secret-password` password and admin access (admin = `yes`)
 
 Additional helpful commands and shortcuts may be defined in the future.
 
@@ -1498,7 +1540,6 @@ This is not just for initial installations. Users with existing files (stored in
 
 To get started, see our [Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider](docs/configuring-playbook-synapse-s3-storage-provider.md) documentation.
 
-
 ## Synapse container image customization support
 
 We now support customizing the Synapse container image by adding additional build steps to its [`Dockerfile`](https://docs.docker.com/engine/reference/builder/).
@@ -1712,7 +1753,6 @@ If you still need bridging to [Skype](https://www.skype.com/), consider switchin
 
 If you think this is a mistake and `mx-puppet-skype` works for you (or you get it to work somehow), let us know and we may reconsider this removal.
 
-
 ## signald (0.19.0+) upgrade requires data migration
 
 In [Pull Request #1921](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1921) we upgraded [signald](https://signald.org/) (used by the mautrix-signal bridge) from `v0.18.5` to `v0.20.0`.
@@ -1844,7 +1884,6 @@ Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the
 
 See our [Setting up BorgBackup](docs/configuring-playbook-backup-borg.md) documentation to get started.
 
-
 ## (Compatibility Break) Upgrading to Synapse v1.57 on setups using workers may require manual action
 
 If you're running a worker setup for Synapse (`matrix_synapse_workers_enabled: true`), the [Synapse v1.57 upgrade notes](https://github.com/element-hq/synapse/blob/v1.57.0rc1/docs/upgrade.md#changes-to-database-schema-for-application-services) say that you may need to take special care when upgrading:
@@ -1960,7 +1999,6 @@ matrix_homeserver_implementation: dendrite
 
 We're excited to gain support for other homeserver implementations, like [Conduit](https://conduit.rs/), etc!
 
-
 ## Honoroit bot support
 
 Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now help you set up [Honoroit](https://github.com/etkecc/honoroit) - a helpdesk bot.
@@ -2083,7 +2121,6 @@ Thanks to [foxcris](https://github.com/foxcris), the playbook can now make autom
 Additional details are available in [Setting up postgres backup](docs/configuring-playbook-postgres-backup.md).
 
 
-
 # 2021-04-03
 
 ## Mjolnir moderation tool (bot) support
@@ -2410,7 +2447,6 @@ We've removed support for the unmaintained [synapse-janitor](https://github.com/
 
 If you need to clean up or compact your database, consider using the Synapse Admin APIs directly. See our [Synapse maintenance](docs/maintenance-synapse.md) and [Postgres maintenance](docs/maintenance-postgres.md) documentation pages for more details.
 
-
 ## Docker 20.10 is here
 
 (No need to do anything special in relation to this. Just something to keep in mind)
@@ -2739,7 +2775,7 @@ You can now customize the server name string that Riot-web displays in its login
 
 These playbook variables, with these default values, have been added:
 
-```
+```yaml
 matrix_riot_web_default_server_name: "{{ matrix_domain }}"
 ```
 
@@ -2767,7 +2803,7 @@ Still, we might become affected in the future. In any case, it's imminent that S
 
 To avoid future problems, we recommend that you run the following command:
 
-```
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres --extra-vars='{"postgres_force_upgrade": true}'
 ```
 
@@ -2938,7 +2974,6 @@ This greatly reduces the number of log messages that are being logged, leading t
 If you'd like to track down an issue, you [can always increase the logging level as described here](./docs/maintenance-and-troubleshooting.md#increasing-synapse-logging).
 
 
-
 # 2019-07-08
 
 ## Synapse Maintenance docs and synapse-janitor support are available
@@ -2949,7 +2984,6 @@ There's a new documentation page about [Synapse maintenance](./docs/maintenance-
 
 Among other things, if your Postgres database has grown significantly over time, you may wish to [ask the playbook to purge unused data with synapse-janitor](./docs/maintenance-synapse.md#purging-unused-data-with-synapse-janitor) for you.
 
-
 ## (BC Break) Rename run control variables
 
 Some internal playbook control variables have been renamed.
@@ -3161,7 +3195,6 @@ If you're using your own Synapse instance (especially one not running in a conta
 
 Having Synapse not be a required component potentially opens the door for installing alternative Matrix homeservers.
 
-
 ## Bridges are now separate from the Synapse role
 
 Bridges are no longer part of the `matrix-synapse` role.
@@ -3169,7 +3202,6 @@ Each bridge now lives in its own separate role (`roles/custom/matrix-bridge-*`).
 
 These bridge roles are independent of the `matrix-synapse` role, so it should be possible to use them with a Synapse instance installed another way (not through the playbook).
 
-
 ## Renaming inconsistently-named Synapse variables
 
 For better consistency, the following variables have been renamed:
@@ -3228,7 +3260,7 @@ The certificates from the Matrix domain will be used for the Coturn server.
 This feature is enabled by default for new installations.
 To make use of TLS support for your existing Matrix server's Coturn, make sure to rebuild both Coturn and Synapse:
 
-```bash
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-coturn,setup-synapse,start
 ```
 
@@ -3250,7 +3282,6 @@ If you don't have a dedicated server for your base domain and want to set up [Se
 It's now possible for the playbook to obtain an SSL certificate and serve the necessary files for Matrix Server Delegation on your base domain.
 Take a look at the new [Serving the base domain](docs/configuring-playbook-base-domain-serving.md) documentation page.
 
-
 ## (BC break) matrix-nginx-proxy data variable renamed
 
 `matrix_nginx_proxy_data_path` was renamed to `matrix_nginx_proxy_base_path`.
@@ -3374,7 +3405,6 @@ Containers are given write access only to the directories they need to write to.
 A minor breaking change is the `matrix_nginx_proxy_proxy_matrix_client_api_client_max_body_size` variable having being renamed to `matrix_nginx_proxy_proxy_matrix_client_api_client_max_body_size_mb` (note the `_mb` suffix). The new variable expects a number value (e.g. `25M` -> `25`).
 If you weren't customizing this variable, this wouldn't affect you.
 
-
 ## matrix-mailer is now based on Exim, not Postfix
 
 While we would have preferred to stay with [Postfix](http://www.postfix.org/), we found out that it cannot run as a non-root user.
@@ -3494,7 +3524,6 @@ For people who use Let's Encrypt (mostly everyone, since it's the default), you'
 - before: `host_specific_matrix_ssl_support_email`
 - after: `host_specific_matrix_ssl_lets_encrypt_support_email`
 
-
 ## (BC Break) mxisd upgrade with multiple base DN support
 
 mxisd has bee upgraded to [version 1.2.2](https://github.com/kamax-matrix/mxisd/releases/tag/v1.2.2), which supports [multiple base DNs](https://github.com/kamax-matrix/mxisd/blob/v1.2.2/docs/stores/ldap.md#base).
@@ -3567,7 +3596,7 @@ The playbook now allows you to set the log levels used by Synapse. The default l
 
 You can now override following variables with any of the supported log levels listed here: https://docs.python.org/3/library/logging.html#logging-levels
 
-```
+```yaml
 matrix_synapse_log_level: "INFO"
 matrix_synapse_storage_sql_log_level: "INFO"
 matrix_synapse_root_log_level: "INFO"
@@ -3580,7 +3609,7 @@ matrix_synapse_root_log_level: "INFO"
 
 You can now customize some parts of Riot's `config.json`. These playbook variables, with these default values, have been added:
 
-```
+```yaml
 matrix_riot_web_disable_custom_urls: true
 matrix_riot_web_disable_guests: true
 matrix_riot_web_integrations_ui_url: "https://scalar.vector.im/"
@@ -3591,7 +3620,7 @@ matrix_riot_web_integrations_jitsi_widget_url: "https://scalar.vector.im/api/wid
 
 This now allows you use a custom integration manager like [Dimension](https://dimension.t2bot.io). For example, if you wish to use the Dimension instance hosted at dimension.t2bot.io, you can set the following in your vars.yml file:
 
-```
+```yaml
 matrix_riot_web_integrations_ui_url: "https://dimension.t2bot.io/riot"
 matrix_riot_web_integrations_rest_url: "https://dimension.t2bot.io/api/v1/scalar"
 matrix_riot_web_integrations_widgets_urls: "https://dimension.t2bot.io/widgets"
@@ -3615,7 +3644,6 @@ The playbook now installs [Postgres 11](https://www.postgresql.org/about/news/18
 
 If you have have an existing setup, it's likely running on an older Postgres version (9.x or 10.x). You can easily upgrade by following the [upgrading PostgreSQL guide](docs/maintenance-postgres.md#upgrading-postgresql).
 
-
 ## (BC Break) Renaming playbook variables
 
 Due to the large amount of features added to this playbook lately, to keep things manageable we've had to reorganize its configuration variables a bit.
@@ -3705,7 +3733,6 @@ The playbook now helps you set up [service discovery](https://matrix.org/docs/sp
 
 Additional details are available in [Configuring service discovery via .well-known](docs/configuring-well-known.md).
 
-
 ## (BC Break) Renaming playbook variables
 
 The following playbook variables were renamed:
@@ -3722,19 +3749,16 @@ The playbook now supports bridging with [Telegram](https://telegram.org/) by ins
 
 Additional details are available in [Setting up Mautrix Telegram bridging](docs/configuring-playbook-bridge-mautrix-telegram.md).
 
-
 ## Events cache size increase and configurability for Matrix Synapse
 
 The playbook now lets you configure Matrix Synapse's `event_cache_size` configuration via the `matrix_synapse_event_cache_size` playbook variable.
 
 Previously, this value was hardcoded to `"10K"`. From now on, a more reasonable default of `"100K"` is used.
 
-
 ## Password-peppering support for Matrix Synapse
 
 The playbook now supports enabling password-peppering for increased security in Matrix Synapse via the `matrix_synapse_password_config_pepper` playbook variable. Using a password pepper is disabled by default (just like it used to be before this playbook variable got introduced) and is not to be enabled/disabled after initial setup, as that would invalidate all existing passwords.
 
-
 ## Statistics-reporting support for Matrix Synapse
 
 There's now a new `matrix_synapse_report_stats` playbook variable, which controls the `report_stats` configuration option for Matrix Synapse. It defaults to `false`, so no change is required to retain your privacy.
@@ -3795,7 +3819,6 @@ The playbook can now install and configure [matrix-synapse-rest-auth](https://gi
 
 Additional details are available in [Setting up the REST authentication password provider module](docs/configuring-playbook-rest-auth.md).
 
-
 ## Compression improvements
 
 Shifted Matrix Synapse compression from happening in the Matrix Synapse,
@@ -3804,7 +3827,6 @@ to happening in the nginx proxy that's in front of it.
 Additionally, `riot-web` also gets compressed now (in the nginx proxy),
 which drops the initial page load's size from 5.31MB to 1.86MB.
 
-
 ## Disabling some unnecessary Synapse services
 
 The following services are not necessary, so they have been disabled:
@@ -3835,7 +3857,6 @@ With this, Matrix Synapse is able to send email notifications for missed message
 
 # 2018-08-08
 
-
 ## (BC Break) Renaming playbook variables
 
 The following playbook variables were renamed:
@@ -3851,13 +3872,11 @@ The following playbook variables were renamed:
 
 If you're overriding any of them in your `vars.yml` file, you'd need to change to the new names.
 
-
 ## Renaming Ansible playbook tag
 
 The command for executing the whole playbook has changed.
 The `setup-main` tag got renamed to `setup-all`.
 
-
 ## Docker container linking
 
 Changed the way the Docker containers are linked together. The ones that need to communicate with others operate in a `matrix` network now and not in the default bridge network.

README.md

@@ -25,7 +25,12 @@ We have detailed documentation in the [docs/](./docs) directory - see the Table
 While the [list of supported services](#-supported-services) and documentation is very extensive, you don't need to read through everything. We recommend:
 
 - 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
+
+- Following our installation guide. There are two guides available for beginners and advanced users:
+
+    - ⚡ **[Quick start](./docs/quick-start.md) (for beginners)**: this is recommended for those who do not have an existing Matrix server and want to start quickly with "opinionated defaults".
+
+    - **Full installation guide (for advanced users)**: if you need to import an existing Matrix server's data into the new server or want to learn more while setting up the server, follow this guide by starting with the **[Prerequisites](./docs/prerequisites.md)** documentation page.
 
 ## ✔ Supported services
 
@@ -58,8 +63,6 @@ Web clients for Matrix that you can host on your own domains.
 | [Cinny](https://github.com/ajbura/cinny) |  ❌ | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
 | [SchildiChat Web](https://schildi.chat/) | ❌ | Based on Element Web, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat-web.md) |
 
-
-
 ### Server Components
 
 Services that run on the server to make the various parts of your installation work.
@@ -74,7 +77,6 @@ Services that run on the server to make the various parts of your installation w
 | [ma1sd](https://github.com/ma1uta/ma1sd) | ❌ | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
 | [ddclient](https://github.com/linuxserver/docker-ddclient) | ❌ | Dynamic DNS | [Link](docs/configuring-playbook-dynamic-dns.md) |
 
-
 ### Authentication
 
 Extend and modify how users are authenticated on your homeserver.
@@ -89,7 +91,6 @@ Extend and modify how users are authenticated on your homeserver.
 | [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (UVS) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
 | [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
 
-
 ### File Storage
 
 Use alternative file storage to the default `media_store` folder.
@@ -135,7 +136,6 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [Email2Matrix](https://github.com/devture/email2matrix) | ❌ | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
 | [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) |
 
-
 ### Bots
 
 Bots provide various additional functionality to your installation.
@@ -182,14 +182,12 @@ Various services that don't fit any other categories.
 | [Sygnal](https://github.com/matrix-org/sygnal) | ❌ | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
 | [ntfy](https://ntfy.sh) | ❌ | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
 
-
 ## 🆕 Changes
 
 This playbook evolves over time, sometimes with backward-incompatible changes.
 
 When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
 
-
 ## 🆘 Support
 
 - Matrix room: [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)
@@ -198,7 +196,6 @@ When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up w
 
 - GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
 
-
 ## 🤝 Related
 
 You may also be interested in [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) - another Ansible playbook for self-hosting non-Matrix services (see its [List of supported services](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md)).

docs/README.md

@@ -1,47 +1,86 @@
 # Table of Contents
 
-- [FAQ](faq.md) - lots of questions and answers. Jump to [Prerequisites](prerequisites.md) to avoid reading too much and to just start a guided installation.
+## ⬇️ Installaton guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->
 
-- [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook
+There are two installation guides available for beginners and advanced users.
 
-- [Configuring your DNS settings](configuring-dns.md)
+- ⚡ **[Quick start](quick-start.md) (for beginners)**: this is recommended for those who do not have an existing Matrix server and want to start quickly with "opinionated defaults".
 
-- [Getting this playbook's source code](getting-the-playbook.md)
+- **Full installation guide (for advanced users)**: if you need to import an existing Matrix server's data into the new server or want to learn more while setting up the server, follow this guide.
 
-- [Configuring the playbook](configuring-playbook.md)
+    - [Prerequisites](prerequisites.md)
 
-- [Installing](installing.md)
+    - [Configuring your DNS settings](configuring-dns.md)
 
-  - **Importing data from another server installation**
+    - [Getting the playbook](getting-the-playbook.md)
 
-    - [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)
+    - [Configuring the playbook](configuring-playbook.md)
 
-    - [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)
+    - [Installing](installing.md)
 
-    - [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
+## 🛠️ Configuration options
 
-  - [Server Delegation](howto-server-delegation.md)
+<!--
+NOTE:
+- Avoid putting the same anchor links as configuring-playbook.md lists under the "configuration options" section. Note that most of them are linked to "configure-playbook-*.md" and their titles start with "Setting up" (e.g. "Setting up Hydrogen").
+-->
 
-    - Server Delegation via a well-known file (recommended): [Installing well-known files on the base domain's server](configuring-well-known.md#installing-well-known-files-on-the-base-domain-s-server)
+You can check useful documentation for configuring components here: [Configuring the playbook](configuring-playbook.md)
 
-      - [Serving the base domain](configuring-playbook-base-domain-serving.md)
+- [Administration](configuring-playbook.md#administration) -  services that help you in administrating and monitoring your Matrix installation
 
-    - [Server Delegation via a DNS SRV record (advanced)](howto-srv-server-delegation.md)
+- [Authentication and user-related](configuring-playbook.md#authentication-and-user-related) - extend and modify how users are authenticated on your homeserver
+
+- [Bots](configuring-playbook.md#bots) - bots provide various additional functionality to your installation
+
+- [Bridges](configuring-playbook.md#bridging-other-networks) - bridges can be used to connect your Matrix installation with third-party communication networks
+
+- [Clients](configuring-playbook.md#clients) - web clients for Matrix that you can host on your own domains
+
+- [Core service adjustments](configuring-playbook.md#core-service-adjustments) - backbone of your Matrix system
+
+- [File Storage](configuring-playbook.md#file-storage) - use alternative file storage to the default `media_store` folder
+
+<!-- NOTE: sort list items above alphabetically -->
+
+- [Other specialized services](configuring-playbook.md#other-specialized-services) - various services that don't fit any other categories
+
+## 👨‍🔧 Maintenance
+
+If your server and services experience issues, feel free to come to [our support room](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) and ask for help.
+
+<!-- NOTE: sort list items alphabetically -->
+
+- [Checking if services work](maintenance-checking-services.md)
+
+- [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
+
+- [PostgreSQL maintenance](maintenance-postgres.md)
+
+- [Synapse maintenance](maintenance-synapse.md)
+
+- [Upgrading services](maintenance-upgrading-services.md)
+
+## Other documentation pages <!-- NOTE: this header's title and the section below need optimization -->
+
+- ℹ️ **[FAQ](faq.md)** - various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook
+
+<!-- NOTE: sort list items under faq.md alphabetically -->
+
+- [Alternative architectures](alternative-architectures.md)
+
+- [Container images used by the playbook](container-images.md)
+
+- [Obtaining an Access Token](obtaining-access-tokens.md)
 
 - [Playbook tags](playbook-tags.md)
 
 - [Registering users](registering-users.md)
 
-- [Updating users passwords](updating-users-passwords.md)
+- [Running `just` commands](just.md)
 
-- [Maintenance / checking if services work](maintenance-checking-services.md)
+- [Self-building](self-building.md)
-
-- [Maintenance / upgrading services](maintenance-upgrading-services.md)
-
-- [Maintenance / Synapse](maintenance-synapse.md)
-
-- [Maintenance / PostgreSQL](maintenance-postgres.md)
-
-- [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
 
 - [Uninstalling](uninstalling.md)
+
+- [Updating users passwords](updating-users-passwords.md)

docs/alternative-architectures.md

@@ -10,7 +10,6 @@ The playbook automatically determines the target server's architecture (the `mat
 
 Some tools and container images can be built on the host or other measures can be used to install on that architecture.
 
-
 ## Implementation details
 
 For `amd64`, prebuilt container images (see the [container images we use](container-images.md)) are used for all components (except [Hydrogen](configuring-playbook-client-hydrogen.md), which goes through self-building).

docs/ansible.md

@@ -5,7 +5,6 @@ This playbook is meant to be run using [Ansible](https://www.ansible.com/).
 
 Ansible typically runs on your local computer and carries out tasks on a remote server. If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
 
-
 ## Supported Ansible versions
 
 To manually check which version of Ansible you're on, run: `ansible --version`.
@@ -16,7 +15,6 @@ We're not sure what's the minimum version of Ansible that can run this playbook
 
 If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
 
-
 ## Upgrading Ansible
 
 Depending on your distribution, you may be able to upgrade Ansible in a few different ways:
@@ -27,10 +25,8 @@ Depending on your distribution, you may be able to upgrade Ansible in a few diff
 
 If using the `pip` method, do note that the `ansible-playbook` binary may not be on the `$PATH` (https://linuxconfig.org/linux-path-environment-variable), but in some more special location like `/usr/local/bin/ansible-playbook`. You may need to invoke it using the full path.
 
-
 **Note**: Both of the above methods are a bad way to run system software such as Ansible. If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
 
-
 ## Using Ansible via Docker
 
 Alternatively, you can run Ansible inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
@@ -39,7 +35,6 @@ This ensures that you're using a very recent Ansible version, which is less like
 
 You can either [run Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself) or [run Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server).
 
-
 ### Running Ansible in a container on the Matrix server itself
 
 To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation. Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
@@ -55,14 +50,14 @@ Alternatively, you can leave your `inventory/hosts` as is and specify the connec
 
 Run this from the playbook's directory:
 
-```bash
+```sh
 docker run -it --rm \
 --privileged \
 --pid=host \
 -w /work \
 -v `pwd`:/work \
 --entrypoint=/bin/sh \
-docker.io/devture/ansible:2.17.0-r0-1
+docker.io/devture/ansible:2.17.0-r0-2
 ```
 
 Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container. The `/work` directory contains the playbook's code.
@@ -71,18 +66,17 @@ First, consider running `git config --global --add safe.directory /work` to [res
 
 Finally, you can execute `ansible-playbook ...` (or `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
 
-
 ### Running Ansible in a container on another computer (not the Matrix server)
 
 Run this from the playbook's directory:
 
-```bash
+```sh
 docker run -it --rm \
 -w /work \
 -v `pwd`:/work \
 -v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
 --entrypoint=/bin/sh \
-docker.io/devture/ansible:2.17.0-r0-1
+docker.io/devture/ansible:2.17.0-r0-2
 ```
 
 The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`). If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part.
@@ -93,17 +87,17 @@ First, consider running `git config --global --add safe.directory /work` to [res
 
 Finally, you execute `ansible-playbook ...` commands as per normal now.
 
-
 #### If you don't use SSH keys for authentication
 
 If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
 
 To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it ...` command), run:
-```bash
+
+```sh
 apk add sshpass
 ```
-Then, to be asked for the password whenever running an  `ansible-playbook` command add `--ask-pass` to the arguments of the command.
 
+Then, to be asked for the password whenever running an  `ansible-playbook` command add `--ask-pass` to the arguments of the command.
 
 #### Resolve directory ownership issues
 

docs/configuring-captcha.md

@@ -1,6 +1,7 @@
 (Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
 
 # Overview
+
 Captcha can be enabled for this home server. This file explains how to do that.
 
 The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.

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

docs/configuring-playbook-alertmanager-receiver.md

@@ -12,7 +12,7 @@ This service is meant to be used with an external [Alertmanager](https://prometh
 
 To enable matrix-alertmanager-receiver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-```yml
+```yaml
 matrix_alertmanager_receiver_enabled: true
 
 # If you'd like to change the username for this bot, uncomment and adjust. Otherwise, remove.
@@ -73,19 +73,28 @@ Steps 1 and 2 above only need to be done once, while preparing your [configurati
 
 Steps 3 and 4 need to be done for each new room you'd like the bot to deliver alerts to. Step 5 is optional and provides cleaner `/alert/` URLs.
 
-
 ## Installing
 
-Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the [installation](installing.md) command: `just install-all`
+Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
 
-Then, you can proceed to [Usage](#usage).
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
 Configure your Prometheus Alertmanager with configuration like this:
 
-```yml
+```yaml
 receivers:
   - name: matrix
     webhook_configs:

docs/configuring-playbook-appservice-double-puppet.md

@@ -10,13 +10,26 @@ Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/
 
 To enable the Appservice Double Puppet service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-```yml
+```yaml
 matrix_appservice_double_puppet_enabled: true
 ```
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -4,7 +4,6 @@ The playbook can install and configure the [Draupnir](https://github.com/the-dra
 
 Appservice mode can be used together with the regular [Draupnir bot](configuring-playbook-bot-draupnir.md) or independently. Details about the differences between the 2 modes are described below.
 
-
 ## Draupnir Appservice mode compared to Draupnir bot mode
 
 The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
@@ -17,7 +16,6 @@ Normal Draupnir does come with the benefit of access to Synapse Admin features.
 
 Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
 
-
 ## Installation
 
 ### 1. Create a main management room.
@@ -49,12 +47,20 @@ matrix_appservice_draupnir_for_all_master_control_room_alias: "ALIAS_FROM_STEP_2
 
 ### 4. Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-backup-borg.md

@@ -18,7 +18,7 @@ By default, if you're using the integrated Postgres database server (as opposed
 
 2. Create a new SSH key:
 
-    ```bash
+    ```sh
     ssh-keygen -t ed25519 -N '' -f matrix-borg-backup -C matrix
     ```
 
@@ -28,7 +28,7 @@ By default, if you're using the integrated Postgres database server (as opposed
 
     If you plan to use a hosted solution, follow their instructions. If you have your own server, copy the key over:
 
-    ```bash
+    ```sh
     # example to append the new PUBKEY contents, where:
     # PUBKEY is path to the public key,
     # USER is a ssh user on a provider / server
@@ -71,12 +71,17 @@ Check the [backup_borg role](https://github.com/mother-of-all-self-hosting/ansib
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
 ## Manually start a backup
 
 For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly a long time. Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

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

@@ -33,7 +33,6 @@ Doing this, the playbook will:
 
 - serve a simple homepage at `https://example.com` with content `Hello from example.com` (configurable via the `matrix_static_files_file_index_html_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain).
 
-
 ## Serving a static website at the base domain
 
 By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage at `/matrix/static-files/public/index.html`. The content of this page is taken from the `matrix_static_files_file_index_html_template` variable.
@@ -56,7 +55,6 @@ With this configuration, Ansible will no longer mess around with the `/matrix/st
 
 You are then free to upload any static website files to `/matrix/static-files/public` and they will get served at the base domain. You can do so manually or by using the [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role, which is part of this playbook already.
 
-
 ## Serving a more complicated website at the base domain
 
 If you'd like to serve an even more complicated (dynamic) website from the Matrix server, relying on the playbook to serve the base domain is not the best choice.

docs/configuring-playbook-bot-baibot.md

@@ -11,12 +11,10 @@ It supports [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/ch
 
 It's designed as a more private and [✨ featureful](https://github.com/etkecc/baibot/?tab=readme-ov-file#-features) alternative to [matrix-chatgpt-bot](./configuring-playbook-bot-chatgpt.md). See the [baibot](https://github.com/etkecc/baibot) project and its documentation for more information.
 
-
 ## Prerequisites
 
 API access to one or more LLM [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
 
-
 ## Adjusting the playbook configuration
 
 There are **a lot of configuration options** (some required, some possibly required, some optional), so they're **split into multiple sections below**:
@@ -30,7 +28,6 @@ There are **a lot of configuration options** (some required, some possibly requi
 
 Depending on your current `vars.yml` file and desired configuration, **you may require more than just the [base configuration](#base-configuration)**.
 
-
 ### Base configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -73,7 +70,6 @@ matrix_bot_baibot_config_persistence_config_encryption_key: 'A_HEX_STRING_OF_64_
 
 As mentioned above, **this may not be enough**. Continue with the configuration sections below.
 
-
 ### 👮‍♂️ Administrator configuration
 
 This is an addition to the [base configuration](#base-configuration).
@@ -84,7 +80,7 @@ If `matrix_admin` is already configured in your `vars.yml` configuration, you ca
 
 **If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-```yml
+```yaml
 # Uncomment to add one or more admins to this bridge:
 #
 # matrix_bot_baibot_config_access_admin_patterns:
@@ -113,7 +109,7 @@ Configuring `matrix_bot_baibot_config_initial_global_config_user_patterns` is op
 
 **If necessary**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-```yml
+```yaml
 # Uncomment and adjust the bot users if necessary:
 #
 # Subsequent changes to `matrix_bot_baibot_config_initial_global_config_user_patterns` do not affect the bot's behavior.
@@ -139,14 +135,13 @@ Depending on your propensity for [GitOps](https://en.wikipedia.org/wiki/DevOps#G
 
 Before proceeding, we recommend reading the upstream documentation on [How to choose a provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#how-to-choose-a-provider). In short, it's probably best to go with [OpenAI](#openai).
 
-
 #### Anthropic
 
 You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Anthropic provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#anthropic) with the help of the playbook's preset variables.
 
 Here's an example **addition** to your `vars.yml` file:
 
-```yml
+```yaml
 matrix_bot_baibot_config_agents_static_definitions_anthropic_enabled: true
 
 matrix_bot_baibot_config_agents_static_definitions_anthropic_config_api_key: "YOUR_API_KEY_HERE"
@@ -166,14 +161,13 @@ If you'd like to use more than one model, take a look at the [Configuring additi
 
 💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
 
-
 #### Groq
 
 You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Groq provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#groq) with the help of the playbook's preset variables.
 
 Here's an example **addition** to your `vars.yml` file:
 
-```yml
+```yaml
 matrix_bot_baibot_config_agents_static_definitions_groq_enabled: true
 
 matrix_bot_baibot_config_agents_static_definitions_groq_config_api_key: "YOUR_API_KEY_HERE"
@@ -200,14 +194,13 @@ If you'd like to use more than one model, take a look at the [Configuring additi
 
 💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
 
-
 #### Mistral
 
 You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [🇫🇷 Mistral provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#mistral) with the help of the playbook's preset variables.
 
 Here's an example **addition** to your `vars.yml` file:
 
-```yml
+```yaml
 matrix_bot_baibot_config_agents_static_definitions_mistral_enabled: true
 
 matrix_bot_baibot_config_agents_static_definitions_mistral_config_api_key: "YOUR_API_KEY_HERE"
@@ -229,7 +222,6 @@ If you'd like to use more than one model, take a look at the [Configuring additi
 
 💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
 
-
 #### OpenAI
 
 You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai) with the help of the playbook's preset variables.
@@ -238,7 +230,7 @@ The OpenAI provider is **only meant to be used with OpenAI's official API** and
 
 Here's an example **addition** to your `vars.yml` file:
 
-```yml
+```yaml
 matrix_bot_baibot_config_agents_static_definitions_openai_enabled: true
 
 matrix_bot_baibot_config_agents_static_definitions_openai_config_api_key: "YOUR_API_KEY_HERE"
@@ -260,7 +252,6 @@ If you'd like to use more than one model, take a look at the [Configuring additi
 
 💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
 
-
 #### OpenAI Compatible
 
 You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI Compatible provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai-compatible) with the help of the playbook's preset variables.
@@ -271,7 +262,6 @@ Some of these popular services already have **shortcut** providers (see [support
 
 As of this moment, the playbook does not include presets for any of these services, so you'll need to [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset).
 
-
 #### Configuring additional agents (without a preset)
 
 The Ansible role may be lacking preset variables for some [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md), or you may wish to statically-define an agent on the same provider twice (or more) with different configuration.
@@ -282,7 +272,7 @@ You can also define providers at runtime, by chatting with the bot, so using Ans
 
 Below is an an **example** demonstrating **statically-defining agents via Ansible without using presets**:
 
-```yml
+```yaml
 matrix_bot_baibot_config_agents_static_definitions_custom:
   # This agent will use the GPT 3.5 model and will only support text-generation,
   # even though the `openai` provider could support other features (e.g. image-generation).
@@ -327,7 +317,6 @@ As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.
 
 💡 You may also wish to use these new agents for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
 
-
 ### 🤝 Configuring initial default handlers
 
 This section is only useful if you're [🤖 Configuring agents via Ansible](#-configuring-agents-via-ansible), as it lets you put these agents to use as soon as the bot starts (by adjusting the bot's **initial global configuration**).
@@ -356,7 +345,7 @@ You can configure the **initial values** for these via Ansible, via the `matrix_
 
 Example **additional** `vars.yml` configuration:
 
-```yml
+```yaml
 # Note: these are initial defaults for the bot's global configuration.
 # As such, changing any of these values subsequently has no effect on the bot's behavior.
 # Once initially configured, the global configuration is managed via bot commands, not via Ansible.
@@ -373,21 +362,24 @@ matrix_bot_baibot_config_initial_global_config_handler_image_generation: null
 
 **Note**: these are initial defaults for the bot's global configuration. As such, changing any of these values subsequently has no effect on the bot's behavior. **Once initially configured the global configuration cannot be managed Ansible**, but only via bot commands.
 
-
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
 ```sh
-just run-tags install-all,ensure-matrix-users-created,start
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
 **Notes**:
 
-- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-- if you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password.
 
 ## Usage
 
@@ -403,7 +395,6 @@ Send `!bai help` to the room at any time to see the bot's help menu for addition
 
 You can also refer to the upstream [baibot](https://github.com/etkecc/baibot) project's documentation.
 
-
 ## Debugging
 
 As with all other services, you can find service logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-bot-baibot`

docs/configuring-playbook-bot-buscarron.md

@@ -56,18 +56,22 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
 **Notes**:
 
-- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-- if you change the bot password (`matrix_bot_buscarron_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_buscarron_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-chatgpt.md

@@ -16,18 +16,16 @@ Choose a strong password for the bot. You can generate a good password with a co
 
 You can use the playbook to [register a new user](registering-users.md):
 
-```
+```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-
 ## 2. Get an access token and create encryption keys
 
 Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
 To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [Element documentation](https://element.io/help#encryption6).
 
-
 ## 3. Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
@@ -53,15 +51,22 @@ matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a
 
 You will need to get tokens for ChatGPT.
 
-
 ## 4. Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
 ```sh
-ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-bot-draupnir.md

@@ -6,7 +6,6 @@ See the project's [documentation](https://github.com/the-draupnir-project/Draupn
 
 This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead.
 
-
 If your migrating from Mjolnir skip to step 5b.
 
 ## 1. Register the bot account
@@ -19,18 +18,16 @@ Choose a strong password for the bot. You can generate a good password with a co
 
 You can use the playbook to [register a new user](registering-users.md):
 
-```
+```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
 If you would like Draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports ([see below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
 
-
 ## 2. Get an access token
 
 Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
-
 ## 3. Make sure the account is free from rate limiting
 
 You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Draupnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
@@ -39,8 +36,6 @@ If your Synapse Admin API is exposed to the internet for some reason like runnin
 
 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.
 
-
-
 ## 4. Create a management room
 
 Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
@@ -51,7 +46,6 @@ Once you have created the room you need to copy the room ID so you can tell the
 
 Finally invite the `@bot.draupnir:example.com` account you created earlier into the room.
 
-
 ## 5. Adjusting the playbook configuration
 
 Decide whether you want Draupnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Draupnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
@@ -115,12 +109,22 @@ That is all you need to do due to that Draupnir can complete migration on its ow
 
 ## 6. Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the Pantalaimon's password (`matrix_bot_draupnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_draupnir_pantalaimon_password` to let Pantalaimon know its new password.
 
 ## Usage
 
@@ -190,7 +194,6 @@ To **enable a given protection**, send a command like this: `!draupnir enable PR
 
 To **disable a given protection**, send a command like this: `!draupnir disable PROTECTION_NAME` (e.g. `!draupnir disable JoinWaveShortCircuit`).
 
-
 ## Extending the configuration
 
 You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.

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

@@ -8,7 +8,6 @@ Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the ori
 
 See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
 
-
 ## Registering the bot user
 
 The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
@@ -19,13 +18,12 @@ Choose a strong password for the bot. You can generate a good password with a co
 
 You can use the playbook to [register a new user](registering-users.md):
 
-```
+```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
 Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
 
-
 ## Adjusting the playbook configuration
 
 To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -219,12 +217,20 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-bot-honoroit.md

@@ -6,7 +6,6 @@ It's a bot you can use to setup **your own helpdesk on matrix**
 
 See the project's [documentation](https://github.com/etkecc/honoroit#how-it-looks-like) to learn what it does with screenshots and why it might be useful to you.
 
-
 ## Adjusting the playbook configuration
 
 To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -48,18 +47,22 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
 **Notes**:
 
-- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-- if you change the bot password (`matrix_bot_honoroit_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_honoroit_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password.
 
 ## Usage
 

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

@@ -6,7 +6,6 @@ The bot allows you to easily **create and manage registration tokens** aka. invi
 
 See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it does and why it might be useful to you.
 
-
 ## Configuration
 
 To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -32,7 +31,22 @@ The bot account will be created automatically.
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_matrix_registration_bot_bot_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_registration_bot_bot_password` to let the bot know its new password.
 
 ## Usage
 
@@ -46,6 +60,6 @@ If you have any questions, or if you need help setting it up, read the [troublsh
 
 To clean the cache (session & encryption data) after you changed the bot's username, changed the login method from access_token to password etc... you can use:
 
-```bash
+```sh
 just run-tags bot-matrix-registration-bot-clean-cache
 ```

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

@@ -6,7 +6,6 @@ It's a bot you can use to **schedule one-off & recurring reminders and alarms**.
 
 See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you.
 
-
 ## Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -24,21 +23,24 @@ matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
 matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
 ```
 
-
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
 **Notes**:
 
-- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-- if you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-maubot.md

@@ -49,11 +49,22 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
 **Notes**:
 
-- if you change the bot password (`matrix_bot_maubot_initial_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bot password (`matrix_bot_maubot_initial_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bot-mjolnir.md

@@ -4,7 +4,6 @@ The playbook can install and configure the [Mjolnir](https://github.com/matrix-o
 
 See the project's [documentation](https://github.com/matrix-org/mjolnir) to learn what it does and why it might be useful to you.
 
-
 ## 1. Register the bot account
 
 The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
@@ -15,18 +14,16 @@ Choose a strong password for the bot. You can generate a good password with a co
 
 You can use the playbook to [register a new user](registering-users.md):
 
-```
+```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
 If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
 
-
 ## 2. Get an access token
 
 Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
-
 ## 3. Make sure the account is free from rate limiting
 
 You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
@@ -45,7 +42,6 @@ Once you have created the room you need to copy the room ID so you can tell the
 
 Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room.
 
-
 ## 5. Adjusting the playbook configuration
 
 Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
@@ -105,7 +101,6 @@ matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
-
 ```yaml
 matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_invites: true
@@ -114,15 +109,24 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
 ```
 
-
 ## 7. Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the Pantalaimon's password (`matrix_bot_mjolnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_mjolnir_pantalaimon_password` to let Pantalaimon know its new password.
 
 ## Usage
 

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

@@ -8,38 +8,46 @@ The playbook can install and configure [matrix-appservice-discord](https://githu
 
 See the project's [documentation](https://github.com/matrix-org/matrix-appservice-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+## Prerequisites
 
-## Setup Instructions
+Create a Discord Application [here](https://discordapp.com/developers/applications). Then retrieve Client ID, and create a bot from the Bot tab and retrieve the Bot token.
 
-Instructions loosely based on [this](https://github.com/matrix-org/matrix-appservice-discord#setting-up).
+## Adjusting the playbook configuration
 
-1. Create a Discord Application [here](https://discordapp.com/developers/applications).
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-2. Retrieve Client ID.
-3. Create a bot from the Bot tab and retrieve the Bot token.
-4. Enable the bridge with the following configuration in your `vars.yml` file:
 
-    ```yaml
+```yaml
-    matrix_appservice_discord_enabled: true
+matrix_appservice_discord_enabled: true
-    matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
+matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
-    matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
+matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
-    ```
 
-5. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
+# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
+# Note: This deprecated method is considered insecure.
+#
+# matrix_synapse_configuration_extension_yaml: |
+#   use_appservice_legacy_authorization: true
+```
 
-    ```yaml
+## Installing
-    matrix_synapse_configuration_extension_yaml: |
-      use_appservice_legacy_authorization: true
-    ```
 
-    **Note**: This deprecated method is considered insecure.
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-6. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Self-Service Bridging (Manual)
 
-Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. This is disabled by default, so it must be enabled by adding this to your `vars.yml`:
+Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_appservice_discord_bridge_enableSelfServiceBridging: true
@@ -47,27 +55,32 @@ matrix_appservice_discord_bridge_enableSelfServiceBridging: true
 
 **Note**: If self-service bridging is not enabled, `!discord help` commands will return no results.
 
-Once self-service is enabled:
+### Usage
 
-1. Start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
+Once self-service is enabled, start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
-2. Follow the instructions in the help output message. If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
 
-**Note**: Encrypted Matrix rooms are not supported as of writing.
+Then, follow the instructions in the help output message.
+
+If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
 
 On the Discord side, you can say `!matrix help` to get a list of available commands to manage the bridge and Matrix users.
 
+**Note**: Encrypted Matrix rooms are not supported as of writing.
+
 ## Portal Bridging (Automatic)
 
 Through portal bridging, Matrix rooms will automatically be created by the bot and bridged to the relevant Discord room. This is done by simply joining a room with a specific name pattern (`#_discord_<guildID>_<channelID>`).
 
 All Matrix rooms created this way are **listed publicly** by default, and you will not have admin permissions to change this. To get more control, [make yourself a room Administrator](#getting-administrator-access-in-a-portal-bridged-room). You can then unlist the room from the directory and change the join rules.
 
-If you want to disable portal bridging, set the following in `vars.yml`:
+To disable portal bridging, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_appservice_discord_bridge_disablePortalBridging: true
 ```
 
+### Usage
+
 To get started with Portal Bridging:
 
 1. To invite the bot to Discord, retrieve the invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).

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

@@ -62,7 +62,20 @@ matrix_appservice_irc_ircService_servers:
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -2,12 +2,17 @@
 
 The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you. `matrix-appservice-kakaotalk` is a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
 
-**Note**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
+⚠️ **Warning**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
 
 See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
 
-## Installing
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
+## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
@@ -17,17 +22,6 @@ matrix_appservice_kakaotalk_enabled: true
 
 You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
 
-## Installing
-
-After configuring the playbook, run the [installation](installing.md) command:
-
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
-```
-
-To make use of the Kakaotalk bridge, see [Usage](#usage) below.
-
-
 ### Additional configuration
 
 There are some additional things you may wish to configure about the bridge.
@@ -37,21 +31,43 @@ Take a look at:
 - `roles/custom/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 - `roles/custom/matrix-bridge-appservice-kakaotalk/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_kakaotalk_configuration_extension_yaml` variable
 
+## Installing
 
-### Set up Double Puppeting
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+Start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
 
 #### Method 1: automatically, by enabling Shared Secret Auth
 
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
 
 This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
 
 #### Method 2: manually, by asking each user to provide a working access token
 
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
 - retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
@@ -59,12 +75,3 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 
 - make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature
-
-
-## Usage
-
-Start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-
-Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
-
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.

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

@@ -2,135 +2,135 @@
 
 **Notes**:
 - Bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook.
-- Currently (as of November, 2024) this component is not available for new installation unless you have already created a classic Slack application (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
+- Currently (as of November, 2024) **this component is not available for new installation unless you have already created a classic Slack application** (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
 
 The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
 
 See the project's [documentation](https://github.com/matrix-org/matrix-appservice-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-## Setup Instructions:
+## Prerequisites
 
-loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)
+### Create a Classic Slack App
 
-1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
+First, you need to create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
 
-2. Enable the bridge by adding the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+Name the app "matrixbot" (or anything else you'll remember). Select the team/workspace this app will belong to. Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
 
-    ```yaml
+Then, click on Event Subscriptions and enable them and use the request url: `https://matrix.example.com/appservice-slack`.
-    matrix_appservice_slack_enabled: true
-    matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
-    ```
 
-3. Enable puppeting (optional, but recommended)
+Add the following events as `Bot User Events` and save:
 
-    ```yaml
+- team_domain_change
-    matrix_appservice_slack_puppeting_enabled: true
+- message.channels
-    matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
+- message.groups (if you want to bridge private channels)
-    matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
+- reaction_added
-    ```
+- reaction_removed
 
-4. Enable Team Sync (optional)
+Next, click on "OAuth & Permissions" and add the following scopes:
 
-    ```yaml
+- chat:write:bot
-    matrix_appservice_slack_team_sync_enabled: true
+- users:read
-    ```
+- reactions:write
+- files:write:user (if you want to bridge files)
 
-    See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
+**Note**: In order to make Slack files visible to Matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
 
-5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
+Click on "Install App" and "Install App to Workspace". Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
 
-6. Invite the bridge bot user into the admin room:
+### Create an administration control room on Matrix
+
+Create a new Matrix room to act as the administration control room.
+
+Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
+
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_appservice_slack_enabled: true
+matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
+
+# Uncomment to enable puppeting (optional, but recommended)
+# matrix_appservice_slack_puppeting_enabled: true
+# matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
+# matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
+
+# Uncomment to enable Team Sync (optional)
+# See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
+# matrix_appservice_slack_team_sync_enabled: true
+```
+
+Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+Send `/invite @slackbot:example.com` to invite the bridge bot user into the admin room.
+
+If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
+
+- Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like `!qporfwt:example.com`.
+- Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
+- Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
+- Issue a link command in the administration control room with these collected values as arguments:
+
+    with file bridging:
 
     ```
-    /invite @slackbot:example.com
+    link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
     ```
 
-    Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
+    without file bridging:
-
-7. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
-
-    Name the app "matrixbot" (or anything else you'll remember).
-
-    Select the team/workspace this app will belong to.
-
-    Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
-
-8. Click on Event Subscriptions and enable them and use the request url `https://matrix.example.com/appservice-slack`. Then add the following events and save:
-
-     Bot User Events:
-
-    - team_domain_change
-    - message.channels
-    - message.groups (if you want to bridge private channels)
-    - reaction_added
-    - reaction_removed
-
-9. Click on OAuth & Permissions and add the following scopes:
-
-    - chat:write:bot
-    - users:read
-    - reactions:write
-
-    If you want to bridge files, also add the following:
-
-    - files:write:user
-
-    **Note**: In order to make Slack files visible to Matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
-
-10. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
-
-11. If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
-
-    * Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !qporfwt:example.com.
-
-    * Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
-
-    * Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
-
-    * Issue a link command in the administration control room with these collected values as arguments:
-
-        with file bridging:
-
-        ```
-        link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
-        ```
-
-        without file bridging:
-
-        ```
-        link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
-        ```
-
-        These arguments can be shortened to single-letter forms:
-
-        ```
-        link -I CHANNELID -R !qporfwt:example.com -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
-        ```
-
-        Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
-
-12. Unlinking
-
-    Channels can be unlinked again like this:
 
     ```
-    unlink --room !qporfwt:example.com
+    link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
     ```
 
-    Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
+    These arguments can be shortened to single-letter forms:
+
+    ```
+    link -I CHANNELID -R !qporfwt:example.com -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
+    ```
+
+### Unlinking
+
+Channels can be unlinked again by sending this:
+
+```
+unlink --room !qporfwt:example.com
+```
+
+Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
 
 ## Troubleshooting
 
-* As always, check the logs: `journalctl -fu matrix-appservice-slack`
+As always, check the logs: `journalctl -fu matrix-appservice-slack`
 
-* Linking: "Room is now pending-name"
+### Linking: "Room is now pending-name"
 
-  This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
+This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
 
-* Messages work from M to S, but not the other way around
+### Messages work from Matrix to Slack, but not the other way around
 
-  Check you logs, if they say something like
+Check you logs, if they say something like
 
-  `WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
+`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
 
-  then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.
+then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.

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

@@ -4,70 +4,84 @@
 
 The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you. This bridge provides support for Slack-compatible webhooks.
 
-Setup Instructions:
+See the project's [documentation](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-loosely based on [this](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md)
+## Adjusting the playbook configuration
 
-1. Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-    ```yaml
+```yaml
-    matrix_appservice_webhooks_enabled: true
+matrix_appservice_webhooks_enabled: true
-    matrix_appservice_webhooks_api_secret: '<your_secret>'
+matrix_appservice_webhooks_api_secret: '<your_secret>'
-    ```
 
-2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service` you can adjust this in `inventory/host_vars/matrix.example.com/vars.yml` as well.
+# Uncomment to increase the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
+# matrix_appservice_webhooks_log_level: 'verbose'
 
-    **Note**: default value is: `info` and availabe log levels are : `info`, `verbose`
+# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
+# Note: This deprecated method is considered insecure.
+#
+# matrix_synapse_configuration_extension_yaml: |
+#   use_appservice_legacy_authorization: true
+```
 
-    ```yaml
+## Installing
-    matrix_appservice_webhooks_log_level: '<log_level>'
-    ```
 
-3. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-    ```yaml
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
-    matrix_synapse_configuration_extension_yaml: |
+```sh
-      use_appservice_legacy_authorization: true
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
-    ```
+```
 
-    **Note**: This deprecated method is considered insecure.
+**Notes**:
 
-4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-5. If you're using the [Dimension integration manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL"  & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-6. Invite the bridge bot user to your room:
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
-    - either with `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
+## Usage
 
-    - or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
+Invite the bridge bot user to your room in either way.
 
-7. Send a message to the bridge bot in order to receive a private message including the webhook link.
+- Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
+- Add the bridge bot to a private channel (personal channels imply you being an administrator)
 
-    ```
+You then need to send a message to the bridge bot in order to receive a private message including the webhook link:
-    !webhook
-    ```
 
-8. The JSON body for posting messages will have to look like this:
+```
+!webhook
+```
 
-    ```json
+The JSON body for posting messages will have to look like this:
-    {
-        "text": "Hello world!",
-        "format": "plain",
-        "displayName": "My Cool Webhook",
-        "avatar_url": "http://i.imgur.com/IDOBtEJ.png"
-    }
-    ```
 
-    You can test this via curl like so:
+```json
-
+{
-    ```sh
-    curl --header "Content-Type: application/json" \
-    --data '{
     "text": "Hello world!",
     "format": "plain",
     "displayName": "My Cool Webhook",
     "avatar_url": "http://i.imgur.com/IDOBtEJ.png"
-    }' \
+}
-    <the link you've gotten in 5.>
+```
-    ```
+
+You can test this via curl like so:
+
+```sh
+curl --header "Content-Type: application/json" \
+--data '{
+"text": "Hello world!",
+"format": "plain",
+"displayName": "My Cool Webhook",
+"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
+}' \
+<the webhook link you've gotten from the bridge bot>
+```
+
+### Setting Webhooks with Dimension integration manager
+
+If you're using the [Dimension integration manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge with it.
+
+To configure it, open the Dimension integration manager, and go to "Settings" and "Bridges", then select edit action for "Webhook Bridge".
+
+On the UI, press "Add self-hosted Bridge" button and populate "Provisioning URL"  and "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.

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

@@ -15,15 +15,14 @@ matrix_beeper_linkedin_enabled: true
 There are some additional things you may wish to configure about the bridge before you continue.
 
 Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+
 ```yaml
-matrix_beeper_linkedin_configuration_extension_yaml: |
+matrix_beeper_linkedin_bridge_encryption_allow: true
-  bridge:
+matrix_beeper_linkedin_bridge_encryption_default: true
-    encryption:
-      allow: true
-      default: true
 ```
 
 If you would like to be able to administrate the bridge from your account it can be configured like this:
+
 ```yaml
 matrix_beeper_linkedin_configuration_extension_yaml: |
   bridge:
@@ -35,17 +34,29 @@ You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/co
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Set up Double Puppeting by enabling Appservice Double Puppet or Shared Secret Auth
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
 
 Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
 
 Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
 
-
 ## Usage
 
 You then need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
@@ -56,7 +67,6 @@ If you run into trouble, check the [Troubleshooting](#troubleshooting) section b
 
 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
 
 ### Bridge asking for 2FA even if you don't have 2FA enabled

docs/configuring-playbook-bridge-go-skype-bridge.md

@@ -14,7 +14,20 @@ matrix_go_skype_bridge_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-bridge-heisenbridge.md

@@ -49,7 +49,20 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-bridge-hookshot.md

@@ -8,7 +8,6 @@ See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/l
 
 **Note**: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however was deprecated by its author.
 
-
 ## Setup Instructions
 
 Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
@@ -25,9 +24,9 @@ Finally, run the playbook (see [installing](installing.md)).
 
 ### End-to-bridge encryption
 
-You can enable [experimental encryption](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) for Hookshot by adding `matrix_hookshot_experimental_encryption_enabled: true` to your configuration (`vars.yml`) and [executing the playbook](installing.md) again.
+You can enable [encryption](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) for Hookshot by adding `matrix_hookshot_encryption_enabled: true` to your configuration (`vars.yml`) and [executing the playbook](installing.md) again.
 
-Should the crypto store be corrupted, you can reset it by executing this Ansible playbook with the tag `reset-hookshot-encryption` added, for example `ansible-playbook -i inventory/hosts setup.yml -K --tags=reset-hookshot-encryption`.
+Should the crypto store be corrupted, you can reset it by executing this Ansible playbook with the tag `reset-hookshot-encryption` added, for example `ansible-playbook -i inventory/hosts setup.yml --tags=reset-hookshot-encryption`.
 
 ## Usage
 
@@ -41,7 +40,6 @@ Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot
 
 **Important**: Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](#urls-for-bridges-setup) below.
 
-
 ## More setup documentation
 
 ### URLs for bridges setup
@@ -72,6 +70,7 @@ The GitHub bridge requires you to install a private key file. This can be done i
 - use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
 
 To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration:
+
 ```yaml
 aux_file_definitions:
   - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
@@ -80,6 +79,7 @@ aux_file_definitions:
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
 ```
+
 For more information, see the documentation in the [default configuration of the aux role](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml).
 
 ### Provisioning API

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

@@ -33,7 +33,20 @@ matrix_sms_bridge_provider_android_truststore_password: 123
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -8,13 +8,18 @@ The playbook can install and configure [mautrix-discord](https://github.com/maut
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/discord/index.html) to learn what it does and why it might be useful to you.
 
-
 ## Prerequisites
 
 There are 2 ways to login to discord using this bridge, either by [scanning a QR code](#method-1-login-using-qr-code-recommended) using the Discord mobile app **or** by using a [Discord token](#method-2-login-using-discord-token-not-recommended).
 
 If this is a dealbreaker for you, consider using one of the other Discord bridges supported by the playbook: [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) or [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md). These come with their own complexity and limitations, however, so we recommend that you proceed with this one if possible.
 
+### Enable Appservice Double Puppet or Shared Secret Auth (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -25,17 +30,6 @@ matrix_mautrix_discord_enabled: true
 
 You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
 
-## Installing
-
-After configuring the playbook, run the [installation](installing.md) command:
-
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
-```
-
-To make use of the bridge, see [Usage](#usage) below.
-
-
 ### Additional configuration
 
 There are some additional things you may wish to configure about the bridge.
@@ -45,31 +39,22 @@ Take a look at:
 - `roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 - `roles/custom/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable
 
+## Installing
 
-### Set up Double Puppeting
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+**Notes**:
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
-#### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
@@ -97,3 +82,27 @@ To acquire the token, open Discord in a private browser window. Then open the de
     - send `guilds status` to see the list of guilds
     - for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire`
 8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function.
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+
+Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature

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

@@ -6,6 +6,12 @@ The playbook can install and configure [mautrix-facebook](https://github.com/mau
 
 See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -17,6 +23,7 @@ matrix_mautrix_facebook_enabled: true
 There are some additional things you may wish to configure about the bridge before you continue.
 
 Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+
 ```yaml
 matrix_mautrix_facebook_configuration_extension_yaml: |
   bridge:
@@ -26,6 +33,7 @@ matrix_mautrix_facebook_configuration_extension_yaml: |
 ```
 
 If you would like to be able to administrate the bridge from your account it can be configured like this:
+
 ```yaml
 matrix_mautrix_facebook_configuration_extension_yaml: |
   bridge:
@@ -49,30 +57,20 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/c
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Shared Secret Auth
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
-
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
@@ -82,8 +80,27 @@ Send `login YOUR_FACEBOOK_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.
+### 💡 Set up Double Puppeting
 
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Shared Secret Auth
+
+The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature
 
 ## Troubleshooting
 
@@ -97,7 +114,7 @@ The easiest way to do this may be to use [sshuttle](https://sshuttle.readthedocs
 
 Example command for proxying your traffic through the Matrix server:
 
-```
+```sh
 sshuttle -r root@matrix.example.com:22 0/0
 ```
 

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

@@ -4,6 +4,12 @@ The playbook can install and configure [mautrix-gmessages](https://github.com/ma
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/index.html) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -14,21 +20,38 @@ matrix_mautrix_gmessages_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
-### Method 2: manually, by asking each user to provide a working access token
+## Usage
 
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
+You then need to start a chat with `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
@@ -37,8 +60,3 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 
 - make sure you don't log out the `Mautrix-gmessages` device some time in the future, as that would break the Double Puppeting feature
-
-
-## Usage
-
-You then need to start a chat with `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

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

@@ -4,6 +4,12 @@ The playbook can install and configure [mautrix-googlechat](https://github.com/m
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/googlechat/index.html) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the [Google Chat](https://chat.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -14,33 +20,20 @@ matrix_mautrix_googlechat_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
-
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
-
-### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
@@ -54,4 +47,26 @@ Once logged in, recent chats should show up as new conversations automatically.
 
 You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
 
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+
+Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature

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

@@ -6,6 +6,12 @@ The playbook can install and configure [mautrix-hangouts](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/hangouts/index.html) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the [Google Hangouts](https://hangouts.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -16,31 +22,20 @@ matrix_mautrix_hangouts_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Shared Secret Auth
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
-
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-
-### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
@@ -54,4 +49,24 @@ Once logged in, recent chats should show up as new conversations automatically.
 
 You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/hangouts/authentication.html).
 
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Shared Secret Auth
+
+The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature

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

@@ -17,6 +17,7 @@ matrix_mautrix_instagram_enabled: true
 There are some additional things you may wish to configure about the bridge before you continue.
 
 Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+
 ```yaml
 matrix_mautrix_instagram_configuration_extension_yaml: |
   bridge:
@@ -26,6 +27,7 @@ matrix_mautrix_instagram_configuration_extension_yaml: |
 ```
 
 If you would like to be able to administrate the bridge from your account it can be configured like this:
+
 ```yaml
 # The easy way. The specified Matrix user ID will be made an admin of all bridges
 matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
@@ -42,7 +44,20 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -6,8 +6,9 @@ Since this bridge component can bridge to both [Messenger](https://messenger.com
 
 This documentation page only deals with the bridge's ability to bridge to Instagram. For bridging to Facebook/Messenger, see [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md).
 
+## Prerequisites
 
-## Migrating from the old mautrix-instagram bridge
+### Migrating from the old mautrix-instagram bridge
 
 If you've been using the [mautrix-instagram](./configuring-playbook-bridge-mautrix-instagram.md) bridge, **you'd better get rid of it first** or the 2 bridges will be in conflict:
 
@@ -18,6 +19,11 @@ To do so, send a `clean-rooms` command to the management room with the old bridg
 
 Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
 
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
 
 ## Adjusting the playbook configuration
 
@@ -42,6 +48,7 @@ Different levels of permission can be granted to users:
 The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
 
 The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this:
+
 ```yaml
 matrix_mautrix_meta_instagram_bridge_permissions_default:
   '*': relay
@@ -62,21 +69,38 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templ
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
-### Method 2: manually, by asking each user to provide a working access token
+## Usage
 
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
+You then need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
@@ -85,8 +109,3 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 
 - make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
-
-
-## Usage
-
-You then need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

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

@@ -6,8 +6,9 @@ Since this bridge component can bridge to both [Messenger](https://messenger.com
 
 This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md).
 
+## Prerequisites
 
-## Migrating from the old mautrix-facebook bridge
+### Migrating from the old mautrix-facebook bridge
 
 If you've been using the [mautrix-facebook](./configuring-playbook-bridge-mautrix-facebook.md) bridge, it's possible to migrate the database using [instructions from the bridge documentation](https://docs.mau.fi/bridges/go/meta/facebook-migration.html) (advanced).
 
@@ -17,6 +18,12 @@ Then, consider disabling the old bridge in your configuration, so it won't recre
 
 **Note**: the user ID of the new bridge bot is `@messengerbot:example.com`, not `@facebookbot:example.com`. After disabling the old bridge, its bot user will stop responding to a command.
 
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -41,7 +48,6 @@ You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variab
 
 Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.).
 
-
 ### Bridge permissions
 
 By default, any user on your homeserver will be able to use the bridge.
@@ -55,6 +61,7 @@ Different levels of permission can be granted to users:
 The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
 
 The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this:
+
 ```yaml
 matrix_mautrix_meta_messenger_bridge_permissions_default:
   '*': relay
@@ -75,30 +82,20 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templ
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
-
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
@@ -107,3 +104,25 @@ You then need to start a chat with `@messengerbot:example.com` (where `example.c
 You then need to send a `login` command and follow the bridge bot's instructions.
 
 Given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there as per [the bridge's authentication instructions](https://docs.mau.fi/bridges/go/meta/authentication.html).
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature

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

@@ -4,10 +4,22 @@ The playbook can install and configure [mautrix-signal](https://github.com/mautr
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/signal/index.html) to learn what it does and why it might be useful to you.
 
-**Note/Prerequisite**: If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing. However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
-
 **Note**: This revamped version of the [mautrix-signal (legacy)](configuring-playbook-bridge-mautrix-signal.md) may increase the CPU usage of your homeserver.
 
+## Prerequisites (optional)
+
+### Prepare Postgres database on external Postgres server
+
+If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing.
+
+However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
+
+### Enable Appservice Double Puppet
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -29,6 +41,7 @@ Different levels of permission can be granted to users:
 The permissions are following the sequence: nothing < relay < user < admin.
 
 The default permissions are set as follows:
+
 ```yaml
 permissions:
   '*': relay
@@ -36,6 +49,7 @@ permissions:
 ```
 
 If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file:
+
 ```yaml
 matrix_mautrix_signal_configuration_extension_yaml: |
   bridge:
@@ -46,6 +60,7 @@ matrix_mautrix_signal_configuration_extension_yaml: |
 This will add the admin permission to the specific user, while keeping the default permissions.
 
 In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
+
 ```yaml
 matrix_mautrix_signal_bridge_permissions:
   '@ADMIN:example.com': admin
@@ -56,21 +71,38 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/con
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+You then need to start a chat with `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
 
 This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
 
-### Method 2: manually, by asking each user to provide a working access token
+#### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
@@ -79,8 +111,3 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 
 - make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature
-
-
-## Usage
-
-You then need to start a chat with `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

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

@@ -10,13 +10,17 @@ See the project's [documentation](https://docs.mau.fi/bridges/go/slack/index.htm
 
 See the [features and roadmap](https://github.com/mautrix/slack/blob/main/ROADMAP.md) for more information.
 
-
 ## Prerequisites
 
 For using this bridge, you would need to authenticate by **providing your username and password** (legacy) or by using a **token login**. See more information in the [docs](https://docs.mau.fi/bridges/go/slack/authentication.html).
 
 Note that neither of these methods are officially supported by Slack. [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) uses a Slack bot account which is the only officially supported method for bridging a Slack channel.
 
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
 
 ## Adjusting the playbook configuration
 
@@ -28,17 +32,6 @@ matrix_mautrix_slack_enabled: true
 
 You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
 
-## Installing
-
-After configuring the playbook, run the [installation](installing.md) command:
-
-```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
-```
-
-To make use of the bridge, see [Usage](#usage) below.
-
-
 ### Additional configuration
 
 There are some additional options you may wish to configure with the bridge.
@@ -48,29 +41,22 @@ Take a look at:
 - `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
 - `roles/custom/matrix-bridge-mautrix-slack/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_slack_configuration_extension_yaml` variable
 
+## Installing
 
-### Set up Double Puppeting
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-#### Method 1: automatically, by enabling Appservice Double Puppet
+**Notes**:
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
-
-#### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
-
-- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
@@ -79,3 +65,25 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
 3. The bot should respond with "Successfully logged into <email> for team <workspace>"
 4. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to.
 5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication.
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature

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

@@ -4,6 +4,12 @@ The playbook can install and configure [mautrix-telegram](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/index.html) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -16,32 +22,20 @@ matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
-
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
-### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging.
-
-When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
-
-- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
-
-- send `login-matrix` to the bot and follow instructions about how to send the access token to it
-
-- make sure you don't log out the `Mautrix-Telegram` device some time in the future, as that would break the Double Puppeting feature
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 
@@ -58,6 +52,7 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
 ```
 
 You might also want to give permissions to administrate the bot:
+
 ```yaml
 matrix_mautrix_telegram_configuration_extension_yaml: |
   bridge:
@@ -68,6 +63,33 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
 More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
 
 If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration:
+
 ```yaml
 matrix_mautrix_telegram_filter_mode: whitelist
 ```
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+
+Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging.
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send `login-matrix` to the bot and follow instructions about how to send the access token to it
+
+- make sure you don't log out the `Mautrix-Telegram` device some time in the future, as that would break the Double Puppeting feature

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

@@ -6,6 +6,12 @@ The playbook can install and configure [mautrix-twitter](https://github.com/maut
 
 See the project's [documentation](https://github.com/mautrix/twitter) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -16,23 +22,20 @@ matrix_mautrix_twitter_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
-### Method 2: manually, by asking each user to provide a working access token
-
-This method is currently not available for the Mautrix-Twitter bridge, but is on the [roadmap](https://github.com/mautrix/twitter/blob/master/ROADMAP.md) under Misc/Manual login with `login-matrix`
 
 ## Usage
 
@@ -41,4 +44,20 @@ This method is currently not available for the Mautrix-Twitter bridge, but is on
 
 You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/twitter/authentication.html).
 
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+
+Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+
+#### Method 2: manually, by asking each user to provide a working access token
+
+This method is currently not available for the Mautrix-Twitter bridge, but is on the [roadmap](https://github.com/mautrix/twitter/blob/master/ROADMAP.md) under Misc/Manual login with `login-matrix`

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

@@ -4,6 +4,12 @@ The playbook can install and configure [mautrix-whatsapp](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/whatsapp/index.html) to learn what it does and why it might be useful to you.
 
+## Prerequisite (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+
+For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -30,23 +36,40 @@ If you want to activate the relay bot in a room, send `!wa set-relay`. To deacti
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-## Set up Double Puppeting
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
 
-If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
+**Notes**:
 
-### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
 
-The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+## Usage
+
+You then need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+
+### 💡 Set up Double Puppeting
+
+After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
+
+To set it up, you have 2 ways of going about it.
+
+#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
 
 Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
 
 Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
 
-### Method 2: manually, by asking each user to provide a working access token
+#### Method 2: manually, by asking each user to provide a working access token
-
-**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
@@ -55,8 +78,3 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 
 - make sure you don't log out the `Mautrix-Whatsapp` device some time in the future, as that would break the Double Puppeting feature
-
-
-## Usage
-
-You then need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

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

@@ -41,7 +41,20 @@ By default, you will need to create a CNAME record for `wsproxy`. See [Configuri
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -18,7 +18,20 @@ matrix_mx_puppet_discord_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -14,7 +14,20 @@ matrix_mx_puppet_groupme_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -14,7 +14,20 @@ matrix_mx_puppet_instagram_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -23,11 +23,20 @@ matrix_mx_puppet_slack_oauth_client_secret: "<SLACK_APP_CLIENT_SECRET>"
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
-ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+
-```
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -14,7 +14,20 @@ matrix_mx_puppet_steam_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

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

@@ -25,7 +25,20 @@ matrix_mx_puppet_twitter_environment: ''
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-bridge-postmoogle.md

@@ -19,7 +19,6 @@ If you don't open these ports, you will still be able to send emails, but not re
 
 These port numbers are configurable via the `matrix_postmoogle_smtp_host_bind_port` and `matrix_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
 
-
 ## Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -49,18 +48,22 @@ You will also need to add several DNS records so that Postmoogle can send emails
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
 ```
 
 **Notes**:
 
-- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create a user account of the bridge's bot
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create a user account of the bridge's bot.
 
-- if you change the bridge's bot password (`matrix_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_postmoogle_password` to let the bot know its new password
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the bridge's bot password (`matrix_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_postmoogle_password` to let the bot know its new password.
 
 ## Usage
 

docs/configuring-playbook-bridge-wechat.md

@@ -14,7 +14,20 @@ matrix_wechat_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-cactus-comments.md

@@ -63,7 +63,20 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Usage
 

docs/configuring-playbook-client-cinny.md

@@ -8,7 +8,6 @@ Cinny is a web client focusing primarily on simple, elegant and secure interface
 
 - [app.cinny.in](https://app.cinny.in), hosted by the [Cinny](https://cinny.in/) developers
 
-
 ## Adjusting the playbook configuration
 
 To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -42,4 +41,13 @@ If you've adjusted `matrix_client_cinny_hostname`, you will need to adjust your
 
 ## Installing
 
-After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-client-element-web.md

@@ -7,7 +7,6 @@ By default, this playbook installs the [Element Web](https://github.com/element-
 - [app.element.io](https://app.element.io/), hosted by [Element](https://element.io/)
 - [app.etke.cc](https://app.etke.cc/), hosted by [etke.cc](https://etke.cc/)
 
-
 ## Disabling Element Web
 
 If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -16,7 +15,6 @@ If you'd like for the playbook to not install Element Web (or to uninstall it if
 matrix_client_element_enabled: false
 ```
 
-
 ## Adjusting the playbook configuration
 
 The playbook provides some customization variables you could use to change Element Web's settings.
@@ -33,7 +31,6 @@ Alternatively, **if there is no pre-defined variable** for an Element Web settin
 
 - or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
 
-
 ### Themes
 
 To change the look of Element Web, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
@@ -71,4 +68,13 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-client-hydrogen.md

@@ -39,4 +39,13 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-client-schildichat-web.md

@@ -8,8 +8,6 @@ SchildiChat Web is a feature-rich messenger for Matrix based on Element Web with
 
 - [app.schildi.chat](https://app.schildi.chat/), hosted by the [SchildiChat](https://schildi.chat/) developers
 
-**WARNING**: SchildiChat Web is based on Element Web, but its releases are lagging behind. As of 2024-11, SchildiChat Web is many releases behind (it being based on Element Web `v1.11.36`, while Element Web is now on `v1.11.85`). Element Web frequently suffers from security issues (see [here](https://github.com/element-hq/element-web/security) for known issues), so running something based on an ancient Element Web release is **unsafe**. Use SchildiChat Web at your own risk!
-
 ## Adjusting the playbook configuration
 
 To enable SchildiChat Web, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -69,4 +67,13 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-conduit.md

@@ -27,7 +27,6 @@ Since it is difficult to create the first user account on Conduit (see [famedly/
 5. Run the playbook again (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-conduit,start` would be enough this time)
 6. You can now use your server safely. Additional users can be created by messaging the internal Conduit bot
 
-
 ## Configuring bridges / appservices
 
 Automatic appservice setup is currently unsupported when using Conduit. After setting up the service as usual you may notice that it is unable to start.
@@ -36,7 +35,6 @@ You will have to manually register appservices using the the [register-appservic
 
 Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to Conduit:
 
-
     @conduit:example.com: register-appservice
     ```
     as_token: <token>

docs/configuring-playbook-dendrite.md

@@ -30,8 +30,15 @@ Alternatively, **if there is no pre-defined variable** for a Dendrite setting yo
 
 - or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
 
-
-
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-dimension.md

@@ -20,8 +20,8 @@ These users can modify the integrations this Dimension supports. Add this to you
 
 ```yaml
 matrix_dimension_admins:
-  - "@user1:{{ matrix_domain }}"
+  - "@alice:{{ matrix_domain }}"
-  - "@user2:{{ matrix_domain }}"
+  - "@bob:{{ matrix_domain }}"
 ```
 
 The admin interface is accessible within Element Web by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element Web by the "Add widgets, bridges, & bots" link in the room information.
@@ -69,14 +69,20 @@ By default, you will need to create a CNAME record for `dimension`. See [Configu
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
-After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the Room info button (`i`) button in the top right corner of the screen, and then clicking Add widgets, bridges & bots.
+**Notes**:
 
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+- After Dimension has been installed you may need to log out and log back in for it to pick up the new integration manager. Then you can access integrations in Element Web by opening a room, clicking the Room info button (`i`) button in the top right corner of the screen, and then clicking Add widgets, bridges & bots.
 
 ## Jitsi domain
 
@@ -84,7 +90,6 @@ By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `co
 
 In the interim until the above limitation is resolved, an admin user needs to configure the domain via the admin ui once dimension is running. In Element Web, go to *Manage Integrations* &rightarrow; *Settings* &rightarrow; *Widgets* &rightarrow; *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
 
-
 ## Additional features
 
 To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.

docs/configuring-playbook-dynamic-dns.md

@@ -25,7 +25,16 @@ matrix_dynamic_dns_domain_configurations:
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Additional Reading
 

docs/configuring-playbook-email.md

@@ -10,12 +10,10 @@ By default, emails are sent from `matrix@matrix.example.com`, as specified by th
 
 💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.
 
-
 ## Firewall settings
 
 No matter whether you send email directly (the default) or you relay email through another host (see how below), you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).
 
-
 ## Relaying email through another SMTP server
 
 If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
@@ -32,8 +30,8 @@ exim_relay_relay_auth_password: "some-password"
 
 **Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
 
-
 ### Configuations for sending emails using Sendgrid
+
 An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `exim_relay_sender_address`.
 
 The only other thing you need to change is the `exim_relay_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.

docs/configuring-playbook-email2matrix.md

@@ -6,7 +6,6 @@ The playbook can install and configure [email2matrix](https://github.com/devture
 
 See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
 
-
 ## Preparation
 
 ### DNS configuration
@@ -83,6 +82,16 @@ Refer to the official documentation [here](https://github.com/devture/email2matr
 
 ## Installing
 
-To enable Email2Matrix, run the [installation](installing.md) command (`--tags=setup-email2matrix,start`).
+To enable Email2Matrix, run the playbook with [playbook tags](playbook-tags.md) as below:
 
-After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected.
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-email2matrix,start
+```
+
+**Notes**:
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just run-tags setup-email2matrix,start` or `just setup-all`
+
+  `just run-tags setup-email2matrix,start` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
+
+- After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected.

docs/configuring-playbook-etherpad.md

@@ -33,7 +33,6 @@ etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
 etherpad_path_prefix: /etherpad
 ```
 
-
 ## Adjusting DNS records
 
 Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
@@ -44,7 +43,22 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the Etherpad admin user (`etherpad_admin_username`).
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
+
+- If you change the Etherpad admin user's password (`etherpad_admin_password` in your `vars.yml` file) subsequently, the admin user's credentials on the homeserver won't be updated automatically. If you'd like to change the admin user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `etherpad_admin_password` to let the admin user know its new password.
 
 ## Usage
 
@@ -52,35 +66,30 @@ The Etherpad UI should be available at `https://etherpad.example.com`, while the
 
 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
 
 If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above.
 
 Then from the plugin manager page (`https://etherpad.example.com/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
 
-
 ### How to use Etherpad widgets without an integration manager (like Dimension)
 
 This is how it works in Element Web, it might work quite similar with other clients:
 
 To integrate a standalone Etherpad in a room, create your pad by visiting `https://etherpad.example.com`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section.
 
-
 ### Set Dimension default to the self-hosted Etherpad (optional)
 
 If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside Etherpad, the Dimension administrator users can configure the default URL template.
 
 The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element Web. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab.
 
-
 #### Removing the integrated Etherpad chat
 
 If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
 
 Example: `https://etherpad.example.com/p/$roomId_$padName?showChat=false`
 
-
 ## Known issues
 
 If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.

docs/configuring-playbook-federation.md

@@ -16,7 +16,6 @@ matrix_synapse_federation_domain_whitelist:
 
 If you wish to disable federation, you can do that with an empty list (`[]`), or better yet by completely disabling federation (see below).
 
-
 ## Exposing the room directory over federation
 
 By default, your server's public rooms directory is not exposed to other servers via federation.
@@ -27,7 +26,6 @@ If you wish to expose it, add this to your configuration file (`inventory/host_v
 matrix_synapse_allow_public_rooms_over_federation: true
 ```
 
-
 ## Disabling federation
 
 To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
@@ -54,10 +52,9 @@ matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
 
 Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
 
-
 The following changes in the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
 
-```
+```yaml
 matrix_synapse_http_listener_resource_names: ["client","federation"]
 # Any port can be used but in this case we use 443
 matrix_federation_public_port: 443

docs/configuring-playbook-jitsi.md

@@ -6,7 +6,6 @@ Jitsi installation is **not enabled by default**, because it's not a core compon
 
 The setup done by the playbook is very similar to [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the documentation there for many of the options here.
 
-
 ## Prerequisites
 
 You may need to open the following ports to your server:
@@ -14,7 +13,6 @@ You may need to open the following ports to your server:
 - `4443/tcp` - RTP media fallback over TCP
 - `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
 
-
 ## Adjusting the playbook configuration
 
 To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -114,7 +112,6 @@ jitsi_ldap_start_tls: false
 
 For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
 
-
 ## (Optional) Making your Jitsi server work on a LAN
 
 By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
@@ -172,18 +169,19 @@ By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-vid
 There is an ansible playbook that can be run with the following tag: `ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
 
 For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
-```
+
+```INI
 [jitsi_jvb_servers]
 <your jvb hosts> ansible_host=<ip address of the jvb host>
 ```
 
 Each JVB will require a server ID to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB. The server ID is set with the variable `jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container. This variable can be set via the host file, a parameter to the ansible command or in the `vars.yaml` for the host which will have the additional JVB. For example:
 
-``` yaml
+```yaml
 jitsi_jvb_server_id: 'jvb-2'
 ```
 
-``` INI
+```INI
 [jitsi_jvb_servers]
 jvb-2.example.com ansible_host=192.168.0.2 jitsi_jvb_server_id=jvb-2
 jvb-3.example.com ansible_host=192.168.0.3 jitsi_jvb_server_id=jvb-2
@@ -269,12 +267,17 @@ jitsi_disable_gravatar: false
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
 ## Usage
 
 You can use the self-hosted Jitsi server in multiple ways:
@@ -287,7 +290,6 @@ You can use the self-hosted Jitsi server in multiple ways:
 
 **Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/element-hq/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
 
-
 ## Troubleshooting
 
 ### Rebuilding your Jitsi installation

docs/configuring-playbook-ldap-auth.md

@@ -21,7 +21,6 @@ matrix_synapse_ext_password_provider_ldap_bind_password: ""
 matrix_synapse_ext_password_provider_ldap_filter: ""
 ```
 
-
 ## Authenticating only using a password provider
 
 If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
@@ -30,12 +29,10 @@ If you wish for users to **authenticate only against configured password provide
 matrix_synapse_password_config_localdb_enabled: false
 ```
 
-
 ## Using ma1sd Identity Server for authentication
 
 If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).
 
-
 ## Handling user registration
 
 If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md).

docs/configuring-playbook-ma1sd.md

@@ -51,7 +51,6 @@ Still, ma1sd can do much more. You can refer to the [ma1sd website](https://gith
 
 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.
@@ -72,7 +71,6 @@ 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](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.
@@ -131,7 +129,16 @@ matrix_ma1sd_configuration_extension_yaml: |
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Troubleshooting
 

docs/configuring-playbook-matrix-authentication-service.md

@@ -12,7 +12,6 @@ Matrix Authentication Service is an implementation of [MSC3861: Next-generation
 
 **If you've already been using Synapse** and have user accounts in its database, you can [migrate to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service).
 
-
 ## Reasons to use Matrix Authentication Service
 
 You may be wondering whether you should make the switch to Matrix Authentication Service (MAS) or keep using your existing authentication flow via Synapse (password-based or [OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)-enabled).
@@ -33,7 +32,6 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
 
 - To reap some of the security benefits that Matrix Authentication Service offers, as outlined in the [Better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/) article.
 
-
 ## 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.
@@ -42,7 +40,6 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
 
 - ❌ **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.
 
-
 ## Expectations
 
 This section details what you can expect when switching to the Matrix Authentication Service (MAS).
@@ -84,8 +81,6 @@ This section details what you can expect when switching to the Matrix Authentica
 
 - ✅ Users that are prepared by the playbook (for bots, bridges, etc.) will continue to be registered automatically as expected. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS.
 
-
-
 ## Installation flows
 
 ### New homeserver
@@ -102,7 +97,6 @@ For existing Synapse homeservers:
 
 - then follow the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) instructions to perform the installation and migration
 
-
 ## Adjusting the playbook configuration
 
 To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -123,7 +117,6 @@ In the sub-sections that follow, we'll cover some additional configuration optio
 
 There are many other configuration options available. Consult the [`defaults/main.yml` file](../roles/custom/matrix-authentication-service/defaults/main.yml) in the [matrix-authentication-service role](../roles/custom/matrix-authentication-service/) to discover them.
 
-
 ### Adjusting the Matrix Authentication Service URL
 
 By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (https://matrix.example.com/auth). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
@@ -144,7 +137,6 @@ The [configuration above](#adjusting-the-playbook-configuration) instructs exist
 
 This is done temporarily. The migration steps are described in more detail in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) section below.
 
-
 ### Upstream OAuth2 configuration
 
 To make Matrix Authentication Service delegate to an existing upstream OAuth 2.0/OIDC provider, you can use its [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers).
@@ -276,7 +268,6 @@ matrix_authentication_service_config_upstream_oauth2_providers:
 - go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process
 - remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration
 
-
 ## Adjusting DNS records
 
 If you've changed the default hostname, **you may need to adjust your DNS** records to point the Matrix Authentication Service domain to the Matrix server.
@@ -285,16 +276,25 @@ See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
 
-
 ## Installing
 
-Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the [installation](installing.md) command: `just install-all`
+Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
 
-If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) guide.
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+**Notes**:
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+- If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) guide.
 
 💡 After installation, you should [verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly).
 
-
 ## Migrating an existing Synapse homeserver to Matrix Authentication Service
 
 Our migration guide is loosely based on the upstream [Migrating an existing homeserver](https://element-hq.github.io/matrix-authentication-service/setup/migration.html) guide.
@@ -333,7 +333,6 @@ The installation + migration steps are like this:
 
 6. [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)
 
-
 ### Migrate your data from Synapse to Matrix Authentication Service using syn2mas
 
 We **don't** ask you to [run the `syn2mas` migration advisor command](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#run-the-migration-advisor), because it only gives you the green light if your Synapse configuration (`homeserver.yaml`) is configured in a way that's compatible with MAS (delegating authentication to MAS; disabling Synapse's password config; etc.). Until we migrate your data with the `syn2mas` tool, we intentionally avoid doing these changes to allow existing user sessions to work.
@@ -364,7 +363,7 @@ The same OIDC provider may have an `id` of `01HFVBY12TMNTYTBV8W921M5FA` on the M
 
 To tell `syn2mas` how the Synapse-configured OIDC provider maps to the new MAS-configured OIDC provider, add this additional configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-```yml
+```yaml
 # Adjust the mapping below to match your provider IDs on the Synapse side and the MAS side.
 # Don't forget that Synapse automatically adds an `oidc-` prefix to provider ids defined in its configuration.
 matrix_authentication_service_syn2mas_process_extra_arguments:
@@ -407,7 +406,6 @@ just run-tags matrix-authentication-service-syn2mas
 
 Having performed a `syn2mas` migration once, trying to do it again will report errors for users that were already migrated (e.g. "Error: Unknown upstream provider oauth-delegated").
 
-
 ## Verify that Matrix Authentication Service is installed correctly
 
 After [installation](#installing), run the `doctor` subcommand of the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) to verify that MAS is installed correctly.
@@ -442,14 +440,12 @@ This documentation page already mentions:
 
 There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview.
 
-
 ## User registration
 
 After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)).
 
 You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag).
 
-
 ## Working around email deliverability issues
 
 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, you may need to work around email deliverability issues if [your email-sending configuration](./configuring-playbook-email.md) is not working.

docs/configuring-playbook-matrix-corporal.md

@@ -14,7 +14,6 @@ If you decide that you'd like to let this playbook install it for you, you'd nee
 - (required) [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md)
 - (optional, but encouraged) [set up the REST authentication password provider module](configuring-playbook-rest-auth.md)
 
-
 ## Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
@@ -116,8 +115,16 @@ To learn more about what the policy configuration, see the matrix-corporal docum
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command (`--tags=setup-all,start` or `--tags=setup-aux-files,setup-corporal,start`).
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just run-tags setup-aux-files,setup-corporal,start` or `just setup-all`
+
+`just run-tags setup-aux-files,setup-corporal,start` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
 
 ## Matrix Corporal files
 

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

@@ -34,4 +34,13 @@ matrix_ldap_registration_proxy_systemd_wanted_services_list_custom:
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

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

@@ -30,6 +30,7 @@ By default, the media-repo will use the local filesystem for data storage. You c
 ## Configuring the media-repo
 
 Additional common configuration options:
+
 ```yaml
 
 # The postgres database pooling options

docs/configuring-playbook-matrix-registration.md

@@ -16,7 +16,6 @@ Use matrix-registration to **create unique registration links**, which people ca
 
 - **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.example.com/matrix-registration`
 
-
 ## Adjusting the playbook configuration
 
 To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -52,12 +51,16 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 
@@ -67,12 +70,11 @@ It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/a
 
 We make the most common APIs easy to use via the playbook (see below).
 
-
 ### Creating registration tokens
 
 To **create a new user registration token (link)**, use this command:
 
-```bash
+```sh
 ansible-playbook -i inventory/hosts setup.yml \
 --tags=generate-matrix-registration-token \
 --extra-vars="one_time=yes ex_date=2021-12-31"
@@ -82,12 +84,13 @@ The above command creates and returns a **one-time use** token, which **expires*
 
 Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
 
-
 ### Listing registration tokens
 
 To **list the existing user registration tokens**, use this command:
 
-```bash
+```sh
 ansible-playbook -i inventory/hosts setup.yml \
 --tags=list-matrix-registration-tokens
 ```
+
+The shortcut command with `just` program is also available: `just run-tags list-matrix-registration-tokens`

docs/configuring-playbook-mautrix-bridges.md

@@ -93,13 +93,26 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/template
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
+```
+
+**Notes**:
+
+- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
+
+- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+  `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
 
 ## Set up Double Puppeting
 
 To set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
 
-The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook by adding
+The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) is configured and enabled on the server for this playbook by adding
 
 ```yaml
 matrix_appservice_double_puppet_enabled: true
@@ -117,7 +130,6 @@ to `vars.yml` to control the logging level, where you may replace WARN with one
 
 If you have issues with a service, and are requesting support, the higher levels of logging will generally be more helpful.
 
-
 ## Usage
 
 You then need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
@@ -126,8 +138,6 @@ Send `login` to the bridge bot to get started. You can learn more here about aut
 
 If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
 
-
-
 ## Troubleshooting
 
 For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.

docs/configuring-playbook-ntfy.md

@@ -8,7 +8,6 @@ This role is intended to support UnifiedPush notifications for use with the Matr
 
 **Note**: In contrast to push notifications using Google's FCM or Apple's APNs, the use of UnifiedPush allows each end-user to choose the push notification server that they prefer.  As a consequence, deploying this ntfy server does not by itself ensure any particular user or device or client app will use it.
 
-
 ## Adjusting the playbook configuration
 
 To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -50,12 +49,16 @@ By default, you will need to create a CNAME record for `ntfy`. See [Configuring
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 
@@ -102,7 +105,6 @@ ntfy also has a web app to subscribe to and push to topics from the browser. Thi
 
 The web app is disabled in this playbook by default as the expectation is that most users won't use it. You can either use the [official hosted one](https://ntfy.sh/app) (it supports using other public reachable ntfy instances) or host it yourself by setting `ntfy_web_root: "app"` and re-running Ansible.
 
-
 ## Troubleshooting
 
 First check that the Matrix client app you are using supports UnifiedPush. There may well be different variants of the app.

docs/configuring-playbook-own-webserver.md

@@ -24,7 +24,6 @@ traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
 
 Traefik will manage SSL certificates for all services seamlessly.
 
-
 ### Traefik managed by you
 
 ```yaml
@@ -132,7 +131,6 @@ There are 2 ways to go about it:
 
 - (difficult) [Using no reverse-proxy on the Matrix side at all](#using-no-reverse-proxy-on-the-matrix-side-at-all) disabling the playbook-managed reverse-proxy (Traefik), exposing services one by one using `_host_bind_port` variables and forwarding traffic from your own webserver to those ports
 
-
 ### Fronting the integrated reverse-proxy webserver with another reverse-proxy
 
 This method is about leaving the integrated reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
@@ -201,7 +199,6 @@ To put it another way:
 - `curl http://127.0.0.1:81` will result in a `404 - not found` error
 - but `curl -H 'Host: matrix.example.com' http://127.0.0.1:81` should work.
 
-
 ### Using no reverse-proxy on the Matrix side at all
 
 Instead of [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), you can also go another way -- completely disabling the playbook-managed Traefik reverse-proxy. You would then need to reverse-proxy from your own webserver directly to each individual Matrix service.

docs/configuring-playbook-pantalaimon.md

@@ -18,4 +18,13 @@ The default configuration should suffice. For advanced configuration, you can ov
 
 ## 2. Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-postgres-backup.md

@@ -4,7 +4,6 @@ The playbook can install and configure [docker-postgres-backup-local](https://gi
 
 For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [BorgBackup](configuring-playbook-backup-borg.md) instead.
 
-
 ## Adjusting the playbook configuration
 
 To enable Postgres backup, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -15,7 +14,6 @@ postgres_backup_enabled: true
 
 Refer to the table below for additional configuration variables and their default values.
 
-
 | Name                              | Default value                | Description                                                      |
 | :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
 |`postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
@@ -26,11 +24,15 @@ Refer to the table below for additional configuration variables and their defaul
 |`postgres_backup_base_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Base path for postgres-backup. Also see `postgres_backup_data_path` |
 |`postgres_backup_data_path` | `"{{ postgres_backup_base_path }}/data"` | Storage path for postgres-backup database backups |
 
-
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-prometheus-grafana.md

@@ -55,7 +55,16 @@ By default, you will need to create a CNAME record for `stats`. See [Configuring
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## What does it do?
 
@@ -69,14 +78,12 @@ Name | Description
 `grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
 `grafana_default_admin_user`<br>`grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
 
-
 ## Security and privacy
 
 Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
 
 Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
 
-
 ## Collecting metrics to an external Prometheus server
 
 **If the integrated Prometheus server is enabled** (`prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".
@@ -113,6 +120,7 @@ Name | Description
 If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.example.com/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`.
 
 The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`. It will look a bit like this:
+
 ```yaml
 scrape_configs:
   - job_name: 'synapse'
@@ -139,7 +147,6 @@ scrape_configs:
           index: 18111
 ```
 
-
 ## More information
 
 - [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)

docs/configuring-playbook-prometheus-nginxlog.md

@@ -22,7 +22,16 @@ matrix_prometheus_nginxlog_exporter_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Docker Image Compatibility
 

docs/configuring-playbook-prometheus-postgres.md

@@ -12,7 +12,16 @@ prometheus_postgres_exporter_enabled: true
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## What does it do?
 
@@ -23,7 +32,6 @@ Name | Description
 `prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
 `prometheus_postgres_exporter_container_labels_traefik_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.example.com/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page.
 
-
 ## More information
 
 - [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)

docs/configuring-playbook-rageshake.md

@@ -51,12 +51,16 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 

docs/configuring-playbook-rest-auth.md

@@ -26,4 +26,13 @@ matrix_synapse_password_config_localdb_enabled: false
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-riot-web.md

@@ -7,7 +7,6 @@ Riot has since been [renamed to Element](https://element.io/blog/welcome-to-elem
 - to learn more about Element Web and its configuration, see our dedicated [Configuring Element Web](configuring-playbook-client-element-web.md) documentation page
 - to learn how to migrate from Riot to Element Web, see [Migrating to Element Web](#migrating-to-element-web) below
 
-
 ## Migrating to Element Web
 
 ### Migrating your custom settings
@@ -16,7 +15,6 @@ If you have custom `matrix_riot_web_` variables in your `inventory/host_vars/mat
 
 Some other playbook variables (but not all) with `riot` in their name are also renamed. The playbook checks and warns if you are using the old name for some commonly used ones.
 
-
 ### Domain migration
 
 We used to set up Riot at the `riot.example.com` domain. The playbook now sets up Element Web at `element.example.com` by default.
@@ -27,7 +25,15 @@ There are a few options for handling this:
 
 - (**embracing changes** - using only `element.example.com`) - set up the `element.example.com` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.example.com` in this case.
 
-
 ### Re-running the playbook
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-s3-goofys.md

@@ -29,7 +29,6 @@ matrix_s3_media_store_custom_endpoint: "https://your-custom-endpoint"
 
 If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
 
-
 ## Migrating from local filesystem storage to S3
 
 It's a good idea to [make a complete server backup](faq.md#how-do-i-back-up-the-data-on-my-server) before migrating your local media store to an S3-backed one.
@@ -85,7 +84,6 @@ After making the backup, follow one of the guides below for a migration path fro
 
 14. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
 
-
 ### Migrating to Backblaze B2
 
 1. While all Matrix services are running, run the following command on the server:

docs/configuring-playbook-s3.md

@@ -12,7 +12,6 @@ Then, [create the S3 bucket](#bucket-creation-and-security-configuration).
 
 Finally, [set up S3 storage for Synapse](#setting-up) (with [Goofys](configuring-playbook-s3-goofys.md), [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md), or use s3 datastore with the [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html)).
 
-
 ## Choosing an Object Storage provider
 
 You can create [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object storage like [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html), [Storj](https://storj.io), [Wasabi](https://wasabi.com), [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces), etc.
@@ -32,7 +31,6 @@ Here are some of the important aspects of choosing the right provider:
 - if a provider's price model is transparent (whether it includes hidden costs like minimum charge, minimum storage term, etc.)
 - if a provider has free or cheap egress fee (in case you need to get the data out often, for some reason) - likely not too important for the common use-case
 
-
 ## Bucket creation and Security Configuration
 
 Now that you've [chosen an Object Storage provider](#choosing-an-object-storage-provider), you need to create a storage bucket.
@@ -66,7 +64,6 @@ You'll need an Amazon S3 bucket and some IAM user credentials (access key + secr
 
 **Note**: This policy needs to be attached to an IAM user created from the **Security Credentials** menu. This is not a **Bucket Policy**.
 
-
 ## Backblaze B2
 
 To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) you first need to sign up.
@@ -92,14 +89,12 @@ For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-stora
 
 - **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.
 
-
 ## Other providers
 
 For other S3-compatible providers, you may not need to configure security policies, etc. (just like for [Backblaze B2](#backblaze-b2)).
 
 You most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner.
 
-
 ## Setting up
 
 To set up Synapse to store files in S3, follow the instructions for the method of your choice:

docs/configuring-playbook-shared-secret-auth.md

@@ -25,4 +25,13 @@ matrix_synapse_password_config_localdb_enabled: false
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

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

@@ -6,7 +6,6 @@ The playbook can install and configure [sliding-sync](https://github.com/matrix-
 
 Sliding Sync is an implementation of [MSC3575](https://github.com/matrix-org/matrix-spec-proposals/blob/kegan/sync-v3/proposals/3575-sync.md) and a prerequisite for running Element X clients ([Element X iOS](https://github.com/element-hq/element-x-ios) and [Element X Android](https://github.com/element-hq/element-x-android)). See the project's [documentation](https://github.com/matrix-org/sliding-sync) to learn more.
 
-
 ## Adjusting the playbook configuration
 
 To enable Sliding Sync proxy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -39,7 +38,16 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`.
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ### External databases
 

docs/configuring-playbook-ssl-certificates.md

@@ -4,7 +4,6 @@ By default, this playbook retrieves and auto-renews free SSL certificates from [
 
 This guide is about using the integrated Traefik server and doesn't apply if you're using [your own webserver](configuring-playbook-own-webserver.md).
 
-
 ## Using staging Let's Encrypt certificates instead of real ones
 
 For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
@@ -15,7 +14,6 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
 traefik_config_certificatesResolvers_acme_use_staging: true
 ```
 
-
 ## Disabling SSL termination
 
 For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://`.
@@ -26,7 +24,6 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
 traefik_config_entrypoint_web_secure_enabled: false
 ```
 
-
 ## Using self-signed SSL certificates
 
 If you'd like to use your own SSL certificates, instead of the default (SSL certificates obtained automatically via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) from [Let's Encrypt](https://letsencrypt.org/)):
@@ -34,7 +31,6 @@ If you'd like to use your own SSL certificates, instead of the default (SSL cert
 - generate your self-signed certificate files
 - follow the [Using your own SSL certificates](#using-your-own-ssl-certificates) documentation below
 
-
 ## Using your own SSL certificates
 
 To use your own SSL certificates with Traefik, you need to:

docs/configuring-playbook-sygnal.md

@@ -77,12 +77,16 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 

docs/configuring-playbook-synapse-admin.md

@@ -6,7 +6,6 @@ synapse-admin is a web UI tool you can use to **administrate users, rooms, media
 
 💡 **Note**: the latest version of synapse-admin is hosted by [etke.cc](https://etke.cc/) at [admin.etke.cc](https://admin.etke.cc/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting.
 
-
 ## Adjusting the playbook configuration
 
 To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -48,7 +47,16 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 

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

@@ -6,7 +6,6 @@ See that project's [documentation](https://github.com/matrix-org/synapse-auto-ac
 
 **Note**: Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the same feature [has been merged](https://github.com/element-hq/synapse/pull/17147) into Synapse (see the [Native alternative](#native-alternative) section below). You'd better use the native feature, instead of the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module.
 
-
 ## Configuration
 
 If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -27,14 +26,13 @@ matrix_synapse_ext_synapse_auto_accept_invite_worker_to_run_on: 'matrix-synapse-
 
 There might be an [issue with federation](https://github.com/matrix-org/synapse-auto-accept-invite/issues/18).
 
-
 ## Native alternative
 
 Since Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the functionality provided by the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module [has been made](https://github.com/element-hq/synapse/pull/17147) part of Synapse.
 
 Here's example configuration for using the **native** Synapse feature:
 
-```yml
+```yaml
 matrix_synapse_auto_accept_invites_enabled: true
 
 # Default settings below. Uncomment and adjust this part if necessary.

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

@@ -6,7 +6,6 @@ It's a CLI tool that automatically compresses Synapse's `state_groups` database
 
 See the project's [documentation](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) to learn what it does and why it might be useful to you.
 
-
 ## Adjusting the playbook configuration
 
 Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -15,15 +14,18 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
 matrix_synapse_auto_compressor_enabled: true
 ```
 
-
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
-```
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 ```
 
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
 ## Usage
 

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

@@ -4,7 +4,6 @@ If you'd like to store Synapse's content repository (`media_store`) files on Ama
 
 An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).
 
-
 ## How it works?
 
 Summarized writings here are inspired by [this article](https://quentin.dufour.io/blog/2021-09-14/matrix-synapse-s3-storage/).
@@ -22,7 +21,6 @@ You can run some scripts to delete the local files once in a while (which we do
 
 While you will need some local disk space around, it's only to accommodate usage, etc., and won't grow as large as your S3 store.
 
-
 ## Installing
 
 After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
@@ -57,7 +55,6 @@ If you have existing files in Synapse's media repository (`/matrix/synapse/media
 
 Regardless of whether you need to [Migrate your existing files to the S3 store](#migrating-your-existing-media-files-to-the-s3-store) or not, make sure you've familiarized yourself with [How it works?](#how-it-works) above and [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem) below.
 
-
 ## Migrating your existing media files to the S3 store
 
 Migrating your existing data can happen in multiple ways:

docs/configuring-playbook-synapse-usage-exporter.md

@@ -50,4 +50,13 @@ If you've decided to use the default hostname, you won't need to do any extra DN
 
 ## Installing
 
-After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.

docs/configuring-playbook-synapse.md

@@ -16,7 +16,6 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
 
 - or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml).
 
-
 ## Load balancing with workers
 
 To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html).
@@ -80,12 +79,10 @@ A separate Ansible role (`matrix-synapse-reverse-proxy-companion`) and component
 
 In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/element-hq/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.
 
-
 ## Synapse Admin
 
 Certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace, if you install [Synapse Admin](configuring-playbook-synapse-admin.md).
 
-
 ## Synapse + OpenID Connect for Single-Sign-On
 
 💡 An alternative to setting up OIDC in Synapse is to use [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS). Newer clients (like Element X) only support SSO-based authentication via MAS and not via the legacy Synapse OIDC setup described below. That said, MAS is still a new experimental service which comes with its own downsides. Consult its documentation to learn if it will be a good fit for your deployment.
@@ -98,7 +95,7 @@ For more detailed documentation on available options and how to setup keycloak,
 
 In case you encounter errors regarding the parsing of the variables, you can try to add `{% raw %}` and `{% endraw %}` blocks around them. For example ;
 
-```yml
+```yaml
 matrix_synapse_oidc_enabled: true
 
 matrix_synapse_oidc_providers:
@@ -117,7 +114,6 @@ matrix_synapse_oidc_providers:
     backchannel_logout_enabled: true # Optional
 ```
 
-
 ## Customizing templates
 
 [Templates](https://github.com/element-hq/synapse/blob/develop/docs/templates.md) are used by Synapse for showing **certain web pages** handled by the server, as well as for **email notifications**.
@@ -156,7 +152,6 @@ matrix_synapse_container_image_customizations_templates_git_repository_ssh_priva
 
 As mentioned in Synapse's Templates documentation, Synapse will fall back to its own templates if a template is not found in that directory. Due to this, it's recommended to only store and maintain template files in your repository if you need to make custom changes. Other files (which you don't need to change), should not be duplicated, so that you don't need to worry about getting out-of-sync with the original Synapse templates.
 
-
 ## Monitoring Synapse Metrics with Prometheus and Grafana
 
 This playbook allows you to enable Synapse metrics, which can provide insight into the performance and activity of Synapse.

docs/configuring-playbook-telemetry.md

@@ -4,7 +4,6 @@ By default, this playbook configures your Matrix homeserver to not send any tele
 
 The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting usage statistics from your homeserver. Enabling usage statistics helps track the growth of the Matrix community, and helps to make Matrix a success.
 
-
 ## Enabling Telemetry
 
 If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -15,7 +14,6 @@ matrix_synapse_report_stats: true # for synapse
 matrix_dendrite_report_stats: true # for dendrite
 ```
 
-
 ## Usage statistics being submitted
 
 When enabled, your homeserver will regularly upload a few dozen statistics about your server. This data includes your homeserver's domain, the total number of users, the number of active users, the total number of rooms, and the number of messages sent per day on your homeserver.