diff --git a/docs/configuring-playbook-appservice-double-puppet.md b/docs/configuring-playbook-appservice-double-puppet.md index 38b5b05b1..0c0f7077e 100644 --- a/docs/configuring-playbook-appservice-double-puppet.md +++ b/docs/configuring-playbook-appservice-double-puppet.md @@ -4,7 +4,7 @@ Appservice Double Puppet is a homeserver appservice through which bridges (and p This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the [appservice method](https://docs.mau.fi/bridges/general/double-puppeting.html#appservice-method-new). The Appservice Double Puppet service is an implementation of this approach. -Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method. +Previously, bridges supported performing double-puppeting with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method. ## Adjusting the playbook configuration diff --git a/docs/configuring-playbook-backup-borg.md b/docs/configuring-playbook-backup-borg.md index dba51e905..2f93b0245 100644 --- a/docs/configuring-playbook-backup-borg.md +++ b/docs/configuring-playbook-backup-borg.md @@ -10,8 +10,6 @@ The backup will run based on `backup_borg_schedule` var (systemd timer calendar) By default, if you're using the integrated Postgres database server (as opposed to [an external Postgres server](configuring-playbook-external-postgres.md)), backups with BorgBackup will also include dumps of your Postgres database. An alternative solution for backing up the Postgres database is [postgres backup](configuring-playbook-postgres-backup.md). If you decide to go with another solution, you can disable Postgres-backup support for BorgBackup using the `backup_borg_postgresql_enabled` variable. -**Note**: the component is not managed by this repository but its [own repository](https://github.com/mother-of-all-self-hosting/ansible-role-backup_borg). - ## Prerequisites 1. If you do not disable Postgres-backup support, make sure that the Postgres version of your homeserver's database is compatible with borgmatic. diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 3863b616b..bce4de3fc 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -36,7 +36,7 @@ If your homeserver's implementation is Synapse, you will need to prevent it from This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally. -To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. +To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index e7737420b..d79f085b5 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -32,7 +32,7 @@ If your homeserver's implementation is Synapse, you will need to prevent it from This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally. -To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. +To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true diff --git a/docs/configuring-playbook-bridge-heisenbridge.md b/docs/configuring-playbook-bridge-heisenbridge.md index 919939423..0b440547f 100644 --- a/docs/configuring-playbook-bridge-heisenbridge.md +++ b/docs/configuring-playbook-bridge-heisenbridge.md @@ -6,7 +6,7 @@ The playbook can install and configure [Heisenbridge](https://github.com/hifi/he See the project's [documentation](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I). -## Configuration +## Adjusting the playbook configuration To enable Heisenbridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: diff --git a/docs/configuring-playbook-bridge-matrix-bridge-sms.md b/docs/configuring-playbook-bridge-matrix-bridge-sms.md index e6a9e963e..7f58a74cd 100644 --- a/docs/configuring-playbook-bridge-matrix-bridge-sms.md +++ b/docs/configuring-playbook-bridge-matrix-bridge-sms.md @@ -4,7 +4,9 @@ The playbook can install and configure [matrix-sms-bridge](https://github.com/be See the project's [documentation](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md) to learn what it does and why it might be useful to you. -**The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.** +## Prerequisite + +The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first. ## Adjusting the playbook configuration diff --git a/docs/configuring-playbook-bridge-mautrix-facebook.md b/docs/configuring-playbook-bridge-mautrix-facebook.md index 8baf793b9..a0d55b62b 100644 --- a/docs/configuring-playbook-bridge-mautrix-facebook.md +++ b/docs/configuring-playbook-bridge-mautrix-facebook.md @@ -76,7 +76,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html). +Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. If you run into trouble, check the [Troubleshooting](#troubleshooting) section below. diff --git a/docs/configuring-playbook-bridge-mautrix-instagram.md b/docs/configuring-playbook-bridge-mautrix-instagram.md index 9d3c4be5e..0e16c7eba 100644 --- a/docs/configuring-playbook-bridge-mautrix-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-instagram.md @@ -64,5 +64,3 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account. - -You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/instagram/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-signal.md b/docs/configuring-playbook-bridge-mautrix-signal.md index f89ca1c42..b925a2bc2 100644 --- a/docs/configuring-playbook-bridge-mautrix-signal.md +++ b/docs/configuring-playbook-bridge-mautrix-signal.md @@ -4,8 +4,6 @@ The playbook can install and configure [mautrix-signal](https://github.com/mautr See the project's [documentation](https://docs.mau.fi/bridges/python/signal/index.html) to learn what it does and why it might be useful to you. -**Note**: This revamped version of the [mautrix-signal (legacy)](configuring-playbook-bridge-mautrix-signal.md) may increase the CPU usage of your homeserver. - ## Prerequisites (optional) ### Prepare Postgres database on external Postgres server diff --git a/docs/configuring-playbook-bridge-mautrix-telegram.md b/docs/configuring-playbook-bridge-mautrix-telegram.md index fc775f61c..c48820b38 100644 --- a/docs/configuring-playbook-bridge-mautrix-telegram.md +++ b/docs/configuring-playbook-bridge-mautrix-telegram.md @@ -4,7 +4,13 @@ The playbook can install and configure [mautrix-telegram](https://github.com/mau See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/index.html) to learn what it does and why it might be useful to you. -## Prerequisite (optional) +## Prerequisites + +### Obtain a Telegram API key + +To use the bridge, you'd need to obtain an API key from [https://my.telegram.org/apps](https://my.telegram.org/apps). + +### Enable Appservice Double Puppet or Shared Secret Auth (optional) If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. @@ -12,7 +18,7 @@ For details about configuring Double Puppeting for this bridge, see the section ## Adjusting the playbook configuration -You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `YOUR_TELEGRAM_APP_ID` and `YOUR_TELEGRAM_API_HASH`. ```yaml matrix_mautrix_telegram_enabled: true diff --git a/docs/configuring-playbook-bridge-mautrix-wsproxy.md b/docs/configuring-playbook-bridge-mautrix-wsproxy.md index dbc4c5ea3..9a057391e 100644 --- a/docs/configuring-playbook-bridge-mautrix-wsproxy.md +++ b/docs/configuring-playbook-bridge-mautrix-wsproxy.md @@ -58,4 +58,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage -Follow the [matrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s). +Follow the [mautrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s). diff --git a/docs/configuring-playbook-bridge-wechat.md b/docs/configuring-playbook-bridge-wechat.md index f39c4a867..0016cbdd9 100644 --- a/docs/configuring-playbook-bridge-wechat.md +++ b/docs/configuring-playbook-bridge-wechat.md @@ -1,6 +1,6 @@ # Setting up WeChat bridging (optional) -The playbook can install and configure the [matrix-wechat](https://github.com/duo/matrix-wechat) bridge for you (for bridging to the [WeChat](https://www.wechat.com/) network). +The playbook can install and configure [matrix-wechat](https://github.com/duo/matrix-wechat) for you, for bridging to [WeChat](https://www.wechat.com/). See the project's [documentation](https://github.com/duo/matrix-wechat/blob/master/README.md) to learn what it does and why it might be useful to you. @@ -31,6 +31,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage -Once the bridge is installed, start a chat with `@wechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). +To use the bridge, you need to start a chat with `@wechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Send `help` to the bot to see the available commands. diff --git a/docs/configuring-playbook-cactus-comments.md b/docs/configuring-playbook-cactus-comments.md index b39387d86..f890b9775 100644 --- a/docs/configuring-playbook-cactus-comments.md +++ b/docs/configuring-playbook-cactus-comments.md @@ -14,7 +14,7 @@ The playbook contains 2 roles for configuring different pieces of the Cactus Com You can enable whichever component you need (typically both). -## Configuration +## Adjusting the playbook configuration To enable Cactus Comments, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: diff --git a/docs/configuring-playbook-dendrite.md b/docs/configuring-playbook-dendrite.md index 441872d73..00bde90b4 100644 --- a/docs/configuring-playbook-dendrite.md +++ b/docs/configuring-playbook-dendrite.md @@ -18,7 +18,7 @@ matrix_homeserver_implementation: dendrite The playbook provides lots of customization variables you could use to change Dendrite's settings. -Their defaults are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2) template. +Their defaults are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite.yaml.j2) template. **If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes. @@ -26,7 +26,7 @@ Alternatively, **if there is no pre-defined variable** for a Dendrite setting yo - you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Dendrite's various settings that rarely get used. -- or, you can **extend and override the default configuration** ([`dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2)) by making use of the `matrix_dendrite_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml). +- or, you can **extend and override the default configuration** ([`dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite.yaml.j2)) by making use of the `matrix_dendrite_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml). - or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml). diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 1c4fd99f9..3fa0ea688 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -38,7 +38,7 @@ Dimension requires an access token to be able to connect to your homeserver. Ref ## Adjusting the playbook configuration -To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`). Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token). +To enable Dimension, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token). ```yaml matrix_dimension_enabled: true @@ -48,7 +48,7 @@ matrix_dimension_access_token: "ACCESS_TOKEN_HERE" ### 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`): +To define admin users who can modify the integrations this Dimension supports, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_dimension_admins: diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index 86a1052b2..619dfd2c3 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/devture/email2matrix/blob/m ## Preparation -### DNS configuration +## Adjusting DNS records It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.example.com`, as described in the [Configuring DNS](configuring-dns.md) documentation page. diff --git a/docs/configuring-playbook-federation.md b/docs/configuring-playbook-federation.md index 6be892314..3bf9ecc70 100644 --- a/docs/configuring-playbook-federation.md +++ b/docs/configuring-playbook-federation.md @@ -20,7 +20,7 @@ If you wish to disable federation, you can do that with an empty list (`[]`), or By default, your server's public rooms directory is not exposed to other servers via federation. -If you wish to expose it, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`): +To expose it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_allow_public_rooms_over_federation: true @@ -28,7 +28,7 @@ matrix_synapse_allow_public_rooms_over_federation: true ## Disabling federation -To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`): +To completely disable federation, isolating your server from the rest of the Matrix network, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_homeserver_federation_enabled: false @@ -52,7 +52,7 @@ matrix_synapse_reverse_proxy_companion_federation_api_enabled: false Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection. -The following changes in the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other: +To make it possible to proxy the federation through a CDN such as CloudFlare or any other, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_http_listener_resource_names: ["client","federation"] diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index 69b93906b..29ded06b4 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -68,7 +68,7 @@ jitsi_prosody_auth_internal_accounts: password: "another-password" ``` -**Caution**: Accounts added here and subsequently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook. +⚠️ **Warning**: Accounts added here and subsequently removed will not be automatically removed from the Prosody server until user account cleaning is integrated into the playbook. **If you get an error** like this: "Error: Account creation/modification not supported.", it's likely that you had previously installed Jitsi without auth/guest support. In such a case, you should look into [Rebuilding your Jitsi installation](#rebuilding-your-jitsi-installation). @@ -263,7 +263,7 @@ To enable Gravatar set: jitsi_disable_gravatar: false ``` -**Beware**: This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com). Besides metadata, this includes the Matrix user_id and possibly the room identifier (via `referrer` header). +⚠️ **Warning**: This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com). Besides metadata, this includes the Matrix user_id and possibly the room identifier (via `referrer` header). ## Installing diff --git a/docs/configuring-playbook-ldap-auth.md b/docs/configuring-playbook-ldap-auth.md index 8d11ac577..d3a95d138 100644 --- a/docs/configuring-playbook-ldap-auth.md +++ b/docs/configuring-playbook-ldap-auth.md @@ -29,9 +29,11 @@ If you wish for users to **authenticate only against configured password provide matrix_synapse_password_config_localdb_enabled: false ``` -## Using ma1sd Identity Server for authentication +## Using ma1sd Identity Server for authentication (not recommended) -If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication). +The playbook can instead configure [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for LDAP authentication. However, **we recommend not bothering with installing it** as ma1sd has been unmaintained for years. + +If you wish to install it anyway, consult the [ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication). ## Handling user registration diff --git a/docs/configuring-playbook-matrix-corporal.md b/docs/configuring-playbook-matrix-corporal.md index ef9ab2d1b..622d4b59d 100644 --- a/docs/configuring-playbook-matrix-corporal.md +++ b/docs/configuring-playbook-matrix-corporal.md @@ -2,7 +2,7 @@
-**WARNING**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't. +⚠️ **Warning**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't.
diff --git a/docs/configuring-playbook-matrix-registration.md b/docs/configuring-playbook-matrix-registration.md index 4a1eeeaf5..edc8a1ea1 100644 --- a/docs/configuring-playbook-matrix-registration.md +++ b/docs/configuring-playbook-matrix-registration.md @@ -1,14 +1,12 @@ # Setting up matrix-registration (optional) -The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you. +⚠️ **Warnings**: +- This is a poorly maintained and buggy project. It's better to avoid using it. +- This is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) -**WARNING**: this is a poorly maintained and buggy project. It's better to avoid using it. +The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you. It is a simple python application to have a token based Matrix registration. -**WARNING**: this is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) - -> matrix-registration is a simple python application to have a token based Matrix registration. - -Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows you to **keep your server's registration closed (private)**, but still allow certain people (these having a special link) to register a user account. +Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows certain people (these having a special link) to register a user account, **keeping your server's registration closed (private)**. **matrix-registration** provides 2 things: diff --git a/docs/configuring-playbook-mautrix-bridges.md b/docs/configuring-playbook-mautrix-bridges.md index 6b86863bf..ca238790a 100644 --- a/docs/configuring-playbook-mautrix-bridges.md +++ b/docs/configuring-playbook-mautrix-bridges.md @@ -30,7 +30,7 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: | '@alice:{{ matrix_domain }}': admin ``` -## encryption +### Encryption Encryption support is off by default. If you would like to enable encryption, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -48,7 +48,7 @@ matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true matrix_mautrix_SERVICENAME_bridge_encryption_default: true ``` -## relay mode +### Relay mode Relay mode is off by default. If you would like to enable relay mode, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -79,7 +79,7 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: | default: true ``` -## Setting the bot's username +### Setting the bot's username ```yaml matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME" @@ -87,7 +87,7 @@ matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME" Can be used to set the username for the bridge. -## Discovering additional configuration options +### Extending the configuration You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure. diff --git a/docs/configuring-playbook-prometheus-nginxlog.md b/docs/configuring-playbook-prometheus-nginxlog.md index ed90cb0aa..1683210c3 100644 --- a/docs/configuring-playbook-prometheus-nginxlog.md +++ b/docs/configuring-playbook-prometheus-nginxlog.md @@ -12,7 +12,7 @@ To make use of this, you need to install [Prometheus](./configuring-playbook-pro If your setup includes [Grafana](./configuring-playbook-prometheus-grafana.md), a dedicated `NGINX PROXY` Grafana dashboard will be created. -## Configuration +## Adjusting the playbook configuration Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: diff --git a/docs/configuring-playbook-rageshake.md b/docs/configuring-playbook-rageshake.md index 88bc3fd61..8847811ef 100644 --- a/docs/configuring-playbook-rageshake.md +++ b/docs/configuring-playbook-rageshake.md @@ -2,7 +2,9 @@ The playbook can install and configure the [rageshake](https://github.com/matrix-org/rageshake) bug report server for you. -This is useful if you're developing your own applications and would like to collect bug reports for them. +See the project's [documentation](https://github.com/matrix-org/rageshake/blob/main/README.md) to learn what it does and why it might be useful to you. + +**Note**: most people don't need to install rageshake to collect bug reports. This component is only useful to people who develop/build their own Matrix client applications themselves. ## Adjusting the playbook configuration @@ -64,4 +66,4 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju ## Usage -Refer to the [rageshake documentation](https://github.com/matrix-org/rageshake) for available APIs, etc. +Refer to the project's [documentation](https://github.com/matrix-org/rageshake/blob/main/README.md) for available APIs, etc. diff --git a/docs/configuring-playbook-synapse-auto-accept-invite.md b/docs/configuring-playbook-synapse-auto-accept-invite.md index c117346f8..52c1c46ae 100644 --- a/docs/configuring-playbook-synapse-auto-accept-invite.md +++ b/docs/configuring-playbook-synapse-auto-accept-invite.md @@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/matrix-org/synapse-auto-acc **Note**: Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the same feature [has been merged](https://github.com/element-hq/synapse/pull/17147) into Synapse (see the [Native alternative](#native-alternative) section below). You'd better use the native feature, instead of the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module. -## Configuration +## Adjusting the playbook configuration If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: diff --git a/docs/configuring-playbook-synapse-s3-storage-provider.md b/docs/configuring-playbook-synapse-s3-storage-provider.md index 82af9574d..05b6debb2 100644 --- a/docs/configuring-playbook-synapse-s3-storage-provider.md +++ b/docs/configuring-playbook-synapse-s3-storage-provider.md @@ -21,7 +21,7 @@ You can run some scripts to delete the local files once in a while (which we do While you will need some local disk space around, it's only to accommodate usage, etc., and won't grow as large as your S3 store. -## Installing +## Adjusting the playbook configuration After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`): diff --git a/docs/configuring-playbook-telemetry.md b/docs/configuring-playbook-telemetry.md index cb144ee1c..111a27da7 100644 --- a/docs/configuring-playbook-telemetry.md +++ b/docs/configuring-playbook-telemetry.md @@ -4,7 +4,7 @@ By default, this playbook configures your Matrix homeserver to not send any tele The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting usage statistics from your homeserver. Enabling usage statistics helps track the growth of the Matrix community, and helps to make Matrix a success. -## Enabling Telemetry +## Adjusting the playbook configuration If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: diff --git a/docs/configuring-playbook-traefik.md b/docs/configuring-playbook-traefik.md index 9032ed1cf..66d6b1aee 100644 --- a/docs/configuring-playbook-traefik.md +++ b/docs/configuring-playbook-traefik.md @@ -34,7 +34,7 @@ traefik_dashboard_basicauth_user: YOUR_USERNAME_HERE traefik_dashboard_basicauth_password: YOUR_PASSWORD_HERE ``` -**WARNING**: Enabling the dashboard on a hostname you use for something else (like `matrix_server_fqn_matrix` in the configuration above) may cause conflicts. Enabling the Traefik Dashboard makes Traefik capture all `/dashboard` and `/api` requests and forward them to itself. If any of the services hosted on the same hostname requires any of these 2 URL prefixes, you will experience problems. So far, we're not aware of any playbook services which occupy these endpoints and are likely to cause conflicts. +⚠️ **Warning**: Enabling the dashboard on a hostname you use for something else (like `matrix_server_fqn_matrix` in the configuration above) may cause conflicts. Enabling the Traefik Dashboard makes Traefik capture all `/dashboard` and `/api` requests and forward them to itself. If any of the services hosted on the same hostname requires any of these 2 URL prefixes, you will experience problems. So far, we're not aware of any playbook services which occupy these endpoints and are likely to cause conflicts. ## Additional configuration @@ -134,7 +134,7 @@ Changing the `url` to one with an `http://` prefix would allow to connect to the With these changes, all TCP traffic will be reverse-proxied to the target system. -**WARNING**: This configuration might lead to problems or need additional steps when a [certbot](https://certbot.eff.org/) behind Traefik also tries to manage [Let's Encrypt](https://letsencrypt.org/) certificates, as Traefik captures all traffic to ```PathPrefix(`/.well-known/acme-challenge/`)```. +⚠️ **Warning**: This configuration might lead to problems or need additional steps when a [certbot](https://certbot.eff.org/) behind Traefik also tries to manage [Let's Encrypt](https://letsencrypt.org/) certificates, as Traefik captures all traffic to ```PathPrefix(`/.well-known/acme-challenge/`)```. ## Traefik behind a `proxy_protocol` reverse-proxy diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 1b1de3c50..78d664a89 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -26,6 +26,8 @@ For a more custom setup, see the [Other configuration options](#other-configurat ## Other configuration options +**Note**: some of the roles like one for integrating Etherpad or Jitsi are managed by their own repositories, and the configuration files for them cannot be found locally (in `roles/galaxy`) until those roles are fetched from the upstream projects. Check [requirements.yml](../requirements.yml) for the URLs of those roles. + ### Core service adjustments - Homeserver configuration: diff --git a/docs/howto-srv-server-delegation.md b/docs/howto-srv-server-delegation.md index f4b028b0b..ba74d38ac 100644 --- a/docs/howto-srv-server-delegation.md +++ b/docs/howto-srv-server-delegation.md @@ -14,7 +14,7 @@ This means that this is **limited to the list of DNS providers supported by Trae The up-to-date list can be accessed on [traefik's documentation](https://doc.traefik.io/traefik/https/acme/#providers) -## The changes +## Adjusting the playbook configuration **Note**: the changes below instruct you how to do this for a basic Synapse installation. You will need to adapt the variable name and the content of the labels: @@ -91,7 +91,7 @@ By default, Coturn is configured to wait on the certificate for the `matrix.` su We also need to indicate to Coturn where the wildcard certificate is. -**⚠️ WARNING ⚠️** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`). +⚠️ **Warning** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`). This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the Coturn service is setup to restart periodically. diff --git a/docs/maintenance-and-troubleshooting.md b/docs/maintenance-and-troubleshooting.md index 673c89859..0ab46f900 100644 --- a/docs/maintenance-and-troubleshooting.md +++ b/docs/maintenance-and-troubleshooting.md @@ -22,7 +22,7 @@ To view systemd-journald logs using [journalctl](https://man.archlinux.org/man/j sudo journalctl -fu matrix-synapse ``` -## Increasing Synapse logging +## Increase logging verbosity Because the [Synapse](https://github.com/element-hq/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`. @@ -51,7 +51,3 @@ The shortcut command with `just` program is also available: `just run-tags run-d ## Postgres See the dedicated [PostgreSQL Maintenance](maintenance-postgres.md) documentation page. - -## Ma1sd - -See the dedicated [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md) documentation page. diff --git a/docs/uninstalling.md b/docs/uninstalling.md index 717037cee..14c8c211f 100644 --- a/docs/uninstalling.md +++ b/docs/uninstalling.md @@ -1,9 +1,7 @@ # Uninstalling -**Warnings**: - +⚠️ **Warnings**: - If your server federates with others, make sure to **leave any federated rooms before nuking your Matrix server's data**. Otherwise, the next time you set up a Matrix server for this domain (regardless of the installation method you use), you'll encounter trouble federating. - - If you have some trouble with your installation, you can just [re-run the playbook](installing.md) and it will try to set things up again. **Uninstalling and then installing anew rarely solves anything**. -----------------