Update documentation for components which do not require subdomain settings by default

This adopts the structure of docs/configuring-playbook-matrix-authentication-service.md which was recently created.

- …
- Adjusting the playbook configuration
  - …
  - Adjusting the (service name here) URL
  - …
- Adjusting DNS records
- Installing
- …

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

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
 

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,6 +24,27 @@ 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
 

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,6 +27,27 @@ 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
 
@@ -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,26 +8,44 @@ 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).
-
-At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.example.com/vars.yml`):
+To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_heisenbridge_enabled: true
 
-# set owner (optional)
+# Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.
+# 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:your-homeserver"
 
-# to enable identd on host port 113/TCP (optional)
-matrix_heisenbridge_identd_enabled: true
+# Uncomment to enable identd on host port 113/TCP (optional)
+# 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.
+
+### Adjusting the Heisenbridge URL
+
+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)).
+
+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.
 
-That's it! A registration file is automatically generated during the setup phase.
+See [Configuring DNS](configuring-dns.md) for details about DNS changes.
 
-Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.
-If you are not using a local user you must set it as otherwise you can't DM it at all.
+If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
 
 ## Installing
 

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,13 +36,31 @@ 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
+```
+
+### 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.
 
-# 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
+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`
@@ -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-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.
 
@@ -259,6 +259,13 @@ 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.
 
+## 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
 

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,6 +28,28 @@ 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:

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

@@ -12,28 +12,35 @@ 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
+## Adjusting the playbook configuration
 
-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.
+To enable Sliding Sync proxy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-This makes it easy to set it up, **without** having to [adjust your DNS records](#adjusting-dns-records).
+```yaml
+matrix_sliding_sync_enabled: true
+```
 
-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 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.
 
-## Adjusting DNS records
+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.
 
-If you've changed the default hostname, **you may need to adjust your DNS** records.
+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 the playbook configuration
+## Adjusting DNS records
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server.
 
-```yaml
-matrix_sliding_sync_enabled: true
-```
+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
 

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,6 +24,27 @@ 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
 

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, run the [installation](installing.md) command: `just install-all` or `just setup-all`