From a4710173d4cc5b8113178ad1b17d702e4e67b041 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 13 Jan 2025 15:54:24 +0900 Subject: [PATCH] Update docs for DNS settings of the services which need its CNAME record by default - Buscarron - Go-NEB; fix a line on the instruction as well - wsproxy - Cinny - Element Web - Hydrogen - SchildiChat Web - Dimension - Etherpad - Jitsi - ntfy - Grafana - rageshake - Sygnal Signed-off-by: Suguru Hirahara --- docs/configuring-dns.md | 13 ----------- docs/configuring-playbook-bot-buscarron.md | 16 +++++++------- docs/configuring-playbook-bot-go-neb.md | 18 +++++++-------- ...iguring-playbook-bridge-mautrix-wsproxy.md | 16 +++++++------- docs/configuring-playbook-client-cinny.md | 20 ++++++++--------- ...configuring-playbook-client-element-web.md | 22 +++++++++---------- docs/configuring-playbook-client-hydrogen.md | 16 +++++++------- ...iguring-playbook-client-schildichat-web.md | 22 +++++++++---------- docs/configuring-playbook-dimension.md | 18 ++++++++------- docs/configuring-playbook-etherpad.md | 16 +++++++------- docs/configuring-playbook-jitsi.md | 6 +++-- docs/configuring-playbook-ntfy.md | 16 +++++++------- ...configuring-playbook-prometheus-grafana.md | 16 +++++++------- docs/configuring-playbook-rageshake.md | 16 +++++++------- docs/configuring-playbook-sygnal.md | 16 +++++++------- 15 files changed, 118 insertions(+), 129 deletions(-) diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 4d66469e3..6e477efa8 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -44,19 +44,6 @@ For other services which may need subdomain settings, see the table below and co | Used by component | Type | Host | Priority | Weight | Port | Target | | -------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | -----------------------------------| -| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.example.com` | -| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.example.com` | -| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.example.com` | -| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.example.com` | -| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.example.com` | -| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.example.com` | -| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.example.com` | -| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.example.com` | -| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.example.com` | -| [SchildiChat Web](configuring-playbook-client-schildichat-web.md) client | CNAME | `schildichat` | - | - | - | `matrix.example.com` | -| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge | CNAME | `wsproxy` | - | - | - | `matrix.example.com` | -| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.example.com` | -| [rageshake](configuring-playbook-rageshake.md) bug report server | CNAME | `rageshake` | - | - | - | `matrix.example.com` | | [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.example.com` | | [Postmoogle](configuring-playbook-bridge-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.example.com` | | [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4:matrix-server-IP -all` | diff --git a/docs/configuring-playbook-bot-buscarron.md b/docs/configuring-playbook-bot-buscarron.md index 089fd35da..c7ed4f69d 100644 --- a/docs/configuring-playbook-bot-buscarron.md +++ b/docs/configuring-playbook-bot-buscarron.md @@ -4,6 +4,12 @@ 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. +## Adjusting DNS records + +By default, this playbook installs Buscarron on the `buscarron.` subdomain (`buscarron.example.com`) and requires you to create a CNAME record for `buscarron`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -29,9 +35,7 @@ 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). +### Adjusting the Buscarron URL (optional) 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. @@ -46,11 +50,7 @@ matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}" 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. +After changing the domain, **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. diff --git a/docs/configuring-playbook-bot-go-neb.md b/docs/configuring-playbook-bot-go-neb.md index 01f86828e..cd6e875cd 100644 --- a/docs/configuring-playbook-bot-go-neb.md +++ b/docs/configuring-playbook-bot-go-neb.md @@ -28,6 +28,12 @@ The bot requires an access token to be able to connect to your homeserver. Refer ⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. +## Adjusting DNS records + +By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to create a CNAME record for `goneb`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_GONEB_HERE` and `ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE` with the ones created [above](#obtain-an-access-token). @@ -194,9 +200,7 @@ 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). +### Adjusting the Go-NEB URL (optional) 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. @@ -207,15 +211,11 @@ Example additional configuration for your `vars.yml` file: # 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 +# 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. - -By default, you will need to create a CNAME record for `goneb`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. +After changing the domain, **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. diff --git a/docs/configuring-playbook-bridge-mautrix-wsproxy.md b/docs/configuring-playbook-bridge-mautrix-wsproxy.md index f9a91af5c..bdc1f3bb2 100644 --- a/docs/configuring-playbook-bridge-mautrix-wsproxy.md +++ b/docs/configuring-playbook-bridge-mautrix-wsproxy.md @@ -6,6 +6,12 @@ The playbook can install and configure [mautrix-wsproxy](https://github.com/maut See the project's [documentation](https://github.com/mautrix/wsproxy/blob/master/README.md) to learn what it does and why it might be useful to you. +## Adjusting DNS records + +By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to create a CNAME record for `wsproxy`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -28,9 +34,7 @@ There are some additional things you may wish to configure about the bridge. See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc. -### 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). +### Adjusting the wsproxy URL (optional) By tweaking the `matrix_mautrix_wsproxy_hostname` variable, you can easily make the service available at a **different hostname** than the default one. @@ -41,11 +45,7 @@ Example additional configuration for your `vars.yml` file: matrix_mautrix_wsproxy_hostname: ws.example.com ``` -## Adjusting DNS records - -Once you've decided on the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server. - -By default, you will need to create a CNAME record for `wsproxy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. +After changing the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server. ## Installing diff --git a/docs/configuring-playbook-client-cinny.md b/docs/configuring-playbook-client-cinny.md index 0bbf71222..63f47c3c4 100644 --- a/docs/configuring-playbook-client-cinny.md +++ b/docs/configuring-playbook-client-cinny.md @@ -8,6 +8,12 @@ Cinny is a web client focusing primarily on simple, elegant and secure interface - [app.cinny.in](https://app.cinny.in), hosted by the [Cinny](https://cinny.in/) developers +## Adjusting DNS records + +By default, this playbook installs Cinny on the `cinny.` subdomain (`cinny.example.com`) and requires you to create a CNAME record for `cinny`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -16,14 +22,10 @@ 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). +### Adjusting the Cinny URL (optional) By tweaking the `matrix_client_cinny_hostname` variable, you can easily make the service available at a **different hostname** than the default one. -While a `matrix_client_cinny_path_prefix` variable exists for tweaking the path-prefix, it's [not supported anymore](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path. - Example additional configuration for your `vars.yml` file: ```yaml @@ -31,13 +33,9 @@ Example additional configuration for your `vars.yml` file: matrix_client_cinny_hostname: "app.{{ matrix_domain }}" ``` -## Adjusting DNS records - -Once you've decided on the domain, **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. +After changing the domain, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server. -If you've adjusted `matrix_client_cinny_hostname`, you will need to adjust your DNS configuration accordingly. +**Note**: while a `matrix_client_cinny_path_prefix` variable exists for tweaking the path-prefix, it's [not supported anymore](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path. ## Installing diff --git a/docs/configuring-playbook-client-element-web.md b/docs/configuring-playbook-client-element-web.md index d88707b7d..4d832752c 100644 --- a/docs/configuring-playbook-client-element-web.md +++ b/docs/configuring-playbook-client-element-web.md @@ -9,6 +9,12 @@ If you'd like to stop the playbook installing the client, see the section [below - [app.element.io](https://app.element.io/), hosted by [Element](https://element.io/) - [app.etke.cc](https://app.etke.cc/), hosted by [etke.cc](https://etke.cc/) +## Adjusting DNS records + +By default, this playbook installs Element Web on the `element.` subdomain (`element.example.com`) and requires you to create a CNAME record for `element`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration ### Themes @@ -40,9 +46,7 @@ If you define your own themes with it and set `matrix_client_element_themes_enab 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. -### Adjusting the Element Web URL - -By default, this playbook installs Element Web on the `element.` subdomain (`element.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). +### Adjusting the Element Web URL (optional) 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. @@ -57,6 +61,10 @@ matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}" matrix_client_element_path_prefix: /element ``` +After changing the domain, **you may need to adjust your DNS** records to point the Element domain to the Matrix server. + +If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration. + ### Extending the configuration There are some additional things you may wish to configure about the component. @@ -84,14 +92,6 @@ matrix_client_element_configuration_extension_json: | } ``` -## Adjusting DNS records - -Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Element Web 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. - ## Disabling Element Web If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `vars.yml` file: diff --git a/docs/configuring-playbook-client-hydrogen.md b/docs/configuring-playbook-client-hydrogen.md index 3166005ae..a2926956d 100644 --- a/docs/configuring-playbook-client-hydrogen.md +++ b/docs/configuring-playbook-client-hydrogen.md @@ -4,6 +4,12 @@ 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 Web. +## Adjusting DNS records + +By default, this playbook installs Hydrogen on the `hydrogen.` subdomain (`hydrogen.example.com`) and requires you to create a CNAME record for `hydrogen`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable Hydrogen, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -12,9 +18,7 @@ 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). +### Adjusting the Hydrogen URL (optional) 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. @@ -29,11 +33,7 @@ matrix_client_hydrogen_hostname: "{{ matrix_server_fqn_matrix }}" 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. +After changing the domain, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server. If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration. diff --git a/docs/configuring-playbook-client-schildichat-web.md b/docs/configuring-playbook-client-schildichat-web.md index 380382937..592809afe 100644 --- a/docs/configuring-playbook-client-schildichat-web.md +++ b/docs/configuring-playbook-client-schildichat-web.md @@ -8,6 +8,12 @@ SchildiChat Web is a feature-rich messenger for Matrix based on Element Web with - [app.schildi.chat](https://app.schildi.chat/), hosted by the [SchildiChat](https://schildi.chat/) developers +## Adjusting DNS records + +By default, this playbook installs SchildiChat Web on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to create a CNAME record for `schildichat`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable SchildiChat Web, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -45,9 +51,7 @@ If you define your own themes with it and set `matrix_client_schildichat_themes_ 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. -### Adjusting the SchildiChat Web URL - -By default, this playbook installs SchildiChat Web on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). +### Adjusting the SchildiChat Web URL (optional) 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. @@ -62,6 +66,10 @@ matrix_client_schildichat_hostname: "{{ matrix_server_fqn_matrix }}" matrix_client_schildichat_path_prefix: /schildichat ``` +After changing the domain, **you may need to adjust your DNS** records to point the SchildiChat Web domain to the Matrix server. + +If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration. + ### Extending the configuration There are some additional things you may wish to configure about the component. @@ -89,14 +97,6 @@ matrix_client_schildichat_configuration_extension_json: | } ``` -## Adjusting DNS records - -Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the SchildiChat Web 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 and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index fe742165e..716b4ddcd 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -36,6 +36,12 @@ Dimension requires an access token to be able to connect to your homeserver. Ref ⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. +## Adjusting DNS records + +By default, this playbook installs Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to create a CNAME record for `dimension`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable Dimension, 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). @@ -58,9 +64,7 @@ matrix_dimension_admins: The admin interface is accessible within Element Web by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element Web by the "Add widgets, bridges, & bots" link in the room information. -### 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). +### Adjusting the Dimension URL (optional) 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. @@ -75,13 +79,11 @@ matrix_dimension_hostname: "{{ matrix_server_fqn_matrix }}" # 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 +After changing the domain, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server. -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. +If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration. -By default, you will need to create a CNAME record for `dimension`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. +**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. ## Installing diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md index 99ec8064d..6e32a1a35 100644 --- a/docs/configuring-playbook-etherpad.md +++ b/docs/configuring-playbook-etherpad.md @@ -4,6 +4,12 @@ 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 DNS records + +By default, this playbook installs Etherpad on the `etherpad.` subdomain (`etherpad.example.com`) and requires you to create a CNAME record for `etherpad`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -16,9 +22,7 @@ etherpad_enabled: true # 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). +### Adjusting the Etherpad URL (optional) 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. @@ -33,11 +37,7 @@ etherpad_hostname: "{{ matrix_server_fqn_matrix }}" etherpad_path_prefix: /etherpad ``` -## Adjusting DNS records - -Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server. - -By default, you will need to create a CNAME record for `etherpad`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. +After changing the domain, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server. If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration. diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index b8ec2bc7a..c5688b375 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -17,7 +17,9 @@ You may need to open the following ports to your server: ## Adjusting DNS records -By default, this playbook installs Jitsi on the `jitsi.` subdomain (`jitsi.example.com`) and requires you to create a CNAME record for `jitsi`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. +By default, this playbook installs Jitsi on the `jitsi.` subdomain (`jitsi.example.com`) and requires you to create a CNAME record for `jitsi`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. ## Adjusting the playbook configuration @@ -27,7 +29,7 @@ To enable Jitsi, add the following configuration to your `inventory/host_vars/ma jitsi_enabled: true ``` -### Adjusting the Jitsi URL +### Adjusting the Jitsi URL (optional) By tweaking the `jitsi_hostname` variable, you can easily make the service available at a **different hostname** than the default one. diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md index 50dee4d42..12bc7fc61 100644 --- a/docs/configuring-playbook-ntfy.md +++ b/docs/configuring-playbook-ntfy.md @@ -8,6 +8,12 @@ This role is intended to support UnifiedPush notifications for use with the Matr **Note**: In contrast to push notifications using Google's FCM or Apple's APNs, the use of UnifiedPush allows each end-user to choose the push notification server that they prefer. As a consequence, deploying this ntfy server does not by itself ensure any particular user or device or client app will use it. +## Adjusting DNS records + +By default, this playbook installs ntfy on the `ntfy.` subdomain (`ntfy.example.com`) and requires you to create a CNAME record for `ntfy`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -28,9 +34,7 @@ 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). +### Adjusting the ntfy URL (optional) By tweaking the `ntfy_hostname` variable, you can easily make the service available at a **different hostname** than the default one. @@ -41,11 +45,7 @@ Example additional configuration for your `vars.yml` file: ntfy_hostname: push.example.com ``` -## Adjusting DNS records - -Once you've decided on the domain, **you may need to adjust your DNS** records to point the ntfy domain to the Matrix server. - -By default, you will need to create a CNAME record for `ntfy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. +After changing the domain, **you may need to adjust your DNS** records to point the ntfy domain to the Matrix server. ## Installing diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md index d44c16aa4..851fa1635 100644 --- a/docs/configuring-playbook-prometheus-grafana.md +++ b/docs/configuring-playbook-prometheus-grafana.md @@ -2,6 +2,12 @@ The playbook can install [Grafana](https://grafana.com/) with [Prometheus](https://prometheus.io/) and configure performance metrics of your homeserver with graphs for you. +## Adjusting DNS records + +By default, this playbook installs Grafana web user-interface on the `stats.` subdomain (`stats.example.com`) and requires you to create a CNAME record for `stats`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable Grafana and/or Prometheus, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -32,9 +38,7 @@ grafana_default_admin_password: "some_strong_password_chosen_by_you" 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). +### Adjusting the Grafana URL (optional) By tweaking the `grafana_hostname` variable, you can easily make the service available at a **different hostname** than the default one. @@ -45,11 +49,7 @@ Example additional configuration for your `vars.yml` file: grafana_hostname: grafana.example.com ``` -## Adjusting DNS records - -Once you've decided on the domain, **you may need to adjust your DNS** records to point the Grafana domain to the Matrix server. - -By default, you will need to create a CNAME record for `stats`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. +After changing the domain, **you may need to adjust your DNS** records to point the Grafana domain to the Matrix server. **Note**: It is possible to install Prometheus without installing Grafana. This case it is not required to create the CNAME record. diff --git a/docs/configuring-playbook-rageshake.md b/docs/configuring-playbook-rageshake.md index ad7057f43..6db32e43a 100644 --- a/docs/configuring-playbook-rageshake.md +++ b/docs/configuring-playbook-rageshake.md @@ -6,6 +6,12 @@ See the project's [documentation](https://github.com/matrix-org/rageshake/blob/m **Note**: most people don't need to install rageshake to collect bug reports. This component is only useful to people who develop/build their own Matrix client applications themselves. +## Adjusting DNS records + +By default, this playbook installs rageshake on the `rageshake.` subdomain (`rageshake.example.com`) and requires you to create a CNAME record for `rageshake`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable rageshake, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -26,9 +32,7 @@ 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). +### Adjusting the rageshake URL (optional) 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. @@ -43,11 +47,7 @@ matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}" 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. +After changing the domain, **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. diff --git a/docs/configuring-playbook-sygnal.md b/docs/configuring-playbook-sygnal.md index 756eb2ee9..8172a17cd 100644 --- a/docs/configuring-playbook-sygnal.md +++ b/docs/configuring-playbook-sygnal.md @@ -10,6 +10,12 @@ See the project's [documentation](https://github.com/matrix-org/sygnal/blob/mast This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves. +## Adjusting DNS records + +By default, this playbook installs Sygnal on the `sygnal.` subdomain (`sygnal.example.com`) and requires you to create a CNAME record for `sygnal`, which targets `matrix.example.com`. + +When setting, replace `example.com` with your own. + ## Adjusting the playbook configuration To enable Sygnal, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -50,9 +56,7 @@ To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Noti - 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). +### Adjusting the Sygnal URL (optional) 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. @@ -67,11 +71,7 @@ matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}" 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. +After changing the domain, **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.