mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-10-31 07:17:57 +01:00
Update documentation for components which do not require subdomain settings by default
This adopts the structure of docs/configuring-playbook-matrix-authentication-service.md which was recently created. - … - Adjusting the playbook configuration - … - Adjusting the (service name here) URL - … - Adjusting DNS records - Installing - … Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara
@@ -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
|
||||
|
||||
|
||||
@@ -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,6 +24,27 @@ 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
|
||||
|
||||
|
||||
@@ -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,6 +27,27 @@ 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
|
||||
|
||||
@@ -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,26 +8,44 @@ 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
|
||||
|
||||
|
||||
@@ -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,13 +36,31 @@ 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`
|
||||
@@ -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.
|
||||
|
||||
@@ -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,6 +259,13 @@ 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
|
||||
|
||||
|
||||
@@ -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,6 +28,28 @@ 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:
|
||||
|
||||
@@ -12,28 +12,35 @@ 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
|
||||
|
||||
|
||||
@@ -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,6 +24,27 @@ 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
|
||||
|
||||
|
||||
@@ -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, run the [installation](installing.md) command: `just install-all` or `just setup-all`
|
||||
|
||||
Reference in New Issue
Block a user