From 819f0c66a2d88dd969543e070304c55bcbb93a78 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 13 Jan 2025 17:27:54 +0900 Subject: [PATCH] Update docs for DNS settings of the services which do not need its CNAME record by default - matrix-alertmanager-receiver - Honoroit - maubot - Heisenbridge - Cactus Comments - Matrix Authentication Service - matrix-registration - Sliding Sync proxy - Synapse Admin - synapse-usage-exporter Signed-off-by: Suguru Hirahara --- ...figuring-playbook-alertmanager-receiver.md | 18 +++++++-------- docs/configuring-playbook-bot-honoroit.md | 18 +++++++-------- docs/configuring-playbook-bot-maubot.md | 18 +++++++-------- ...onfiguring-playbook-bridge-heisenbridge.md | 22 ++++++++----------- docs/configuring-playbook-cactus-comments.md | 18 +++++++-------- ...-playbook-matrix-authentication-service.md | 22 +++++++++---------- ...onfiguring-playbook-matrix-registration.md | 18 +++++++-------- ...configuring-playbook-sliding-sync-proxy.md | 18 +++++++-------- docs/configuring-playbook-synapse-admin.md | 18 +++++++-------- ...iguring-playbook-synapse-usage-exporter.md | 18 +++++++-------- 10 files changed, 92 insertions(+), 96 deletions(-) diff --git a/docs/configuring-playbook-alertmanager-receiver.md b/docs/configuring-playbook-alertmanager-receiver.md index 7a066c293..8a0b8776b 100644 --- a/docs/configuring-playbook-alertmanager-receiver.md +++ b/docs/configuring-playbook-alertmanager-receiver.md @@ -36,6 +36,12 @@ For each new room you would like the bot to deliver alerts to, invite the bot to Then, log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account, and log out. +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-matrix-alertmanager-receiver-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token). @@ -61,9 +67,7 @@ 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. +### Adjusting the matrix-alertmanager-receiver URL (optional) 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. @@ -75,13 +79,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the matrix-alertmanager-receiver domain (`alertmanager.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-bot-honoroit.md b/docs/configuring-playbook-bot-honoroit.md index eed5d70db..d89aa7152 100644 --- a/docs/configuring-playbook-bot-honoroit.md +++ b/docs/configuring-playbook-bot-honoroit.md @@ -6,6 +6,12 @@ It's a bot you can use to setup **your own helpdesk on matrix** See the project's [documentation](https://github.com/etkecc/honoroit/blob/main/README.md) to learn what it does and why it might be useful to you. +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-honoroit-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -23,9 +29,7 @@ matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT matrix_bot_honoroit_roomid: "!qporfwt:{{ 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. +### Adjusting the Honoroit URL (optional) 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. @@ -37,13 +41,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the Honoroit domain (`honoroit.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index a82f5c66e..0436de588 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/docs/configuring-playbook-bot-maubot.md @@ -6,6 +6,12 @@ After setting up maubot, you can use the web management interface to make it do See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) to learn what it does and why it might be useful to you. +## Adjusting DNS records (optional) + +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 you wish to adjust it, see the section [below](#adjusting-the-maubot-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -25,9 +31,7 @@ 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. +### Adjusting the maubot URL (optional) 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. @@ -39,13 +43,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the maubot domain (`maubot.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Customizing the maubot container image diff --git a/docs/configuring-playbook-bridge-heisenbridge.md b/docs/configuring-playbook-bridge-heisenbridge.md index 5e1ae4c27..a464a60f3 100644 --- a/docs/configuring-playbook-bridge-heisenbridge.md +++ b/docs/configuring-playbook-bridge-heisenbridge.md @@ -6,6 +6,12 @@ The playbook can install and configure [Heisenbridge](https://github.com/hifi/he See the project's [documentation](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I). +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-heisenbridge-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -21,13 +27,7 @@ matrix_heisenbridge_owner: "@alice:{{ matrix_domain }}" # matrix_heisenbridge_identd_enabled: true ``` -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. +### Adjusting the Heisenbridge URL (optional) 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. @@ -39,13 +39,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the Heisenbridge domain (`heisenbridge.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index a1721eb09..ee5213be9 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -14,6 +14,12 @@ The playbook contains 2 roles for configuring different pieces of the Cactus Com You can enable whichever component you need (typically both). +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-cactus-comments-client-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable Cactus Comments, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -38,9 +44,7 @@ matrix_cactus_comments_enabled: true 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. +### Adjusting the Cactus Comments' client URL (optional) 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. @@ -53,13 +57,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the Cactus Comments' client domain (`cactus.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-matrix-authentication-service.md b/docs/configuring-playbook-matrix-authentication-service.md index 45aa1557a..eb9ea08b9 100644 --- a/docs/configuring-playbook-matrix-authentication-service.md +++ b/docs/configuring-playbook-matrix-authentication-service.md @@ -97,6 +97,12 @@ For existing Synapse homeservers: - then follow the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) instructions to perform the installation and migration +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-matrix-authentication-service-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -117,9 +123,7 @@ In the sub-sections that follow, we'll cover some additional configuration optio There are many other configuration options available. Consult the [`defaults/main.yml` file](../roles/custom/matrix-authentication-service/defaults/main.yml) in the [matrix-authentication-service role](../roles/custom/matrix-authentication-service/) to discover them. -### Adjusting the Matrix Authentication Service URL - -By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (https://matrix.example.com/auth). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section. +### Adjusting the Matrix Authentication Service URL (optional) 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. @@ -131,6 +135,10 @@ matrix_authentication_service_hostname: auth.example.com matrix_authentication_service_path_prefix: / ``` +If you've changed the default hostname, you may need to create a CNAME record for the Matrix Authentication Service domain (`auth.example.com`), which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ### Marking an existing homeserver for migration The [configuration above](#adjusting-the-playbook-configuration) instructs existing users wishing to migrate to add `matrix_authentication_service_migration_in_progress: true` to their configuration. @@ -268,14 +276,6 @@ matrix_authentication_service_config_upstream_oauth2_providers: - go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process - remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration -## Adjusting DNS records - -If you've changed the default hostname, **you may need to adjust your DNS** records to point the Matrix Authentication Service domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. - ## Installing Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-matrix-registration.md b/docs/configuring-playbook-matrix-registration.md index 218a32754..fb5e04b31 100644 --- a/docs/configuring-playbook-matrix-registration.md +++ b/docs/configuring-playbook-matrix-registration.md @@ -14,6 +14,12 @@ Use matrix-registration to **create unique registration links**, which people ca - **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.example.com/matrix-registration` +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-matrix-registration-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -25,9 +31,7 @@ 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. +### Adjusting the matrix-registration URL (optional) 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. @@ -39,13 +43,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the matrix-registration domain (`registration.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-sliding-sync-proxy.md b/docs/configuring-playbook-sliding-sync-proxy.md index e9f936f72..406dc6196 100644 --- a/docs/configuring-playbook-sliding-sync-proxy.md +++ b/docs/configuring-playbook-sliding-sync-proxy.md @@ -6,6 +6,12 @@ The playbook can install and configure [sliding-sync](https://github.com/matrix- Sliding Sync is an implementation of [MSC3575](https://github.com/matrix-org/matrix-spec-proposals/blob/kegan/sync-v3/proposals/3575-sync.md) and a prerequisite for running Element X clients ([Element X iOS](https://github.com/element-hq/element-x-ios) and [Element X Android](https://github.com/element-hq/element-x-android)). See the project's [documentation](https://github.com/matrix-org/sliding-sync) to learn more. +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-sliding-sync-proxy-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable Sliding Sync proxy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -14,9 +20,7 @@ To enable Sliding Sync proxy, add the following configuration to your `inventory 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. +### Adjusting the Sliding Sync proxy URL (optional) 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. @@ -28,13 +32,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the Sliding Sync proxy domain (`ss.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md index c3811521f..22635d012 100644 --- a/docs/configuring-playbook-synapse-admin.md +++ b/docs/configuring-playbook-synapse-admin.md @@ -6,6 +6,12 @@ synapse-admin is a web UI tool you can use to **administrate users, rooms, media 💡 **Note**: the latest version of synapse-admin is hosted by [etke.cc](https://etke.cc/) at [admin.etke.cc](https://admin.etke.cc/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting. +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-synapse-admin-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -23,9 +29,7 @@ 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. +### Adjusting the Synapse Admin URL (optional) 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. @@ -37,13 +41,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the Synapse Admin domain (`admin.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index 81589d9e2..e07fc6d0d 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/docs/configuring-playbook-synapse-usage-exporter.md @@ -11,6 +11,12 @@ 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 +## Adjusting DNS records (optional) + +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. + +If you wish to adjust it, see the section [below](#adjusting-the-synapse-usage-exporter-url-optional) for details about DNS configuration. + ## Adjusting the playbook configuration To enable synapse-usage-exporter, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -25,9 +31,7 @@ matrix_synapse_usage_exporter_enabled: true # 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. +### Adjusting the synapse-usage-exporter URL (optional) 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. @@ -40,13 +44,9 @@ 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 changed the default hostname, you may need to create a CNAME record for the synapse-usage-exporter domain (`sue.example.com`), which targets `matrix.example.com`. -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing