Update documentation for components which 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-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,6 +29,30 @@ 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
 

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,6 +190,30 @@ 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
 

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,6 +20,25 @@ 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: wsproxy.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`

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`

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, 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`

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`

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,6 +46,30 @@ 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
 

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,21 +38,10 @@ 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`

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: jitsi.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.

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,11 +29,27 @@ 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: ntfy.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, run the [installation](installing.md) command:
 
 ```

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: stats.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, 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,6 +24,30 @@ 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
 

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