From 81d76989446ed8c471e06c14748e57d6c8690271 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 21 Oct 2024 05:07:51 +0900 Subject: [PATCH 1/5] Update documentation for components which require subdomain settings by default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/configuring-playbook-bot-buscarron.md | 50 +++++++++--------- docs/configuring-playbook-bot-go-neb.md | 49 ++++++++--------- ...iguring-playbook-bridge-mautrix-wsproxy.md | 25 ++++++--- docs/configuring-playbook-client-cinny.md | 37 ++++++++----- docs/configuring-playbook-client-element.md | 35 +++++++++++-- docs/configuring-playbook-client-hydrogen.md | 37 ++++++++----- ...configuring-playbook-client-schildichat.md | 37 ++++++++----- docs/configuring-playbook-dimension.md | 52 ++++++++++--------- docs/configuring-playbook-etherpad.md | 34 ++++++------ docs/configuring-playbook-jitsi.md | 31 +++++++---- docs/configuring-playbook-ntfy.md | 25 ++++++--- ...configuring-playbook-prometheus-grafana.md | 32 ++++++++++-- docs/configuring-playbook-rageshake.md | 52 +++++++++---------- docs/configuring-playbook-sygnal.md | 50 +++++++++--------- 14 files changed, 339 insertions(+), 207 deletions(-) diff --git a/docs/configuring-playbook-bot-buscarron.md b/docs/configuring-playbook-bot-buscarron.md index fb01bb2ae..4c81cebb9 100644 --- a/docs/configuring-playbook-bot-buscarron.md +++ b/docs/configuring-playbook-bot-buscarron.md @@ -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,6 +29,30 @@ 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 diff --git a/docs/configuring-playbook-bot-go-neb.md b/docs/configuring-playbook-bot-go-neb.md index 8e5e08a5f..72334f1a5 100644 --- a/docs/configuring-playbook-bot-go-neb.md +++ b/docs/configuring-playbook-bot-go-neb.md @@ -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,6 +190,30 @@ 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 diff --git a/docs/configuring-playbook-bridge-mautrix-wsproxy.md b/docs/configuring-playbook-bridge-mautrix-wsproxy.md index 2bff1ecda..48e3a9198 100644 --- a/docs/configuring-playbook-bridge-mautrix-wsproxy.md +++ b/docs/configuring-playbook-bridge-mautrix-wsproxy.md @@ -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,6 +20,25 @@ 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` diff --git a/docs/configuring-playbook-client-cinny.md b/docs/configuring-playbook-client-cinny.md index d5deb3380..680baa1d8 100644 --- a/docs/configuring-playbook-client-cinny.md +++ b/docs/configuring-playbook-client-cinny.md @@ -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` diff --git a/docs/configuring-playbook-client-element.md b/docs/configuring-playbook-client-element.md index 65ff2f577..159072cca 100644 --- a/docs/configuring-playbook-client-element.md +++ b/docs/configuring-playbook-client-element.md @@ -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, run the [installation](installing.md) command: `just install-all` or `just setup-all` diff --git a/docs/configuring-playbook-client-hydrogen.md b/docs/configuring-playbook-client-hydrogen.md index 94775eaae..6ad08c770 100644 --- a/docs/configuring-playbook-client-hydrogen.md +++ b/docs/configuring-playbook-client-hydrogen.md @@ -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` diff --git a/docs/configuring-playbook-client-schildichat.md b/docs/configuring-playbook-client-schildichat.md index 251a28933..6f220ad65 100644 --- a/docs/configuring-playbook-client-schildichat.md +++ b/docs/configuring-playbook-client-schildichat.md @@ -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` diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 15351282d..93f2c7d51 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -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,6 +46,30 @@ 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 diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md index 4810c24d6..18e37c5f4 100644 --- a/docs/configuring-playbook-etherpad.md +++ b/docs/configuring-playbook-etherpad.md @@ -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,21 +38,10 @@ 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` diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index 3b395b319..3398bf3c1 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -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. diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md index 67f7ce6c7..aedd51b81 100644 --- a/docs/configuring-playbook-ntfy.md +++ b/docs/configuring-playbook-ntfy.md @@ -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,11 +29,27 @@ 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: ``` diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md index d1f2e2fa5..3b0426b07 100644 --- a/docs/configuring-playbook-prometheus-grafana.md +++ b/docs/configuring-playbook-prometheus-grafana.md @@ -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, run the [installation](installing.md) command: `just install-all` or `just setup-all` ## What does it do? diff --git a/docs/configuring-playbook-rageshake.md b/docs/configuring-playbook-rageshake.md index 34fd08633..a9f7f63b6 100644 --- a/docs/configuring-playbook-rageshake.md +++ b/docs/configuring-playbook-rageshake.md @@ -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,6 +24,30 @@ 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 diff --git a/docs/configuring-playbook-sygnal.md b/docs/configuring-playbook-sygnal.md index d7382c3d0..642ed5488 100644 --- a/docs/configuring-playbook-sygnal.md +++ b/docs/configuring-playbook-sygnal.md @@ -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 From ea6e8794870074c6ebffc0ac3893c82eca0e0aa6 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 21 Oct 2024 05:13:48 +0900 Subject: [PATCH 2/5] Update docs/configuring-dns.md: add an entry for Rageshake Signed-off-by: Suguru Hirahara --- docs/configuring-dns.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index e64c3b40e..720424425 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -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: -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: From c892971e89419cff69e11fc4cb7925436b0e1a56 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 21 Oct 2024 05:15:21 +0900 Subject: [PATCH 3/5] Update documentation for components which do not require subdomain settings by default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...figuring-playbook-alertmanager-receiver.md | 31 ++++++++++----- docs/configuring-playbook-bot-honoroit.md | 27 ++++++++++--- docs/configuring-playbook-bot-maubot.md | 25 +++++++++++- ...onfiguring-playbook-bridge-heisenbridge.md | 38 ++++++++++++++----- docs/configuring-playbook-cactus-comments.md | 32 +++++++++++++--- ...-playbook-matrix-authentication-service.md | 11 +++++- ...onfiguring-playbook-matrix-registration.md | 24 +++++++++++- ...configuring-playbook-sliding-sync-proxy.md | 37 ++++++++++-------- docs/configuring-playbook-synapse-admin.md | 23 ++++++++++- ...iguring-playbook-synapse-usage-exporter.md | 31 ++++++++++++++- 10 files changed, 226 insertions(+), 53 deletions(-) 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` From e8c61b0a3c22d546abe07dc7c7e1941bb59a495a Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 21 Oct 2024 05:42:21 +0900 Subject: [PATCH 4/5] Update lines for installing instruction: add anchor link to "adjusting DNS records" header Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-alertmanager-receiver.md | 2 +- docs/configuring-playbook-bot-buscarron.md | 2 +- docs/configuring-playbook-bot-go-neb.md | 2 +- docs/configuring-playbook-bot-honoroit.md | 2 +- docs/configuring-playbook-bot-maubot.md | 2 +- docs/configuring-playbook-bridge-heisenbridge.md | 2 +- docs/configuring-playbook-bridge-mautrix-wsproxy.md | 2 +- docs/configuring-playbook-cactus-comments.md | 2 +- docs/configuring-playbook-client-cinny.md | 2 +- docs/configuring-playbook-client-element.md | 2 +- docs/configuring-playbook-client-hydrogen.md | 2 +- docs/configuring-playbook-client-schildichat.md | 2 +- docs/configuring-playbook-dimension.md | 2 +- docs/configuring-playbook-etherpad.md | 2 +- docs/configuring-playbook-jitsi.md | 2 +- docs/configuring-playbook-matrix-authentication-service.md | 2 +- docs/configuring-playbook-matrix-registration.md | 2 +- docs/configuring-playbook-ntfy.md | 2 +- docs/configuring-playbook-prometheus-grafana.md | 2 +- docs/configuring-playbook-rageshake.md | 2 +- docs/configuring-playbook-sliding-sync-proxy.md | 2 +- docs/configuring-playbook-synapse-admin.md | 3 +-- docs/configuring-playbook-synapse-usage-exporter.md | 2 +- 23 files changed, 23 insertions(+), 24 deletions(-) diff --git a/docs/configuring-playbook-alertmanager-receiver.md b/docs/configuring-playbook-alertmanager-receiver.md index 566cfc550..1de72ee21 100644 --- a/docs/configuring-playbook-alertmanager-receiver.md +++ b/docs/configuring-playbook-alertmanager-receiver.md @@ -76,7 +76,7 @@ Steps 3 and 4 need to be done for each new room you'd like the bot to deliver al ## 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](#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). diff --git a/docs/configuring-playbook-bot-buscarron.md b/docs/configuring-playbook-bot-buscarron.md index 4c81cebb9..20cd40c9f 100644 --- a/docs/configuring-playbook-bot-buscarron.md +++ b/docs/configuring-playbook-bot-buscarron.md @@ -56,7 +56,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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 diff --git a/docs/configuring-playbook-bot-go-neb.md b/docs/configuring-playbook-bot-go-neb.md index 72334f1a5..e3316a54b 100644 --- a/docs/configuring-playbook-bot-go-neb.md +++ b/docs/configuring-playbook-bot-go-neb.md @@ -217,7 +217,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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 diff --git a/docs/configuring-playbook-bot-honoroit.md b/docs/configuring-playbook-bot-honoroit.md index 717791573..29680cb04 100644 --- a/docs/configuring-playbook-bot-honoroit.md +++ b/docs/configuring-playbook-bot-honoroit.md @@ -48,7 +48,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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 diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index cd866f6fd..8a59ac919 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/docs/configuring-playbook-bot-maubot.md @@ -51,7 +51,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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**: diff --git a/docs/configuring-playbook-bridge-heisenbridge.md b/docs/configuring-playbook-bridge-heisenbridge.md index f09e9add3..9a96330ff 100644 --- a/docs/configuring-playbook-bridge-heisenbridge.md +++ b/docs/configuring-playbook-bridge-heisenbridge.md @@ -49,7 +49,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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 diff --git a/docs/configuring-playbook-bridge-mautrix-wsproxy.md b/docs/configuring-playbook-bridge-mautrix-wsproxy.md index 48e3a9198..14af101dc 100644 --- a/docs/configuring-playbook-bridge-mautrix-wsproxy.md +++ b/docs/configuring-playbook-bridge-mautrix-wsproxy.md @@ -41,7 +41,7 @@ By default, you will need to create a CNAME record for `wsproxy`. See [Configuri ## 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 diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index 735bf1edd..0607e288e 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -63,7 +63,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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 diff --git a/docs/configuring-playbook-client-cinny.md b/docs/configuring-playbook-client-cinny.md index 680baa1d8..9925c836f 100644 --- a/docs/configuring-playbook-client-cinny.md +++ b/docs/configuring-playbook-client-cinny.md @@ -39,4 +39,4 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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` diff --git a/docs/configuring-playbook-client-element.md b/docs/configuring-playbook-client-element.md index 159072cca..c0f7c348c 100644 --- a/docs/configuring-playbook-client-element.md +++ b/docs/configuring-playbook-client-element.md @@ -66,4 +66,4 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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` diff --git a/docs/configuring-playbook-client-hydrogen.md b/docs/configuring-playbook-client-hydrogen.md index 6ad08c770..7e3aab465 100644 --- a/docs/configuring-playbook-client-hydrogen.md +++ b/docs/configuring-playbook-client-hydrogen.md @@ -39,4 +39,4 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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` diff --git a/docs/configuring-playbook-client-schildichat.md b/docs/configuring-playbook-client-schildichat.md index 6f220ad65..0cf640f6f 100644 --- a/docs/configuring-playbook-client-schildichat.md +++ b/docs/configuring-playbook-client-schildichat.md @@ -65,4 +65,4 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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` diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 93f2c7d51..aca5fdb83 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -73,7 +73,7 @@ By default, you will need to create a CNAME record for `dimension`. See [Configu ## 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 diff --git a/docs/configuring-playbook-etherpad.md b/docs/configuring-playbook-etherpad.md index 18e37c5f4..8a734a739 100644 --- a/docs/configuring-playbook-etherpad.md +++ b/docs/configuring-playbook-etherpad.md @@ -44,7 +44,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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 diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index 3398bf3c1..ac39b3b88 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -284,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 diff --git a/docs/configuring-playbook-matrix-authentication-service.md b/docs/configuring-playbook-matrix-authentication-service.md index b0a0a8d9c..8c2631d40 100644 --- a/docs/configuring-playbook-matrix-authentication-service.md +++ b/docs/configuring-playbook-matrix-authentication-service.md @@ -269,7 +269,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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. diff --git a/docs/configuring-playbook-matrix-registration.md b/docs/configuring-playbook-matrix-registration.md index 974789525..2b89a3eca 100644 --- a/docs/configuring-playbook-matrix-registration.md +++ b/docs/configuring-playbook-matrix-registration.md @@ -52,7 +52,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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 diff --git a/docs/configuring-playbook-ntfy.md b/docs/configuring-playbook-ntfy.md index aedd51b81..48a51da48 100644 --- a/docs/configuring-playbook-ntfy.md +++ b/docs/configuring-playbook-ntfy.md @@ -50,7 +50,7 @@ By default, you will need to create a CNAME record for `ntfy`. See [Configuring ## 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 diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md index 3b0426b07..c92fd1ede 100644 --- a/docs/configuring-playbook-prometheus-grafana.md +++ b/docs/configuring-playbook-prometheus-grafana.md @@ -55,7 +55,7 @@ By default, you will need to create a CNAME record for `stats`. See [Configuring ## 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` ## What does it do? diff --git a/docs/configuring-playbook-rageshake.md b/docs/configuring-playbook-rageshake.md index a9f7f63b6..154949499 100644 --- a/docs/configuring-playbook-rageshake.md +++ b/docs/configuring-playbook-rageshake.md @@ -51,7 +51,7 @@ If you've decided to reuse the `matrix.` domain, you won't need to do any extra ## 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 diff --git a/docs/configuring-playbook-sliding-sync-proxy.md b/docs/configuring-playbook-sliding-sync-proxy.md index 4193547f8..b35fe25ba 100644 --- a/docs/configuring-playbook-sliding-sync-proxy.md +++ b/docs/configuring-playbook-sliding-sync-proxy.md @@ -44,7 +44,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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 diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md index 497c0a709..39d9d3df4 100644 --- a/docs/configuring-playbook-synapse-admin.md +++ b/docs/configuring-playbook-synapse-admin.md @@ -48,8 +48,7 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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 diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index 0c9e19880..8a472f345 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/docs/configuring-playbook-synapse-usage-exporter.md @@ -50,4 +50,4 @@ If you've decided to use the default hostname, you won't need to do any extra DN ## 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` From a6fa33e16c00cfc55285297dce3d124aed79ba3a Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 21 Oct 2024 05:48:02 +0900 Subject: [PATCH 5/5] Update docs/configuring-playbook-alertmanager-receiver.md: fix anchor links Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-alertmanager-receiver.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-alertmanager-receiver.md b/docs/configuring-playbook-alertmanager-receiver.md index 1de72ee21..0e10a5016 100644 --- a/docs/configuring-playbook-alertmanager-receiver.md +++ b/docs/configuring-playbook-alertmanager-receiver.md @@ -69,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), [configured the playbook](#configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), 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).