mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-10-30 06:47:56 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update docs for DNS settings etc. (#3936)

Browse Source 
* 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 <acioustick@noreply.codeberg.org>

* Update docs for DNS settings of the services which do not need its CNAME record by default

- matrix-alertmanager-receiver
- Honoroit
- maubot
- Heisenbridge
- Cactus Comments
- Matrix Authentication Service
- matrix-registration
- Sliding Sync proxy
- Synapse Admin
- synapse-usage-exporter

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

* Update docs for DNS settings: ma1sd

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

* Update docs for DNS settings: Email2Matrix

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

* Update docs for DNS settings: Postmoogle

Remove the table from configuring-dns.md altogether

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

* Update docs for Cinny and Dimension: adopt the common note

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

* Update docs/configuring-dns.md: add "Note" to the line on using Cloudflare DNS

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

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara
2025-01-15 16:22:00 +09:00
committed by GitHub
parent cc5ac80e9e
commit 04b32af0c1
28 changed files with 237 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/configuring-dns.md
View File

@@ -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.
---------------------------------------------

18
docs/configuring-playbook-alertmanager-receiver.md
View File

@@ -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

16
docs/configuring-playbook-bot-buscarron.md
View File

@@ -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.

18
docs/configuring-playbook-bot-go-neb.md
View File

@@ -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.

18
docs/configuring-playbook-bot-honoroit.md
View File

@@ -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

18
docs/configuring-playbook-bot-maubot.md
View File

@@ -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

22
docs/configuring-playbook-bridge-heisenbridge.md
View File

@@ -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

16
docs/configuring-playbook-bridge-mautrix-wsproxy.md
View File

@@ -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

17
docs/configuring-playbook-bridge-postmoogle.md
View File

@@ -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:

18
docs/configuring-playbook-cactus-comments.md
View File

@@ -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

23
docs/configuring-playbook-client-cinny.md
View File

@@ -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

22
docs/configuring-playbook-client-element-web.md
View File

@@ -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:

16
docs/configuring-playbook-client-hydrogen.md
View File

@@ -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.

22
docs/configuring-playbook-client-schildichat-web.md
View File

@@ -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:

18
docs/configuring-playbook-dimension.md
View File

@@ -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

12
docs/configuring-playbook-email2matrix.md
View File

@@ -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).

16
docs/configuring-playbook-etherpad.md
View File

@@ -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.

6
docs/configuring-playbook-jitsi.md
View File

@@ -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.

2
docs/configuring-playbook-ma1sd.md
View File

@@ -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

22
docs/configuring-playbook-matrix-authentication-service.md
View File

@@ -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:

18
docs/configuring-playbook-matrix-registration.md
View File

@@ -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

16
docs/configuring-playbook-ntfy.md
View File

@@ -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

16
docs/configuring-playbook-prometheus-grafana.md
View File

@@ -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.

16
docs/configuring-playbook-rageshake.md
View File

@@ -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.

18
docs/configuring-playbook-sliding-sync-proxy.md
View File

@@ -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

16
docs/configuring-playbook-sygnal.md
View File

@@ -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.

18
docs/configuring-playbook-synapse-admin.md
View File

@@ -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

18
docs/configuring-playbook-synapse-usage-exporter.md
View File

@@ -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