From 81d76989446ed8c471e06c14748e57d6c8690271 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 21 Oct 2024 05:07:51 +0900 Subject: [PATCH] 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