diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 4d66469e3..5cea036fc 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -36,42 +36,7 @@ The `element.example.com` subdomain is necessary, because this playbook installs Be mindful as to how long it will take for the DNS records to propagate. -If you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail. - -## DNS settings for optional services/features - -For other services which may need subdomain settings, see the table below and configure the DNS (`CNAME`) records accordingly. - -| 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` | -| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` | -| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` | - -### SRV record for ma1sd - -To make ma1sd enable its federation features, you need to set up a `_matrix-identity._tcp` SRV record. Don't confuse this with the `_matrix._tcp` SRV record for server delegation. See the table above and [this section](configuring-playbook-ma1sd.md#adjusting-dns-records) for values which need to be specified. - -When setting up a SRV record, if you are asked for a service and protocol instead of a hostname split the host value from the table where the period is. For example use service as `_matrix-identity` and protocol as `_tcp`. - -### MX and TXT records for Postmoogle - -To make Postmoogle enable its email sending features, you need to configure MX and TXT (SPF, DMARC, and DKIM) records. See the table above for values which need to be specified. +**Note**: if you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail. --------------------------------------------- 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 create a CNAME record for the matrix-alertmanager-receiver domain (`alertmanager.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-alertmanager-receiver domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing 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-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 create a CNAME record for the Honoroit domain (`honoroit.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +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 create a CNAME record for the maubot domain (`maubot.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the maubot domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +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 create a CNAME record for the Heisenbridge domain (`heisenbridge.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the Heisenbridge domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing 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-bridge-postmoogle.md b/docs/configuring-playbook-bridge-postmoogle.md index 9622b6919..af52e6acc 100644 --- a/docs/configuring-playbook-bridge-postmoogle.md +++ b/docs/configuring-playbook-bridge-postmoogle.md @@ -19,6 +19,19 @@ If you don't open these ports, you will still be able to send emails, but not re These port numbers are configurable via the `matrix_postmoogle_smtp_host_bind_port` and `matrix_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use. +## Adjusting DNS records + +To make Postmoogle enable its email sending features, you need to configure MX and TXT (SPF, DMARC, and DKIM) records. See the table below for values which need to be specified. + +| Type | Host | Priority | Weight | Port | Target | +|------|--------------------------------|----------|--------|------|------------------------------------| +| MX | `matrix` | 10 | 0 | - | `matrix.example.com` | +| TXT | `matrix` | - | - | - | `v=spf1 ip4:matrix-server-IP -all` | +| TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` | +| TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` | + +**Note**: the DKIM record can be retrieved after configuring and installing the bridge's bot. + ## Adjusting the playbook configuration Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -42,10 +55,6 @@ matrix_postmoogle_password: PASSWORD_FOR_THE_BOT # matrix_admin: '@yourAdminAccount:{{ matrix_domain }}' ``` -## Adjusting DNS records - -You will also need to add several DNS records so that Postmoogle can send emails. See [Configuring DNS](configuring-dns.md) for details about DNS changes. - ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: 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 create a CNAME record for the Cactus Comments' client domain (`cactus.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the Cactus Comments' client domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing diff --git a/docs/configuring-playbook-client-cinny.md b/docs/configuring-playbook-client-cinny.md index 0bbf71222..de1bd6324 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,28 +22,23 @@ 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 # Switch to a different domain (`app.example.com`) than the default one (`cinny.example.com`) matrix_client_cinny_hostname: "app.{{ matrix_domain }}" + +# Expose under the /cinny subpath +# matrix_client_cinny_path_prefix: /cinny ``` -## Adjusting DNS records +After changing the domain, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server. -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. - -If you've adjusted `matrix_client_cinny_hostname`, you will need to adjust your DNS configuration accordingly. +**Note**: while there is a `matrix_client_cinny_path_prefix` variable for changing the path where Cinny is served, overriding it is [not possible](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. You'd need to serve Cinny at a dedicated subdomain. ## 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..7d1c0ce3f 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. +After changing the domain, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server. -## Adjusting DNS records +If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration. -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. +**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'd need to serve Dimension at a dedicated subdomain. ## Installing diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index 02881ac64..d703d5417 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -8,10 +8,6 @@ See the project's [documentation](https://github.com/devture/email2matrix/blob/m ## Preparation -## Adjusting DNS records - -It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.example.com`, as described in the [Configuring DNS](configuring-dns.md) documentation page. - ### Port availability Ensure that port 25 is available on your Matrix server and open in your firewall. @@ -54,6 +50,14 @@ Make sure that you and the sender user are part of the same room and that the se Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below. +## Adjusting DNS records + +To increase the chances that incoming emails reach your server, you can set up a `MX` record for `matrix.example.com` that looks like this: + +| Type | Host | Priority | Weight | Port | Target | +|------|----------|----------|--------|------|------------------------------------| +| MX | `matrix` | 10 | 0 | - | `matrix.example.com` | + ## Adjusting the playbook configuration To enable Email2Matrix, add the following configuration to your `vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE` and `ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE` with the ones created [above](#obtain-an-access-token). 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-ma1sd.md b/docs/configuring-playbook-ma1sd.md index 597acc751..c2f9d3132 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -23,6 +23,8 @@ To make the ma1sd Identity Server enable its federation features, set up a SRV r See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record. +When setting up a SRV record, if you are asked for a service and protocol instead of a hostname split the host value from the table where the period is. For example use service as `_matrix-identity` and protocol as `_tcp`. + **Note**: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation. ## Adjusting the playbook configuration 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 create a CNAME record for the matrix-registration domain (`registration.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-registration domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing 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-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 create a CNAME record for the Sliding Sync proxy domain (`ss.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing 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. 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 create a CNAME record for the Synapse Admin domain (`admin.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the Synapse Admin domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +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 create a CNAME record for the synapse-usage-exporter domain (`sue.example.com`), which targets `matrix.example.com`. -If you've changed the default hostname, **you may need to adjust your DNS** records to point the synapse-usage-exporter domain to the Matrix server. - -See [Configuring DNS](configuring-dns.md) for details about DNS changes. - -If you've decided to use the default hostname, you won't need to do any extra DNS configuration. +When setting, replace `example.com` with your own. ## Installing