mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2024-11-06 02:37:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3646 from luixxiul/fix

Browse Source 
Update documentation for components about adjusting the URL and the DNS records
This commit is contained in:
Slavi Pantaleev 2024-10-21 10:07:34 +03:00 committed by GitHub
commit 3d7a926c19
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
25 changed files with 589 additions and 282 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/configuring-dns.md
View File

@ -45,6 +45,7 @@ When you're done configuring DNS, proceed to [Configuring the playbook](configur
| [SchildiChat](configuring-playbook-client-schildichat.md) web 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](docs/configuring-playbook-rageshake.md) bug report server | CNAME | `rageshake` | - | - | - | `matrix.example.com` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.example.com` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4:<your-ip> -all` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` |
@ -83,6 +84,8 @@ The `wsproxy.example.com` subdomain may be necessary, because this playbook coul
The `buscarron.example.com` subdomain may be necessary, because this playbook could install the [buscarron](https://github.com/etkecc/buscarron) bot. The installation of buscarron is disabled by default, it is not a core required component. To learn how to install it, see our [configuring buscarron guide](configuring-playbook-bot-buscarron.md). If you do not wish to set up buscarron, feel free to skip the `buscarron.example.com` DNS record.
The `rageshake.example.com` subdomain may be necessary, because this playbook could install the [rageshake](https://github.com/matrix-org/rageshake) bug report server. The installation of Rageshake is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Rageshake guide](docs/configuring-playbook-rageshake.md). If you do not wish to set up Rageshake, feel free to skip the `rageshake.example.com` DNS record.
## `_matrix-identity._tcp` SRV record setup
To make the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server (which this playbook may optionally install for you) enable its federation features, set up an SRV record that looks like this:

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

@ -10,19 +10,11 @@ This service is meant to be used with an external [Alertmanager](https://prometh
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable matrix-alertmanager-receiver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yml
matrix_alertmanager_receiver_enabled: true
# This exposes matrix-alertmanager-receiver on the `matrix.` domain.
# Adjust, if necessary.
matrix_alertmanager_receiver_hostname: "{{ matrix_server_fqn_matrix }}"
# This exposes matrix-alertmanager-receiver under a path prefix containing a random (secret) value.
# Adjust the `RANDOM_VALUE_HERE` part with a long and secure value.
matrix_alertmanager_receiver_path_prefix: /matrix-alertmanager-receiver-RANDOM_VALUE_HERE
# If you'd like to change the username for this bot, uncomment and adjust. Otherwise, remove.
# matrix_alertmanager_receiver_config_matrix_user_id_localpart: "bot.alertmanager.receiver"
@ -43,6 +35,27 @@ 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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
matrix_alertmanager_receiver_hostname: alertmanager.example.com
matrix_alertmanager_receiver_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-alertmanager-receiver domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Account and room preparation
@ -56,14 +69,14 @@ The playbook can automatically create users, but it cannot automatically obtain
4. Log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account and log out
5. (Optionally) Adjust `matrix_alertmanager_receiver_config_matrix_room_mapping` to create a mapping between the new room and its ID
Steps 1 and 2 above only need to be done once, while preparing your [configuration](#configuration).
Steps 1 and 2 above only need to be done once, while preparing your [configuration](#adjusting-the-playbook-configuration).
Steps 3 and 4 need to be done for each new room you'd like the bot to deliver alerts to. Step 5 is optional and provides cleaner `/alert/` URLs.
## Installing
Now that you've [prepared the bot account and room](#account-and-room-preparation) and have [configured the playbook](#configuration), you can run the [installation](installing.md) command: `just install-all`
Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the [installation](installing.md) command: `just install-all`
Then, you can proceed to [Usage](#usage).

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

@ -4,33 +4,9 @@ The playbook can install and configure [buscarron](https://github.com/etkecc/bus
Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.
## Decide on a domain and path
By default, Buscarron is configured to use its own dedicated domain (`buscarron.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Buscarron.
matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /buscarron subpath
matrix_bot_buscarron_path_prefix: /buscarron
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable Buscarron, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_bot_buscarron_enabled: true
@ -53,10 +29,34 @@ matrix_bot_buscarron_forms:
matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
```
### Adjusting the Buscarron URL
By default, this playbook installs Buscarron on the `buscarron.` subdomain (`buscarron.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_bot_buscarron_hostname` and `matrix_bot_buscarron_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Buscarron.
matrix_bot_buscarron_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /buscarron subpath
matrix_bot_buscarron_path_prefix: /buscarron
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Buscarron domain to the Matrix server.
By default, you will need to create a CNAME record for `buscarron`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

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

@ -24,32 +24,9 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb
Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
## Decide on a domain and path
By default, Go-NEB is configured to use its own dedicated domain (`goneb.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Go-NEB.
matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /go-neb subpath
matrix_bot_go_neb_path_prefix: /go-neb
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_bot_go_neb_enabled: true
@ -213,10 +190,34 @@ matrix_bot_go_neb_services:
msg_type: "m.text" # Must be either `m.text` or `m.notice`
```
### Adjusting the Go-NEB URL
By default, this playbook installs Go-NEB on the `goneb.` subdomain (`goneb.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_bot_go_neb_hostname` and `matrix_bot_go_neb_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Go-NEB.
matrix_bot_go_neb_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /buscarron subpath
matrix_bot_go_neb_path_prefix: /go-neb
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Go-NEB domain to the Matrix server.
By default, you will need to create a CNAME record for `goneb`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing
After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@ -9,15 +9,11 @@ See the project's [documentation](https://github.com/etkecc/honoroit#how-it-look
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_bot_honoroit_enabled: true
# Uncomment and adjust this part if you'd like to use a hostname or path different than the default
# matrix_bot_honoroit_hostname: "{{ matrix_server_fqn_matrix }}"
# matrix_bot_honoroit_path_prefix: /honoroit
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_honoroit_login: honoroit
@ -28,10 +24,31 @@ matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT
matrix_bot_honoroit_roomid: "!yourRoomID:{{ 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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
matrix_bot_honoroit_hostname: honoroit.example.com
matrix_bot_honoroit_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

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

@ -10,7 +10,7 @@ does and why it might be useful to you.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable maubot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_bot_maubot_enabled: true
@ -27,10 +27,31 @@ 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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
matrix_bot_maubot_hostname: maubot.example.com
matrix_bot_maubot_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the maubot domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`
**Notes**:
@ -38,7 +59,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
## Usage
You can visit `matrix.example.com/_matrix/maubot/` to manage your available plugins, clients and instances.
By default, you can visit `matrix.example.com/_matrix/maubot/` to manage your available plugins, clients and instances.
You should start in the following order
1. **Create one or more clients**: A client is a Matrix account which the bot will use to message. By default, the playbook creates a `bot.maubot` account (as per the configuration above). You only need to [obtain an access token](#obtaining-an-access-token) for it

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

@ -8,30 +8,48 @@ See the project's [README](https://github.com/hifi/heisenbridge/blob/master/READ
## Configuration
Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml).
At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.example.com/vars.yml`):
To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_heisenbridge_enabled: true
# set owner (optional)
# Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.
# If you are not using a local user you must set it as otherwise you can't DM it at all.
matrix_heisenbridge_owner: "@you:your-homeserver"
# to enable identd on host port 113/TCP (optional)
matrix_heisenbridge_identd_enabled: true
# Uncomment to enable identd on host port 113/TCP (optional)
# matrix_heisenbridge_identd_enabled: true
```
By default, Heisenbrdige would be exposed on the Matrix domain (`matrix.example.com`, as specified in `matrix_server_fqn_matrix`) under the `/heisenbridge` path prefix. 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)).
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.
That's it! A registration file is automatically generated during the setup phase.
### Adjusting the Heisenbridge URL
Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` will be made the owner.
If you are not using a local user you must set it as otherwise you can't DM it at all.
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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
matrix_heisenbridge_hostname: heisenbridge.example.com
matrix_heisenbridge_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Heisenbridge domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
## Usage

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

@ -4,12 +4,6 @@ The playbook can install and configure [mautrix-wsproxy](https://github.com/maut
See the project's [documentation](https://github.com/mautrix/wsproxy#readme) to learn what it does and why it might be useful to you.
## DNS
You need to create a `wsproxy.example.com` DNS record pointing to your Matrix server (a `CNAME` pointing to `matrix.example.com`) to use wsproxy.
The hostname is configurable via a `matrix_mautrix_wsproxy_hostname` variable.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -26,9 +20,28 @@ matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge'
Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device.
### Adjusting the wsproxy URL
By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_mautrix_wsproxy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname
matrix_mautrix_wsproxy_hostname: wsproxy.example.com
```
## Adjusting DNS records
Once you've decided on the domain, **you may need to adjust your DNS** records to point the wsproxy domain to the Matrix server.
By default, you will need to create a CNAME record for `wsproxy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
## Usage

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

@ -16,7 +16,7 @@ You can enable whichever component you need (typically both).
## Configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable Cactus Comments, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
#################
@ -36,16 +36,34 @@ matrix_cactus_comments_enabled: true
# When the backend (appservice) is enabled, this is also enabled automatically,
# but we explicitly enable it here.
matrix_cactus_comments_client_enabled: true
# Uncomment and adjust this part if you'd like to host the client assets at a different location.
# These variables are only make used if (`matrix_cactus_comments_client_enabled: true`)
# matrix_cactus_comments_client_hostname: "{{ matrix_server_fqn_matrix }}"
# matrix_cactus_comments_client_path_prefix: /cactus-comments
```
### 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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix to host the client assets at a different location
# These variables are used only if (`matrix_cactus_comments_client_enabled: true`)
matrix_cactus_comments_client_hostname: cactus.example.com
matrix_cactus_comments_client_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Cactus Comments' client domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
## Usage
@ -91,3 +109,5 @@ Make sure to replace `example.com` with your base domain before you include the
<script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
<link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">
```
**Note**: if the `matrix_cactus_comments_client_hostname` and `matrix_cactus_comments_client_path_prefix` variables are tweaked, you would need to adjust the URLs of the assets accordingly.

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

@ -4,18 +4,6 @@ This playbook can install the [cinny](https://github.com/ajbura/cinny) Matrix we
Cinny is a web client focusing primarily on simple, elegant and secure interface. It can be installed alongside or instead of Element.
## DNS
You need to add a DNS record so that Cinny can be accessed.
By default Cinny will use https://cinny.example.com so you will need to create an CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md).
If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
```yaml
matrix_server_fqn_cinny: "app.{{ matrix_domain }}"
```
## Adjusting the playbook configuration
To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -24,6 +12,31 @@ To enable Cinny, add the following configuration to your `inventory/host_vars/ma
matrix_client_cinny_enabled: true
```
### Adjusting the Cinny URL
By default, this playbook installs Cinny on the `cinny.` subdomain (`cinny.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_cinny_hostname` and `matrix_client_cinny_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Cinny.
matrix_client_cinny_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /cinny subpath
matrix_client_cinny_path_prefix: /cinny
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Cinny domain to the Matrix server.
By default, you will need to create a CNAME record for `cinny`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`

35
docs/configuring-playbook-client-element.md
View File

@ -5,14 +5,14 @@ By default, this playbook installs the [Element](https://github.com/element-hq/e
## Disabling Element
If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), you can disable it in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
If you'd like for the playbook to not install Element (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_client_element_enabled: false
```
## Configuring Element settings
## Adjusting the playbook configuration
The playbook provides some customization variables you could use to change Element's settings.
@ -29,7 +29,7 @@ Alternatively, **if there is no pre-defined variable** for an Element setting yo
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
## Themes
### Themes
To change the look of Element, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
@ -38,3 +38,32 @@ Or better yet, you can automatically pull it all themes provided by the [aaronra
If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
Note that for a custom theme to work well, all Element instances that you use must have the same theme installed.
### Adjusting the Element URL
By default, this playbook installs Element on the `element.` subdomain (`element.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_element_hostname` and `matrix_client_element_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Element.
matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /element subpath
matrix_client_element_path_prefix: /element
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Element domain to the Matrix server.
By default, you will need to create a CNAME record for `element`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`

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

@ -4,18 +4,6 @@ This playbook can install the [Hydrogen](https://github.com/element-hq/hydrogen-
Hydrogen is a lightweight web client that supports mobile and legacy web browsers. It can be installed alongside or instead of Element.
## DNS
You need to add a DNS record so that Hydrogen can be accessed.
By default Hydrogen will use https://hydrogen.example.com so you will need to create an CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md).
If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
```yaml
matrix_server_fqn_hydrogen: "helium.{{ matrix_domain }}"
```
## Adjusting the playbook configuration
To enable Hydrogen, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -24,6 +12,31 @@ To enable Hydrogen, add the following configuration to your `inventory/host_vars
matrix_client_hydrogen_enabled: true
```
### Adjusting the Hydrogen URL
By default, this playbook installs Hydrogen on the `hydrogen.` subdomain (`hydrogen.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_hydrogen_hostname` and `matrix_client_hydrogen_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Hydrogen.
matrix_client_hydrogen_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /hydrogen subpath
matrix_client_hydrogen_path_prefix: /hydrogen
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Hydrogen domain to the Matrix server.
By default, you will need to create a CNAME record for `hydrogen`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`

39
docs/configuring-playbook-client-schildichat.md
View File

@ -6,18 +6,6 @@ SchildiChat is a feature-rich messenger for Matrix based on Element with some ex
**WARNING**: SchildiChat Web is based on Element-web, but its releases are lagging behind. As an example (from 2024-02-26), SchildiChat Web is 22 releases behind (it being based on element-web `v1.11.36`, while element-web is now on `v1.11.58`). Element-web frequently suffers from security issues, so running something based on an ancient Element-web release is **dangerous**. Use SchildiChat Web at your own risk!
## DNS
You need to add a DNS record so that SchildiChat can be accessed.
By default SchildiChat will use https://schildichat.example.com so you will need to create an CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md).
If you would like to use a different domain, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (changing it to use your preferred domain):
```yaml
matrix_server_fqn_schildichat: "sc.{{ matrix_domain }}"
```
## Adjusting the playbook configuration
To enable SchildiChat, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -50,6 +38,31 @@ If you make your own theme, we encourage you to submit it to the **aaronraimist/
Note that for a custom theme to work well, all SchildiChat instances that you use must have the same theme installed.
### Adjusting the SchildiChat URL
By default, this playbook installs SchildiChat on the `schildichat.` subdomain (`schildichat.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_client_schildichat_hostname` and `matrix_client_schildichat_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for SchildiChat.
matrix_client_schildichat_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /schildichat subpath
matrix_client_schildichat_path_prefix: /schildichat
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the SchildiChat domain to the Matrix server.
By default, you will need to create a CNAME record for `schildichat`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`

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

@ -7,28 +7,7 @@ If you're just installing Matrix services for the first time, please continue wi
**Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
## Decide on a domain and path
By default, Dimension is configured to use its own dedicated domain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to another hostname compared to the default (`dimension.{{ matrix_domain }}`)
matrix_dimension_hostname: "integrations.{{ matrix_domain }}"
```
While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible right now due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain until this issue is solved.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
## Enable
## Adjusting the playbook configuration
To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
@ -36,8 +15,7 @@ To enable Dimension, add this to your configuration file (`inventory/host_vars/m
matrix_dimension_enabled: true
```
## Define admin users
### Define admin users
These users can modify the integrations this Dimension supports.
Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
@ -50,7 +28,7 @@ matrix_dimension_admins:
The admin interface is accessible within Element by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element by the "Add widgets, bridges, & bots" link in the room information.
## Access token
### Access token
We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username).
Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
@ -68,10 +46,34 @@ matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE"
For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens).
### Adjusting the Dimension URL
By default, this playbook installs Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_dimension_hostname` and `matrix_dimension_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Dimension.
matrix_dimension_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /dimension subpath
# matrix_dimension_path_prefix: /dimension
```
**Note**: While there is a `matrix_dimension_path_prefix` variable for changing the path where Dimension is served, overriding it is not possible due to [this Dimension issue](https://github.com/turt2live/matrix-dimension/issues/510). You must serve Dimension at a dedicated subdomain.
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Dimension domain to the Matrix server.
By default, you will need to create a CNAME record for `dimension`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
## Installing
After these variables have been set and you have potentially [adjusted your DNS records](#adjusting-dns-records), please run the following command to re-run setup and to restart Dimension:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@ -4,12 +4,25 @@
When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
## Adjusting the playbook configuration
## Decide on a domain and path
To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
By default, Etherpad is configured to use its own dedicated domain (`etherpad.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
```yaml
etherpad_enabled: true
You can override the domain and path like this:
# Uncomment and adjust this part if you'd like to enable the admin web UI
# etherpad_admin_username: YOUR_USERNAME_HERE
# etherpad_admin_password: YOUR_PASSWORD_HERE
```
### Adjusting the Etherpad URL
By default, this playbook installs Etherpad on the `etherpad.` subdomain (`etherpad.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `etherpad_hostname` and `etherpad_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
@ -25,24 +38,13 @@ etherpad_path_prefix: /etherpad
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
By default, you will need to create a CNAME record for `etherpad`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Adjusting the playbook configuration
[Etherpad](https://etherpad.org) installation is disabled by default. To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
etherpad_enabled: true
# Uncomment and adjust this part if you'd like to enable the admin web UI
# etherpad_admin_username: YOUR_USERNAME_HERE
# etherpad_admin_password: YOUR_PASSWORD_HERE
```
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
## Usage

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

@ -9,9 +9,7 @@ The setup done by the playbook is very similar to [docker-jitsi-meet](https://gi
## Prerequisites
Before installing Jitsi, make sure you've created the `jitsi.example.com` DNS record (unless you've changed `jitsi_hostname`, as described below). See [Configuring DNS](configuring-dns.md) for details about DNS changes.
You may also need to open the following ports to your server:
You may need to open the following ports to your server:
- `4443/tcp` - RTP media fallback over TCP
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
@ -19,18 +17,31 @@ You may also need to open the following ports to your server:
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
jitsi_enabled: true
# Uncomment and adjust this part if you'd like to use a hostname different than the default
# jitsi_hostname: "jitsi.{{ matrix_domain }}"
# Uncomment and possible adjust this part if you'd like to host under a subpath
# jitsi_path_prefix: /jitsi
```
### Adjusting the Jitsi URL
By default, this playbook installs Jitsi on the `jitsi.` subdomain (`jitsi.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `jitsi_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname
jitsi_hostname: jitsi.example.com
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Jitsi domain to the Matrix server.
By default, you will need to create a CNAME record for `jitsi`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
## (Optional) Configure Jitsi authentication and guests mode
By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration.
@ -273,7 +284,7 @@ Besides metadata, this includes the Matrix user_id and possibly the room identif
## Installing
After configuring the playbook, run the [installation](installing.md) command:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@ -94,7 +94,7 @@ For existing Synapse homeservers:
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_authentication_service_enabled: true
@ -115,7 +115,7 @@ There are many other configuration options available. Consult the [`defaults/mai
### Adjusting the Matrix Authentication Service URL
By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (e.g. 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.
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.
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.
@ -259,10 +259,17 @@ matrix_authentication_service_config_upstream_oauth2_providers:
⚠ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2.
## 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), you can run the [installation](installing.md) command: `just install-all`
Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the [installation](installing.md) command: `just install-all`
If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing homeserver to Matrix Authentication Service](#migrating-an-existing-homeserver-to-matrix-authentication-service) guide.

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

@ -19,7 +19,7 @@ Use matrix-registration to **create unique registration links**, which people ca
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_registration_enabled: true
@ -28,9 +28,31 @@ 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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
matrix_registration_hostname: registration.example.com
matrix_registration_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the matrix-registration domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@ -11,15 +11,12 @@ This role is intended to support UnifiedPush notifications for use with the Matr
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Enabling it is the only required setting
ntfy_enabled: true
# Uncomment and adjust this part if you'd like to use a hostname different than the default
# matrix_server_fqn_ntfy: "ntfy.{{ matrix_domain }}"
# Uncomment to enable the ntfy web app (disabled by default)
# ntfy_web_root: app # defaults to "disable"
@ -32,12 +29,28 @@ For a more complete list of variables that you could override, see the [`default
For a complete list of ntfy config options that you could put in `ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
### Adjusting the ntfy URL
By default, this playbook installs ntfy on the `ntfy.` subdomain (`ntfy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `ntfy_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname
ntfy_hostname: ntfy.example.com
```
## Adjusting DNS records
Once you've decided on the domain, **you may need to adjust your DNS** records to point the ntfy domain to the Matrix server.
By default, you will need to create a CNAME record for `ntfy`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
## Installing
Don't forget to add `ntfy.example.com` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
After configuring the playbook, run the [installation](installing.md) command:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@ -1,10 +1,10 @@
# Enabling metrics and graphs for your Matrix server (optional)
It can be useful to have some (visual) insight into the performance of your homeserver.
The playbook can install [Grafana](https://grafana.com/) with [Prometheus](https://prometheus.io/) and configure performance metrics of your homeserver with graphs for you.
You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
## Adjusting the playbook configuration
Remember to add `stats.example.com` to DNS as described in [Configuring DNS](configuring-dns.md) before running the playbook.
To enable Grafana and/or Prometheus, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
prometheus_enabled: true
@ -30,10 +30,32 @@ grafana_default_admin_user: "some_username_chosen_by_you"
grafana_default_admin_password: "some_strong_password_chosen_by_you"
```
By default, a [Grafana](https://grafana.com/) web user-interface will be available at `https://stats.example.com`.
The retention policy of Prometheus metrics is [15 days by default](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects). Older data gets deleted automatically.
### Adjusting the Grafana URL
By default, this playbook installs Grafana web user-interface on the `stats.` subdomain (`stats.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `grafana_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname
grafana_hostname: stats.example.com
```
## Adjusting DNS records
Once you've decided on the domain, **you may need to adjust your DNS** records to point the Grafana domain to the Matrix server.
By default, you will need to create a CNAME record for `stats`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
**Note**: It is possible to install Prometheus without installing Grafana. This case it is not required to create the CNAME record.
## Installing
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
## What does it do?

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

@ -4,33 +4,9 @@ The playbook can install and configure the [rageshake](https://github.com/matrix
This is useful if you're developing your own applications and would like to collect bug reports for them.
## Adjusting the playbook configuration
## Decide on a domain and path
By default, Rageshake is configured to use its own dedicated domain (`rageshake.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Rageshake.
matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /rageshake subpath
matrix_rageshake_path_prefix: /rageshake
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Rageshake domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Enabling the Rageshake service
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
To enable Rageshake, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_rageshake_enabled: true
@ -48,10 +24,34 @@ matrix_rageshake_configuration_extension_yaml: |
my-app: octocat/HelloWorld
```
### Adjusting the Rageshake URL
By default, this playbook installs Rageshake on the `rageshake.` subdomain (`rageshake.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_rageshake_hostname` and `matrix_rageshake_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Rageshake.
matrix_rageshake_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /rageshake subpath
matrix_rageshake_path_prefix: /rageshake
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Rageshake domain to the Matrix server.
By default, you will need to create a CNAME record for `rageshake`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command:
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

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

@ -12,32 +12,39 @@ Element X Android is [available on the Github Releases page](https://github.com/
**Note**: The sliding-sync proxy is **not required** when using the **Conduit homeserver**. Starting from version `0.6.0` Conduit has native support for some sliding sync features. If there are issues with the native implementation, you might have a better experience when enabling the sliding-sync proxy anyway.
## Decide on a domain and path
By default, the Sliding Sync proxy is configured to be served on the Matrix domain (`matrix.example.com`, controlled by `matrix_server_fqn_matrix`), under the `/sliding-sync` path.
This makes it easy to set it up, **without** having to [adjust your DNS records](#adjusting-dns-records).
If you'd like to run the Sliding Sync proxy on another hostname or path, use the `matrix_sliding_sync_hostname` and `matrix_sliding_sync_path_prefix` variables.
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable Sliding Sync proxy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
matrix_sliding_sync_hostname: ss.example.com
matrix_sliding_sync_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Honoroit domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
After potentially [adjusting DNS records](#adjusting-dns-records) and configuring the playbook, run the [installation](installing.md) command again: `just install-all`.
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all`.
### External databases

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

@ -10,33 +10,9 @@ See the project's [documentation](https://github.com/matrix-org/sygnal) to learn
This optional playbook component is only useful to people who develop/build their own Matrix client applications themselves.
## Decide on a domain and path
By default, Sygnal is configured to use its own dedicated domain (`sygnal.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
You can override the domain and path like this:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Sygnal.
matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /sygnal subpath
matrix_sygnal_path_prefix: /sygnal
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Sygnal domain to the Matrix server.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
To enable Sygnal, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_sygnal_enabled: true
@ -75,6 +51,30 @@ To do that, the above example configuration:
- references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container)
### Adjusting the Sygnal URL
By default, this playbook installs Sygnal on the `sygnal.` subdomain (`sygnal.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).
By tweaking the `matrix_sygnal_hostname` and `matrix_sygnal_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Switch to the domain used for Matrix services (`matrix.example.com`),
# so we won't need to add additional DNS records for Sygnal.
matrix_sygnal_hostname: "{{ matrix_server_fqn_matrix }}"
# Expose under the /sygnal subpath
matrix_sygnal_path_prefix: /sygnal
```
## Adjusting DNS records
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Sygnal domain to the Matrix server.
By default, you will need to create a CNAME record for `sygnal`. See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
## Installing

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

@ -9,7 +9,7 @@ See the project's [documentation](https://github.com/etkecc/synapse-admin) to le
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_synapse_admin_enabled: true
@ -24,11 +24,31 @@ 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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
matrix_synapse_admin_hostname: admin.example.com
matrix_synapse_admin_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Synapse Admin domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all`
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command:
## Usage

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

@ -11,9 +11,9 @@ 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
## Quickstart
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file and [re-run the installation process](./installing.md) for the playbook:
To enable synapse-usage-exporter, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_synapse_usage_exporter_enabled: true
@ -24,3 +24,30 @@ matrix_synapse_usage_exporter_enabled: true
# You can adjust the hostname and path via `matrix_synapse_usage_exporter_hostname` and `matrix_synapse_usage_exporter_path_prefix`.
# 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.
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.
Example additional configuration for your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Change the default hostname and path prefix
# These variables are used only if (`matrix_synapse_usage_exporter_proxying_enabled: true`)
matrix_synapse_usage_exporter_hostname: sue.example.com
matrix_synapse_usage_exporter_path_prefix: /
```
## Adjusting DNS records
If you've changed the default hostname, **you may need to adjust your DNS** records to point the synapse-usage-exporter domain to the Matrix server.
See [Configuring DNS](configuring-dns.md) for details about DNS changes.
If you've decided to use the default hostname, 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 [installation](installing.md) command: `just install-all` or `just setup-all`