diff --git a/docs/configuring-playbook-alertmanager-receiver.md b/docs/configuring-playbook-alertmanager-receiver.md index c11b759fc..566cfc550 100644 --- a/docs/configuring-playbook-alertmanager-receiver.md +++ b/docs/configuring-playbook-alertmanager-receiver.md @@ -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 diff --git a/docs/configuring-playbook-bot-honoroit.md b/docs/configuring-playbook-bot-honoroit.md index 5cd218d2f..717791573 100644 --- a/docs/configuring-playbook-bot-honoroit.md +++ b/docs/configuring-playbook-bot-honoroit.md @@ -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 diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index 22b638f4c..cd866f6fd 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/docs/configuring-playbook-bot-maubot.md @@ -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 diff --git a/docs/configuring-playbook-bridge-heisenbridge.md b/docs/configuring-playbook-bridge-heisenbridge.md index 75c6b1315..f09e9add3 100644 --- a/docs/configuring-playbook-bridge-heisenbridge.md +++ b/docs/configuring-playbook-bridge-heisenbridge.md @@ -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 diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index d808d3e6e..735bf1edd 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -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 ``` + +**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. diff --git a/docs/configuring-playbook-matrix-authentication-service.md b/docs/configuring-playbook-matrix-authentication-service.md index 9fd2620a1..b0a0a8d9c 100644 --- a/docs/configuring-playbook-matrix-authentication-service.md +++ b/docs/configuring-playbook-matrix-authentication-service.md @@ -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 diff --git a/docs/configuring-playbook-matrix-registration.md b/docs/configuring-playbook-matrix-registration.md index cc5c0f69c..974789525 100644 --- a/docs/configuring-playbook-matrix-registration.md +++ b/docs/configuring-playbook-matrix-registration.md @@ -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: diff --git a/docs/configuring-playbook-sliding-sync-proxy.md b/docs/configuring-playbook-sliding-sync-proxy.md index 0368f4a3a..4193547f8 100644 --- a/docs/configuring-playbook-sliding-sync-proxy.md +++ b/docs/configuring-playbook-sliding-sync-proxy.md @@ -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 diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md index 2482f83bb..497c0a709 100644 --- a/docs/configuring-playbook-synapse-admin.md +++ b/docs/configuring-playbook-synapse-admin.md @@ -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 diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index 85c455b0f..0c9e19880 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/docs/configuring-playbook-synapse-usage-exporter.md @@ -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`