mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2024-12-25 02:18:31 +01:00
Merge pull request #3646 from luixxiul/fix
Update documentation for components about adjusting the URL and the DNS records
This commit is contained in:
Slavi Pantaleev
GitHub
commit
3d7a926c19
@ -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:
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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?
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user