Merge pull request #3649 from luixxiul/fix

Update docs/configuring-playbook-bridge-heisenbridge.md: matrix_heisenbridge_owner domain and usage

docs/configuring-dns.md

@@ -45,6 +45,7 @@ When you're done configuring DNS, proceed to [Configuring the playbook](configur
 | [SchildiChat](configuring-playbook-client-schildichat.md) web client                                                    | CNAME | `schildichat`                  | -        | -      | -    | `matrix.example.com`      |
 | [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge                                                    | CNAME | `wsproxy`                      | -        | -      | -    | `matrix.example.com`      |
 | [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot                                                         | CNAME | `buscarron`                    | -        | -      | -    | `matrix.example.com`      |
+| [Rageshake](docs/configuring-playbook-rageshake.md) bug report server                                                   | CNAME | `rageshake`                    | -        | -      | -    | `matrix.example.com`      |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX    | `matrix`                       | 10       | 0      | -    | `matrix.example.com`      |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge                                                       | TXT   | `matrix`                       | -        | -      | -    | `v=spf1 ip4:<your-ip> -all` |
 | [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge                                                       | TXT   | `_dmarc.matrix`                | -        | -      | -    | `v=DMARC1; p=quarantine;`   |
@@ -83,6 +84,8 @@ The `wsproxy.example.com` subdomain may be necessary, because this playbook coul
 
 The `buscarron.example.com` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etkecc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.example.com` DNS record.
 
+The `rageshake.example.com` subdomain may be necessary, because this playbook could install the [rageshake](https://github.com/matrix-org/rageshake) bug report server. The installation of Rageshake is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Rageshake guide](docs/configuring-playbook-rageshake.md). If you do not wish to set up Rageshake, feel free to skip the `rageshake.example.com` DNS record.
+
 ## `_matrix-identity._tcp` SRV record setup
 
 To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook may optionally install for you) enable its federation features, set up an SRV record that looks like this:

docs/configuring-playbook-alertmanager-receiver.md

@@ -10,19 +10,11 @@ This service is meant to be used with an external [Alertmanager](https://prometh
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable matrix-alertmanager-receiver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yml
 matrix_alertmanager_receiver_enabled: true
 
-# This exposes matrix-alertmanager-receiver on the `matrix.` domain.
-# Adjust, if necessary.
-matrix_alertmanager_receiver_hostname: "{{ matrix_server_fqn_matrix }}"
-
-# This exposes matrix-alertmanager-receiver under a path prefix containing a random (secret) value.
-# Adjust the `RANDOM_VALUE_HERE` part with a long and secure value.
-matrix_alertmanager_receiver_path_prefix: /matrix-alertmanager-receiver-RANDOM_VALUE_HERE
-
 # If you'd like to change the username for this bot, uncomment and adjust. Otherwise, remove.
 # matrix_alertmanager_receiver_config_matrix_user_id_localpart: "bot.alertmanager.receiver"
 
@@ -43,6 +35,27 @@ matrix_alertmanager_receiver_config_matrix_room_mapping:
 
 See `roles/custom/matrix-alertmanager-receiver/defaults/main.yml` for additional configuration variables.
 
+### Adjusting the matrix-alertmanager-receiver URL
+
+By default, this playbook installs matrix-alertmanager-receiver on the `matrix.` subdomain, at the `/matrix-alertmanager-receiver` path (https://matrix.example.com/matrix-alertmanager-receiver). 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.
+
+By tweaking the `matrix_alertmanager_receiver_hostname` and `matrix_alertmanager_receiver_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_alertmanager_receiver_hostname: alertmanager.example.com
+matrix_alertmanager_receiver_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-alertmanager-receiver domain to the Matrix server.
+
+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.
 
 ## Account and room preparation
 
@@ -56,14 +69,14 @@ The playbook can automatically create users, but it cannot automatically obtain
 4. Log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account and log out
 5. (Optionally) Adjust `matrix_alertmanager_receiver_config_matrix_room_mapping` to create a mapping between the new room and its ID
 
-Steps 1 and 2 above only need to be done once, while preparing your [configuration](#configuration).
+Steps 1 and 2 above only need to be done once, while preparing your [configuration](#adjusting-the-playbook-configuration).
 
 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) and have [configured the playbook](#configuration), 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 [installation](installing.md) command: `just install-all`
 
 Then, you can proceed to [Usage](#usage).
 

docs/configuring-playbook-bot-buscarron.md

@@ -4,33 +4,9 @@ The playbook can install and configure [buscarron](https://github.com/etkecc/bus
 
 Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.
 
-
-## Decide on a domain and path
-
-By default, Buscarron is configured to use its own dedicated domain (`buscarron.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
-
-You can override the domain and path like this:
-
-```yaml
-# Switch to the domain used for Matrix services (`matrix.example.com`),
-# so we won't need to add additional DNS records for Buscarron.
-matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
-
-# Expose under the /buscarron subpath
-matrix_bot_buscarron_path_prefix: /buscarron
-```
-
-
-## Adjusting DNS records
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
-
-If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
-
-
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable Buscarron, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_buscarron_enabled: true
@@ -53,10 +29,34 @@ matrix_bot_buscarron_forms:
 matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
 ```
 
+### Adjusting the Buscarron URL
+
+By default, this playbook installs Buscarron on the `buscarron.` subdomain (`buscarron.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_bot_buscarron_hostname` and `matrix_bot_buscarron_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Buscarron.
+matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /buscarron subpath
+matrix_bot_buscarron_path_prefix: /buscarron
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `buscarron`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

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

@@ -24,32 +24,9 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb
 Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
 
 
-## Decide on a domain and path
-
-By default, Go-NEB is configured to use its own dedicated domain (`goneb.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
-
-You can override the domain and path like this:
-
-```yaml
-# Switch to the domain used for Matrix services (`matrix.example.com`),
-# so we won't need to add additional DNS records for Go-NEB.
-matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
-
-# Expose under the /go-neb subpath
-matrix_bot_go_neb_path_prefix: /go-neb
-```
-
-
-## Adjusting DNS records
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
-
-If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
-
-
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_go_neb_enabled: true
@@ -213,10 +190,34 @@ matrix_bot_go_neb_services:
           msg_type: "m.text"  # Must be either `m.text` or `m.notice`
 ```
 
+### Adjusting the Go-NEB URL
+
+By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_bot_go_neb_hostname` and `matrix_bot_go_neb_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Go-NEB.
+matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /buscarron subpath
+matrix_bot_go_neb_path_prefix: /go-neb
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `goneb`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
 ## Installing
 
-After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

docs/configuring-playbook-bot-honoroit.md

@@ -9,15 +9,11 @@ See the project's [documentation](https://github.com/etkecc/honoroit#how-it-look
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_honoroit_enabled: true
 
-# Uncomment and adjust this part if you'd like to use a hostname or path different than the default
-# matrix_bot_honoroit_hostname: "{{ matrix_server_fqn_matrix }}"
-# matrix_bot_honoroit_path_prefix: /honoroit
-
 # Uncomment and adjust this part if you'd like to use a username different than the default
 # matrix_bot_honoroit_login: honoroit
 
@@ -28,10 +24,31 @@ matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT
 matrix_bot_honoroit_roomid: "!yourRoomID:{{ matrix_domain }}"
 ```
 
+### Adjusting the Honoroit URL
+
+By default, this playbook installs Honoroit on the `matrix.` subdomain, at the `/honoroit` path (https://matrix.example.com/honoroit). 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.
+
+By tweaking the `matrix_bot_honoroit_hostname` and `matrix_bot_honoroit_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_bot_honoroit_hostname: honoroit.example.com
+matrix_bot_honoroit_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server.
+
+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
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

docs/configuring-playbook-bot-maubot.md

@@ -10,7 +10,7 @@ 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:
+To enable maubot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_bot_maubot_enabled: true
@@ -27,10 +27,31 @@ matrix_bot_maubot_admins:
 
 You can add multiple admins. The admin accounts are only used to access the maubot administration interface.
 
+### Adjusting the maubot URL
+
+By default, this playbook installs maubot on the `matrix.` subdomain, at the `/_matrix/maubot/` path (https://matrix.example.com/_matrix/maubot/). 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.
+
+By tweaking the `matrix_bot_maubot_hostname` and `matrix_bot_maubot_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_bot_maubot_hostname: maubot.example.com
+matrix_bot_maubot_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the maubot domain to the Matrix server.
+
+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
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`
 
 **Notes**:
 
@@ -38,7 +59,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
 
 ## Usage
 
-You can visit `matrix.example.com/_matrix/maubot/` to manage your available plugins, clients and instances.
+By default, you can visit `matrix.example.com/_matrix/maubot/` to manage your available plugins, clients and instances.
 
 You should start in the following order
 1. **Create one or more clients**: A client is a Matrix account which the bot will use to message. By default, the playbook creates a `bot.maubot` account (as per the configuration above). You only need to [obtain an access token](#obtaining-an-access-token) for it

docs/configuring-playbook-bridge-heisenbridge.md

@@ -8,36 +8,54 @@ See the project's [README](https://github.com/hifi/heisenbridge/blob/master/READ
 
 ## Configuration
 
-Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml).
+To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.example.com/vars.yml`):
 
 ```yaml
 matrix_heisenbridge_enabled: true
 
-# set owner (optional)
+# Setting the owner is optional as the first local user to DM `@heisenbridge:example.com` will be made the owner.
-matrix_heisenbridge_owner: "@you:your-homeserver"
+# If you are not using a local user you must set it as otherwise you can't DM it at all.
+matrix_heisenbridge_owner: "@you:example.com"
 
-# to enable identd on host port 113/TCP (optional)
+# Uncomment to enable identd on host port 113/TCP (optional)
-matrix_heisenbridge_identd_enabled: true
+# matrix_heisenbridge_identd_enabled: true
 ```
 
-By default, Heisenbrdige would be exposed on the Matrix domain (`matrix.example.com`, as specified in `matrix_server_fqn_matrix`) under the `/heisenbridge` path prefix. It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)).
+For a more complete list of variables that you could override, see the [`defaults/main.yml` file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml) of the Heisenbridge Ansible role.
 
-That's it! A registration file is automatically generated during the setup phase.
+### Adjusting the Heisenbridge URL
 
-Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.
+By default, this playbook installs Heisenbridge on the `matrix.` subdomain, at the `/heisenbridge` path (https://matrix.example.com/heisenbridge). It would handle media requests there (see the [release notes for Heisenbridge v1.15.0](https://github.com/hifi/heisenbridge/releases/tag/v1.15.0)).
-If you are not using a local user you must set it as otherwise you can't DM it at all.
+
+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.
+
+By tweaking the `matrix_heisenbridge_hostname` and `matrix_heisenbridge_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_heisenbridge_hostname: heisenbridge.example.com
+matrix_heisenbridge_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the Heisenbridge domain to the Matrix server.
+
+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
 
-After configuring the playbook, 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 [installation](installing.md) command: `just install-all` or `just setup-all`
 
 ## Usage
 
-After the bridge is successfully running just DM `@heisenbridge:your-homeserver` to start setting it up.
+After the bridge is successfully running just DM `@heisenbridge:example.com` to start setting it up. If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
+
 Help is available for all commands with the `-h` switch.
-If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
 
 You can also learn the basics by watching [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
 

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

@@ -4,12 +4,6 @@ The playbook can install and configure [mautrix-wsproxy](https://github.com/maut
 
 See the project's [documentation](https://github.com/mautrix/wsproxy#readme) to learn what it does and why it might be useful to you.
 
-
-## DNS
-
-You need to create a `wsproxy.example.com` DNS record pointing to your Matrix server (a `CNAME` pointing to `matrix.example.com`) to use wsproxy.
-The hostname is configurable via a `matrix_mautrix_wsproxy_hostname` variable.
-
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -26,9 +20,28 @@ matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
 
 Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device.
 
+### Adjusting the wsproxy URL
+
+By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_mautrix_wsproxy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname
+matrix_mautrix_wsproxy_hostname: ws.example.com
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `wsproxy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
 ## Installing
 
-After configuring the playbook, 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 [installation](installing.md) command: `just install-all` or `just setup-all`
 
 ## Usage
 

docs/configuring-playbook-cactus-comments.md

@@ -16,7 +16,7 @@ You can enable whichever component you need (typically both).
 
 ## Configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable Cactus Comments, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 #################
@@ -36,16 +36,34 @@ matrix_cactus_comments_enabled: true
 # When the backend (appservice) is enabled, this is also enabled automatically,
 # but we explicitly enable it here.
 matrix_cactus_comments_client_enabled: true
-
-# Uncomment and adjust this part if you'd like to host the client assets at a different location.
-# These variables are only make used if (`matrix_cactus_comments_client_enabled: true`)
-# matrix_cactus_comments_client_hostname: "{{ matrix_server_fqn_matrix }}"
-# matrix_cactus_comments_client_path_prefix: /cactus-comments
 ```
 
+### Adjusting the Cactus Comments' client URL
+
+By default, this playbook installs Cactus Comments' client on the `matrix.` subdomain, at the `/cactus-comments` path (https://matrix.example.com/cactus-comments). 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.
+
+By tweaking the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix to host the client assets at a different location
+# These variables are used only if (`matrix_cactus_comments_client_enabled: true`)
+matrix_cactus_comments_client_hostname: cactus.example.com
+matrix_cactus_comments_client_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the Cactus Comments' client domain to the Matrix server.
+
+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
 
-After configuring the playbook, 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 [installation](installing.md) command: `just install-all` or `just setup-all`
 
 ## Usage
 
@@ -91,3 +109,5 @@ Make sure to replace `example.com` with your base domain before you include the
 <script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
 <link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">
 ```
+
+**Note**: if the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_path_prefix` variables are tweaked, you would need to adjust the URLs of the assets accordingly.

docs/configuring-playbook-client-cinny.md

@@ -4,18 +4,6 @@ This playbook can install the [cinny](https://github.com/ajbura/cinny) Matrix we
 
 Cinny is a web client focusing primarily on simple, elegant and secure interface. It can be installed alongside or instead of Element.
 
-## DNS
-
-You need to add a DNS record so that Cinny can be accessed.
-
-By default Cinny will use https://cinny.example.com so you will need to create an CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md).
-
-If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
-
-```yaml
-matrix_server_fqn_cinny: "app.{{ matrix_domain }}"
-```
-
 ## Adjusting the playbook configuration
 
 To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -24,6 +12,31 @@ To enable Cinny, add the following configuration to your `inventory/host_vars/ma
 matrix_client_cinny_enabled: true
 ```
 
+### Adjusting the Cinny URL
+
+By default, this playbook installs Cinny on the `cinny.` subdomain (`cinny.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_client_cinny_hostname` and `matrix_client_cinny_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Cinny.
+matrix_client_cinny_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /cinny subpath
+matrix_client_cinny_path_prefix: /cinny
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
 ## Installing
 
-After configuring the playbook, 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 [installation](installing.md) command: `just install-all` or `just setup-all`

docs/configuring-playbook-client-element.md

@@ -5,14 +5,14 @@ By default, this playbook installs the [Element](https://github.com/element-hq/e
 
 ## Disabling Element
 
-If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
+If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_client_element_enabled: false
 ```
 
 
-## Configuring Element settings
+## Adjusting the playbook configuration
 
 The playbook provides some customization variables you could use to change Element's settings.
 
@@ -29,7 +29,7 @@ Alternatively, **if there is no pre-defined variable** for an Element setting yo
 - 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
+### Themes
 
 To change the look of Element, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
 
@@ -38,3 +38,32 @@ Or better yet, you can automatically pull it all themes provided by the [aaronra
 If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
 
 Note that for a custom theme to work well, all Element instances that you use must have the same theme installed.
+
+### Adjusting the Element URL
+
+By default, this playbook installs Element on the `element.` subdomain (`element.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_client_element_hostname` and `matrix_client_element_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Element.
+matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /element subpath
+matrix_client_element_path_prefix: /element
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Element domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `element`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
+## 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`

docs/configuring-playbook-client-hydrogen.md

@@ -4,18 +4,6 @@ This playbook can install the [Hydrogen](https://github.com/element-hq/hydrogen-
 
 Hydrogen is a lightweight web client that supports mobile and legacy web browsers. It can be installed alongside or instead of Element.
 
-## DNS
-
-You need to add a DNS record so that Hydrogen can be accessed.
-
-By default Hydrogen will use https://hydrogen.example.com so you will need to create an CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md).
-
-If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
-
-```yaml
-matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}"
-```
-
 ## Adjusting the playbook configuration
 
 To enable Hydrogen, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -24,6 +12,31 @@ To enable Hydrogen, add the following configuration to your `inventory/host_vars
 matrix_client_hydrogen_enabled: true
 ```
 
+### Adjusting the Hydrogen URL
+
+By default, this playbook installs Hydrogen on the `hydrogen.` subdomain (`hydrogen.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_client_hydrogen_hostname` and `matrix_client_hydrogen_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Hydrogen.
+matrix_client_hydrogen_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /hydrogen subpath
+matrix_client_hydrogen_path_prefix: /hydrogen
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
 ## Installing
 
-After configuring the playbook, 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 [installation](installing.md) command: `just install-all` or `just setup-all`

docs/configuring-playbook-client-schildichat.md

@@ -6,18 +6,6 @@ SchildiChat is a feature-rich messenger for Matrix based on Element with some ex
 
 **WARNING**: SchildiChat Web is based on Element-web, but its releases are lagging behind. As an example (from 2024-02-26), SchildiChat Web is 22 releases behind (it being based on element-web `v1.11.36`, while element-web is now on `v1.11.58`). Element-web frequently suffers from security issues, so running something based on an ancient Element-web release is **dangerous**. Use SchildiChat Web at your own risk!
 
-## DNS
-
-You need to add a DNS record so that SchildiChat can be accessed.
-
-By default SchildiChat will use https://schildichat.example.com so you will need to create an CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md).
-
-If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
-
-```yaml
-matrix_server_fqn_schildichat: "sc.{{ matrix_domain }}"
-```
-
 ## Adjusting the playbook configuration
 
 To enable SchildiChat, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -50,6 +38,31 @@ If you make your own theme, we encourage you to submit it to the **aaronraimist/
 
 Note that for a custom theme to work well, all SchildiChat instances that you use must have the same theme installed.
 
+### Adjusting the SchildiChat URL
+
+By default, this playbook installs SchildiChat on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_client_schildichat_hostname` and `matrix_client_schildichat_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for SchildiChat.
+matrix_client_schildichat_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /schildichat subpath
+matrix_client_schildichat_path_prefix: /schildichat
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the SchildiChat domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
+
 ## Installing
 
-After configuring the playbook, 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 [installation](installing.md) command: `just install-all` or `just setup-all`

docs/configuring-playbook-dimension.md

@@ -7,28 +7,7 @@ If you're just installing Matrix services for the first time, please continue wi
 
 **Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
 
-
+## Adjusting the playbook configuration
-## Decide on a domain and path
-
-By default, Dimension is configured to use its own dedicated domain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
-
-You can override the domain and path like this:
-
-```yaml
-# Switch to another hostname compared to the default (`dimension.{{ matrix_domain }}`)
-matrix_dimension_hostname: "integrations.{{ matrix_domain }}"
-
-```
-
-While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible right now due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain until this issue is solved.
-
-
-## Adjusting DNS records
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
-
-
-## Enable
 
 To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
 
@@ -36,8 +15,7 @@ To enable Dimension, add this to your configuration file (`inventory/host_vars/m
 matrix_dimension_enabled: true
 ```
 
-
+### Define admin users
-## Define admin users
 
 These users can modify the integrations this Dimension supports.
 Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
@@ -50,7 +28,7 @@ matrix_dimension_admins:
 
 The admin interface is accessible within Element by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element by the "Add widgets, bridges, & bots" link in the room information.
 
-## Access token
+### Access token
 
 We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username).
 Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
@@ -68,10 +46,34 @@ matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"
 
 For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens).
 
+### Adjusting the Dimension URL
+
+By default, this playbook installs Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_dimension_hostname` and `matrix_dimension_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Dimension.
+matrix_dimension_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /dimension subpath
+# matrix_dimension_path_prefix: /dimension
+```
+
+**Note**: While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain.
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `dimension`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 ## Installing
 
-After these variables have been set and you have potentially [adjusted your DNS records](#adjusting-dns-records), please run the following command to re-run setup and to restart Dimension:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

docs/configuring-playbook-etherpad.md

@@ -4,12 +4,25 @@
 
 When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
 
+## Adjusting the playbook configuration
 
-## Decide on a domain and path
+To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-By default, Etherpad is configured to use its own dedicated domain (`etherpad.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+```yaml
+etherpad_enabled: true
 
-You can override the domain and path like this:
+# Uncomment and adjust this part if you'd like to enable the admin web UI
+# etherpad_admin_username: YOUR_USERNAME_HERE
+# etherpad_admin_password: YOUR_PASSWORD_HERE
+```
+
+### Adjusting the Etherpad URL
+
+By default, this playbook installs Etherpad on the `etherpad.` subdomain (`etherpad.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `etherpad_hostname` and `etherpad_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 # Switch to the domain used for Matrix services (`matrix.example.com`),
@@ -25,24 +38,13 @@ etherpad_path_prefix: /etherpad
 
 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.
 
+By default, you will need to create a CNAME record for `etherpad`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
 If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
-
-## Adjusting the playbook configuration
-
-[Etherpad](https://etherpad.org) installation is disabled by default. To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-etherpad_enabled: true
-
-# Uncomment and adjust this part if you'd like to enable the admin web UI
-# etherpad_admin_username: YOUR_USERNAME_HERE
-# etherpad_admin_password: YOUR_PASSWORD_HERE
-```
-
 ## Installing
 
-After configuring the playbook, 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 [installation](installing.md) command: `just install-all` or `just setup-all`
 
 ## Usage
 

docs/configuring-playbook-jitsi.md

@@ -9,9 +9,7 @@ The setup done by the playbook is very similar to [docker-jitsi-meet](https://gi
 
 ## Prerequisites
 
-Before installing Jitsi, make sure you've created the `jitsi.example.com` DNS record (unless you've changed `jitsi_hostname`, as described below). See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+You may need to open the following ports to your server:
-
-You may also need to open the following ports to your server:
 
 - `4443/tcp` - RTP media fallback over TCP
 - `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
@@ -19,18 +17,31 @@ You may also need to open the following ports to your server:
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 jitsi_enabled: true
-
-# Uncomment and adjust this part if you'd like to use a hostname different than the default
-# jitsi_hostname: "jitsi.{{ matrix_domain }}"
-
-# Uncomment and possible adjust this part if you'd like to host under a subpath
-# jitsi_path_prefix: /jitsi
 ```
 
+### Adjusting the Jitsi URL
+
+By default, this playbook installs Jitsi on the `jitsi.` subdomain (`jitsi.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `jitsi_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname
+jitsi_hostname: call.example.com
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Jitsi domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `jitsi`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
 ## (Optional) Configure Jitsi authentication and guests mode
 
 By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.
@@ -273,7 +284,7 @@ Besides metadata, this includes the Matrix user_id and possibly the room identif
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@@ -94,7 +94,7 @@ For existing Synapse homeservers:
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_authentication_service_enabled: true
@@ -115,7 +115,7 @@ There are many other configuration options available. Consult the [`defaults/mai
 
 ### Adjusting the Matrix Authentication Service URL
 
-By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (e.g. 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.
+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.
 
 By tweaking the `matrix_authentication_service_hostname` and `matrix_authentication_service_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
 
@@ -229,21 +229,21 @@ matrix_authentication_service_config_upstream_oauth2_providers:
       # By default it uses the `sub` claim as per the OIDC spec,
       # which should fit most use cases.
       subject:
-        #template: "{{ user.sub }}"
+        #template: "{% raw %}{{ user.sub }}{% endraw %}"
       # The localpart is the local part of the user's Matrix ID.
       # For example, on the `example.com` server, if the localpart is `alice`,
       #  the user's Matrix ID will be `@alice:example.com`.
       localpart:
         #action: force
-        #template: "{{ user.preferred_username }}"
+        #template: "{% raw %}{{ user.preferred_username }}{% endraw %}"
       # The display name is the user's display name.
       displayname:
         #action: suggest
-        #template: "{{ user.name }}"
+        #template: "{% raw %}{{ user.name }}{% endraw %}"
       # An email address to import.
       email:
         #action: suggest
-        #template: "{{ user.email }}"
+        #template: "{% raw %}{{ user.email }}{% endraw %}"
         # Whether the email address must be marked as verified.
         # Possible values are:
         #  - `import`: mark the email address as verified if the upstream provider
@@ -259,10 +259,20 @@ matrix_authentication_service_config_upstream_oauth2_providers:
 
 ⚠ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2.
 
+⚠ When [migrating an existing homeserver](#migrating-an-existing-homeserver-to-matrix-authentication-service) which contains OIDC-sourced users, you will need to [Configure upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas).
+
+
+## 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.
+
+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), 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 [installation](installing.md) command: `just install-all`
 
 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 homeserver to Matrix Authentication Service](#migrating-an-existing-homeserver-to-matrix-authentication-service) guide.
 
@@ -287,6 +297,8 @@ The installation + migration steps are like this:
 
   - Various [compatibility layer URLs](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) are not yet installed. New login sessions will still be forwarded to the homeserver, which is capable of completing them.
 
+  - The `matrix-user-creator` role would be suppressed, so that it doesn't automatically attempt to create users (for bots, etc.) in the MAS database. These user accounts likely already exist in Synapse's user database and could be migrated over (via syn2mas, as per the steps below), so creating them in the MAS database would have been unnecessary and potentially problematic (conflicts during the syn2mas migration).
+
 3. Consider taking a full [backup of your Postgres database](./maintenance-postgres.md#backing-up-postgresql). This is done just in case. The **syn2mas migration tool does not delete any data**, so it should be possible to revert to your previous setup by merely disabling MAS and re-running the playbook (no need to restore a Postgres backup). However, do note that as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break.
 
 4. [Migrate your data from Synapse to Matrix Authentication Service using syn2mas](#migrate-your-data-from-synapse-to-matrix-authentication-service-using-syn2mas)
@@ -308,9 +320,40 @@ We **don't** ask you to [run the `syn2mas` migration advisor command](https://el
 
 You can invoke the `syn2mas` tool via the playbook by running the playbook's `matrix-authentication-service-syn2mas` tag. We recommend first doing a [dry-run](#performing-a-syn2mas-dry-run) and then a [real migration](#performing-a-real-syn2mas-migration).
 
+#### Configuring syn2mas
+
+If you're using [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to [Configuring upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas).
+
+If you only have local (non-OIDC) users in your Synapse database, you can likely run `syn2mas` as-is (without doing additional configuration changes).
+
+When you're done with potentially configuring `syn2mas`, proceed to doing a [dry-run](#performing-a-syn2mas-dry-run) and then a [real migration](#performing-a-real-syn2mas-migration).
+
+##### Configuring upstream OIDC provider mapping for syn2mas
+
+If you have existing OIDC users in your Synapse user database (which will be the case if when using [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)), you may need to pass an additional `--upstreamProviderMapping` argument to the `syn2mas` tool to tell it which provider (on the Synapse side) maps to which other provider on the MAS side.
+
+If you don't do this, `syn2mas` would report errors like this one:
+
+> [FATAL] migrate - [Failed to import external id 4264b0f0-4f11-4ddd-aedb-b500e4d07c25 with oidc-keycloak for user @user:example.com: Error: Unknown upstream provider oidc-keycloak]
+
+Below is an example situation and a guide for how to solve it.
+
+If in `matrix_synapse_oidc_providers` your provider `idp_id` is (was) named `keycloak`, in the Synapse database users would be associated with the `oidc-keycloak` provider (note the `oidc-` prefix that was added automatically by Synapse to your `idp_id` value).
+
+The same OIDC provider may have an `id` of `01HFVBY12TMNTYTBV8W921M5FA` on the MAS side, as defined in `matrix_authentication_service_config_upstream_oauth2_providers` (see the [Upstream OAuth2 configuration](#upstream-oauth2-configuration) section above).
+
+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
+# 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:
+  - "--upstreamProviderMapping oidc-keycloak:01HFVBY12TMNTYTBV8W921M5FA"
+```
+
 #### Performing a syn2mas dry-run
 
-We recommend doing a [dry-run](https://en.wikipedia.org/wiki/Dry_run_(testing)) first to verify that everything will work out as expected.
+Having [configured syn2mas](#configuring-syn2mas), we recommend doing a [dry-run](https://en.wikipedia.org/wiki/Dry_run_(testing)) first to verify that everything will work out as expected.
 
 A dry-run would not cause downtime, because it avoids stopping Synapse.
 
@@ -324,13 +367,17 @@ Observe the command output (especially the last line of the the syn2mas output).
 
 #### Performing a real syn2mas migration
 
-Before performing a real migration:
+Before performing a real migration make sure:
 
-- make sure you've familiarized yourself with the [expectations](#expectations)
+- you've familiarized yourself with the [expectations](#expectations)
 
-- make sure you've performed a Postgres backup, just in case
+- you've performed a Postgres backup, just in case
 
-- make sure you're aware of the irreversibility of the migration process without disruption after users have created new login sessions via the new MAS setup
+- you're aware of the irreversibility of the migration process without disruption after users have created new login sessions via the new MAS setup
+
+- you've [configured syn2mas](#configuring-syn2mas), especially if you've used [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)
+
+- you've performed a [syn2mas dry-run](#performing-a-syn2mas-dry-run) and don't see any issues in its output
 
 To perform a real migration, run the `matrix-authentication-service-syn2mas` tag **without** the `matrix_authentication_service_syn2mas_dry_run` variable:
 

docs/configuring-playbook-matrix-registration.md

@@ -19,7 +19,7 @@ Use matrix-registration to **create unique registration links**, which people ca
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_registration_enabled: true
@@ -28,9 +28,31 @@ matrix_registration_enabled: true
 matrix_registration_admin_secret: "ENTER_SOME_SECRET_HERE"
 ```
 
+### Adjusting the matrix-registration URL
+
+By default, this playbook installs the matrix-registration on the `matrix.` subdomain, at the `/matrix-registration` path (https://matrix.example.com/matrix-registration). 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.
+
+By tweaking the `matrix_registration_hostname` and `matrix_registration_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_registration_hostname: registration.example.com
+matrix_registration_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-registration domain to the Matrix server.
+
+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
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

docs/configuring-playbook-ntfy.md

@@ -11,15 +11,12 @@ This role is intended to support UnifiedPush notifications for use with the Matr
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 # Enabling it is the only required setting
 ntfy_enabled: true
 
-# Uncomment and adjust this part if you'd like to use a hostname different than the default
-# matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
-
 # Uncomment to enable the ntfy web app (disabled by default)
 # ntfy_web_root: app  # defaults to "disable"
 
@@ -32,12 +29,28 @@ For a more complete list of variables that you could override, see the [`default
 
 For a complete list of ntfy config options that you could put in `ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
 
+### Adjusting the ntfy URL
+
+By default, this playbook installs ntfy on the `ntfy.` subdomain (`ntfy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `ntfy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname
+ntfy_hostname: push.example.com
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain, **you may need to adjust your DNS** records to point the ntfy domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `ntfy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
 ## Installing
 
-Don't forget to add `ntfy.example.com` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
-
-After configuring the playbook, run the [installation](installing.md) command:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

docs/configuring-playbook-prometheus-grafana.md

@@ -1,10 +1,10 @@
 # Enabling metrics and graphs for your Matrix server (optional)
 
-It can be useful to have some (visual) insight into the performance of your homeserver.
+The playbook can install [Grafana](https://grafana.com/) with [Prometheus](https://prometheus.io/) and configure performance metrics of your homeserver with graphs for you.
 
-You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
+## Adjusting the playbook configuration
 
-Remember to add `stats.example.com` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
+To enable Grafana and/or Prometheus, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 prometheus_enabled: true
@@ -30,10 +30,32 @@ grafana_default_admin_user: "some_username_chosen_by_you"
 grafana_default_admin_password: "some_strong_password_chosen_by_you"
 ```
 
-By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.example.com`.
-
 The retention policy of Prometheus metrics is [15 days by default](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects). Older data gets deleted automatically.
 
+### Adjusting the Grafana URL
+
+By default, this playbook installs Grafana web user-interface on the `stats.` subdomain (`stats.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `grafana_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname
+grafana_hostname: grafana.example.com
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain, **you may need to adjust your DNS** records to point the Grafana domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `stats`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+**Note**: It is possible to install Prometheus without installing Grafana. This case it is not required to create the CNAME record.
+
+## 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`
 
 ## What does it do?
 

docs/configuring-playbook-rageshake.md

@@ -4,33 +4,9 @@ The playbook can install and configure the [rageshake](https://github.com/matrix
 
 This is useful if you're developing your own applications and would like to collect bug reports for them.
 
+## Adjusting the playbook configuration
 
-## Decide on a domain and path
+To enable Rageshake, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-By default, Rageshake is configured to use its own dedicated domain (`rageshake.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
-
-You can override the domain and path like this:
-
-```yaml
-# Switch to the domain used for Matrix services (`matrix.example.com`),
-# so we won't need to add additional DNS records for Rageshake.
-matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}"
-
-# Expose under the /rageshake subpath
-matrix_rageshake_path_prefix: /rageshake
-```
-
-
-## Adjusting DNS records
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Rageshake domain to the Matrix server.
-
-If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
-
-
-## Enabling the Rageshake service
-
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_rageshake_enabled: true
@@ -48,10 +24,34 @@ matrix_rageshake_configuration_extension_yaml: |
      my-app: octocat/HelloWorld
 ```
 
+### Adjusting the Rageshake URL
+
+By default, this playbook installs Rageshake on the `rageshake.` subdomain (`rageshake.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_rageshake_hostname` and `matrix_rageshake_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Rageshake.
+matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /rageshake subpath
+matrix_rageshake_path_prefix: /rageshake
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Rageshake domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `rageshake`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
 ## Installing
 
-After configuring the playbook, run the [installation](installing.md) command:
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@@ -12,32 +12,39 @@ Element X Android is [available on the Github Releases page](https://github.com/
 
 **Note**: The sliding-sync proxy is **not required** when using the **Conduit homeserver**. Starting from version `0.6.0` Conduit has native support for some sliding sync features. If there are issues with the native implementation, you might have a better experience when enabling the sliding-sync proxy anyway.
 
-## Decide on a domain and path
-
-By default, the Sliding Sync proxy is configured to be served on the Matrix domain (`matrix.example.com`, controlled by `matrix_server_fqn_matrix`), under the `/sliding-sync` path.
-
-This makes it easy to set it up, **without** having to [adjust your DNS records](#adjusting-dns-records).
-
-If you'd like to run the Sliding Sync proxy on another hostname or path, use the `matrix_sliding_sync_hostname` and `matrix_sliding_sync_path_prefix` variables.
-
-
-## Adjusting DNS records
-
-If you've changed the default hostname, **you may need to adjust your DNS** records.
-
-
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable Sliding Sync proxy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_sliding_sync_enabled: true
 ```
 
+### Adjusting the Sliding Sync proxy URL
+
+By default, this playbook installs the Sliding Sync proxy on the `matrix.` subdomain, at the `/sliding-sync` path (https://matrix.example.com/sliding-sync). 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.
+
+By tweaking the `matrix_sliding_sync_hostname` and `matrix_sliding_sync_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_sliding_sync_hostname: ss.example.com
+matrix_sliding_sync_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server.
+
+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
 
-After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again: `just install-all`.
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`.
 
 ### External databases
 

docs/configuring-playbook-sygnal.md

@@ -10,33 +10,9 @@ See the project's [documentation](https://github.com/matrix-org/sygnal) to learn
 
 This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves.
 
-
-## Decide on a domain and path
-
-By default, Sygnal is configured to use its own dedicated domain (`sygnal.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
-
-You can override the domain and path like this:
-
-```yaml
-# Switch to the domain used for Matrix services (`matrix.example.com`),
-# so we won't need to add additional DNS records for Sygnal.
-matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}"
-
-# Expose under the /sygnal subpath
-matrix_sygnal_path_prefix: /sygnal
-```
-
-
-## Adjusting DNS records
-
-Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Sygnal domain to the Matrix server.
-
-If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
-
-
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+To enable Sygnal, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_sygnal_enabled: true
@@ -75,6 +51,30 @@ To do that, the above example configuration:
 
 - references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container)
 
+### Adjusting the Sygnal URL
+
+By default, this playbook installs Sygnal on the `sygnal.` subdomain (`sygnal.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
+
+By tweaking the `matrix_sygnal_hostname` and `matrix_sygnal_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Switch to the domain used for Matrix services (`matrix.example.com`),
+# so we won't need to add additional DNS records for Sygnal.
+matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}"
+
+# Expose under the /sygnal subpath
+matrix_sygnal_path_prefix: /sygnal
+```
+
+## Adjusting DNS records
+
+Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Sygnal domain to the Matrix server.
+
+By default, you will need to create a CNAME record for `sygnal`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
+
+If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
 ## Installing
 

docs/configuring-playbook-synapse-admin.md

@@ -9,7 +9,7 @@ See the project's [documentation](https://github.com/etkecc/synapse-admin) to le
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_synapse_admin_enabled: true
@@ -24,11 +24,31 @@ By default, synapse-admin installation will be [restricted to only work with one
 
 ⚠ **Warning**: If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all.
 
+### Adjusting the Synapse Admin URL
+
+By default, this playbook installs Synapse Admin on the `matrix.` subdomain, at the `/synapse-admin` path (https://matrix.example.com/synapse-admin). 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.
+
+By tweaking the `matrix_synapse_admin_hostname` and `matrix_synapse_admin_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_synapse_admin_hostname: admin.example.com
+matrix_synapse_admin_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the Synapse Admin domain to the Matrix server.
+
+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
 
-After configuring the playbook, run the [installation](installing.md) command: `just install-all`
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
-
 
 ## Usage
 

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

@@ -11,9 +11,9 @@ Enabling this service will automatically:
 - re-configure [Prometheus](./configuring-playbook-prometheus-grafana.md) (if Prometheus is enabled), to periodically scrape metrics from synapse-usage-exporter
 - add a new [Grafana](./configuring-playbook-prometheus-grafana.md) dashboard (if Grafana is enabled) containing Synapse usage statistics
 
-## Quickstart
+## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file and [re-run the installation process](./installing.md) for the playbook:
+To enable synapse-usage-exporter, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_synapse_usage_exporter_enabled: true
@@ -24,3 +24,30 @@ matrix_synapse_usage_exporter_enabled: true
 # You can adjust the hostname and path via `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix`.
 # matrix_synapse_usage_exporter_proxying_enabled: true
 ```
+
+### Adjusting the synapse-usage-exporter URL
+
+By default, this playbook installs synapse-usage-exporter on the `matrix.` subdomain, at the `/report-usage-stats/push` path (https://matrix.example.com/report-usage-stats/push). 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.
+
+By tweaking the `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+# These variables are used only if (`matrix_synapse_usage_exporter_proxying_enabled: true`)
+matrix_synapse_usage_exporter_hostname: sue.example.com
+matrix_synapse_usage_exporter_path_prefix: /
+```
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the synapse-usage-exporter domain to the Matrix server.
+
+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
+
+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`

roles/custom/matrix-authentication-service/defaults/main.yml

@@ -567,6 +567,13 @@ matrix_authentication_service_syn2mas_container_network: "{{ matrix_authenticati
 # Path to Synapse's homeserver.yaml configuration file.
 matrix_authentication_service_syn2mas_synapse_homeserver_config_path: ""
 
+# Additional arguments passed to the syn2mas process.
+#
+# Example:
+# matrix_authentication_service_syn2mas_process_extra_arguments:
+#   - "--upstreamProviderMapping oidc-keycloak:01H8PKNWKKRPCBW4YGH1RWV279"
+matrix_authentication_service_syn2mas_process_extra_arguments: []
+
 ########################################################################################
 #                                                                                      #
 # /syn2mas configuration                                                               #

roles/custom/matrix-user-creator/tasks/setup.yml

@@ -31,7 +31,7 @@
       # Suppress logging to avoid dumping the credentials to the shell
       no_log: true
 
-- when: matrix_authentication_service_enabled | bool
+- when: matrix_authentication_service_enabled and not matrix_authentication_service_migration_in_progress
   block:
     - name: Ensure Matrix Authentication Service is started before creating Matrix users
       ansible.builtin.service: