Merge pull request #4020 from luixxiul/fix

Update docs and config files for various services

docs/configuring-playbook-bot-mjolnir.md

@@ -194,3 +194,17 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 ## Usage
 
 You can refer to the upstream [documentation](https://github.com/matrix-org/mjolnir) for additional ways to use and configure Mjolnir. Check out their [quickstart guide](https://github.com/matrix-org/mjolnir#quickstart-guide) for some basic commands you can give to the bot.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bot-mjolnir`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: ERROR, WARN, INFO, DEBUG
+matrix_bot_mjolnir_configuration_extension_yaml: |
+  logLevel: "DEBUG"
+```

docs/configuring-playbook-bridge-appservice-discord.md

@@ -28,6 +28,15 @@ matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
 #   use_appservice_legacy_authorization: true
 ```
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-appservice-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_discord_configuration_extension_yaml` variable
+
 ## Installing
 
 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@@ -99,3 +108,18 @@ There's the Discord bridge's guide for [setting privileges on bridge managed roo
 docker exec -it matrix-appservice-discord \
 /bin/sh -c 'cp /cfg/registration.yaml /tmp/discord-registration.yaml && cd /tmp && node /build/tools/adminme.js -c /cfg/config.yaml -m "!qporfwt:example.com" -u "@alice:example.com" -p 100'
 ```
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-appservice-discord`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file (adapt to your needs) and re-run the playbook:
+
+```yaml
+matrix_appservice_discord_configuration_extension_yaml: |
+  logging:
+    # What level should the logger output to the console at.
+    console: "info" # Valid values: silent, error, warn, http, info, verbose, silly
+```

docs/configuring-playbook-client-cinny.md

@@ -40,6 +40,15 @@ After changing the domain, **you may need to adjust your DNS** records to point
 
 **Note**: while there is a `matrix_client_cinny_path_prefix` variable for changing the path where Cinny is served, overriding it is [not possible](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3701), because Cinny requires an application rebuild (with a tweaked build config) to be functional under a custom path. You'd need to serve Cinny at a dedicated subdomain.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-cinny/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-cinny/templates/config.json.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_cinny_configuration_extension_json` variable
+
 ## Installing
 
 After configuring the playbook and [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
@@ -52,3 +61,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
 `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-client-cinny`.

docs/configuring-playbook-client-hydrogen.md

@@ -37,6 +37,15 @@ After changing the domain, **you may need to adjust your DNS** records to point
 
 If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the client.
+
+Take a look at:
+
+- `roles/custom/matrix-client-hydrogen/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-hydrogen/templates/config.json.j2` for the client's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_hydrogen_configuration_extension_json` variable
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
@@ -49,3 +58,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
 `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-client-hydrogen`.

docs/configuring-playbook-conduit.md

@@ -75,3 +75,7 @@ Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/ma
     sender_localpart: _bot_signalbot
     url: http://matrix-mautrix-signal:29328
     ```
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-conduit`.

docs/configuring-playbook-dendrite.md

@@ -62,3 +62,18 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
 `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-dendrite`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warning`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_dendrite_configuration_extension_yaml: |
+  logging:
+  - type: std
+    level: debug
+```

docs/configuring-playbook-jitsi.md

@@ -175,6 +175,17 @@ These configurations:
 - **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved
 - **limit the number of video feeds forwarded to each client**, to save up resources on both server and clients. As clients’ bandwidth and CPU may not bear the load, use this setting to avoid lag and crashes. This feature is available by default on other webconference applications such as Office 365 Teams (the number is limited to 4). Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/5ff195985edf46c9399dcf263cb07167f0a2c724/doc/allocation.md).
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- [Jitsi role](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi)'s [`defaults/main.yml`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml) for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using these variables:
+  - `jitsi_web_custom_interface_config_extension`: custom configuration to be appended to `interface_config.js`, passed to Jitsi Web
+  - `jitsi_web_custom_config_extension`: custom configuration to be injected into `custom-config.js`, passed to Jitsi Web
+  - `jitsi_jvb_custom_config_extension`: custom configuration to be injected into `custom-sip-communicator.properties`, passed to Jitsi JVB
+
 ### Example configurations
 
 Here is an example set of configurations for running a Jitsi instance with:

docs/configuring-playbook-matrix-media-repo.md

@@ -1,20 +1,18 @@
 # Storing Matrix media files using matrix-media-repo (optional)
 
-[matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/) (often abbreviated "MMR") is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
+The playbook can install and configure [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/) (often abbreviated "MMR") for you.
 
-Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
+MMR is a highly customizable multi-domain media repository for Matrix. Intended for medium to large environments consisting of several homeservers, this media repo de-duplicates media (including remote media) while being fully compliant with the specification.
 
-For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
+**Notes**:
 
-| **Table of Contents**                                                                       |
-| :------------------------------------------------------------------------------------------ |
-| [Quickstart](#quickstart)                                                                   |
-| [Additional configuration options](#configuring-the-media-repo)                             |
-| [Importing data from an existing media store](#importing-data-from-an-existing-media-store) |
+- Smaller/individual homeservers can still make use of this project's features, though it may be difficult to set up or have higher than expected resource consumption. Please do your research before deploying this as this project may not be useful for your environment.
 
-## Quickstart
+- For a simpler alternative (which allows you to offload your media repository storage to S3, etc.), you can [configure S3 storage](configuring-playbook-s3.md) instead of setting up matrix-media-repo.
 
-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:
+## Adjusting the playbook configuration
+
+To enable matrix-media-repo, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
 matrix_media_repo_enabled: true
@@ -27,12 +25,17 @@ The repo is pre-configured for integrating with the Postgres database, Traefik p
 
 By default, the media-repo will use the local filesystem for data storage. You can alternatively use a `s3` cloud backend as well. Access token caching is also enabled by default since the logout endpoints are proxied through the media repo.
 
-## Configuring the media-repo
+### Extending the configuration
 
-Additional common configuration options:
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-media-repo/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+Here is a list of additional common configuration options:
 
 ```yaml
-
 # The postgres database pooling options
 
 # The maximum number of connects to hold open. More of these allow for more concurrent
@@ -85,11 +88,8 @@ matrix_media_repo_datastore_s3_opts_bucket_name: "your-media-bucket"
 # An optional storage class for tuning how the media is stored at s3.
 # See https://aws.amazon.com/s3/storage-classes/ for details; uncomment to use.
 # matrix_media_repo_datastore_s3_opts_storage_class: "STANDARD"
-
 ```
 
-Full list of configuration options with documentation can be found in [`roles/custom/matrix-media-repo/defaults/main.yml`](../roles/custom/matrix-media-repo/defaults/main.yml)
-
 ## Signing Keys
 
 Authenticated media endpoints ([MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916)) requires MMR to have a configured signing key to authorize outbound federation requests. Additionally, the signing key must be merged with your homeserver's signing key file.
@@ -161,3 +161,15 @@ docker exec -it matrix-media-repo \
 Enter `1` for the Machine ID when prompted (you are not doing any horizontal scaling) unless you know what you're doing.
 
 This should output a `msg="Import completed"` when finished successfully!
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-media-repo`.
+
+### Increase logging verbosity
+
+If you want to turn on sentry's built-in debugging, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_media_repo_sentry_debug: true
+```

docs/configuring-playbook-sygnal.md

@@ -100,3 +100,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 To make use of your Sygnal installation, you'd need to build your own Matrix client application, which uses the same API keys (for [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/)) and certificates (for [APNS](https://developer.apple.com/notifications/)) and is to your Sygnal URL endpoint (e.g. `https://sygnal.example.com`).
 
 Refer to Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) document.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-sygnal`.

docs/configuring-playbook-synapse-admin.md

@@ -46,6 +46,14 @@ If you've changed the default hostname, you may need to create a CNAME record fo
 
 When setting, replace `example.com` with your own.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-synapse-admin/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_synapse_admin_configuration_extension_json` variable
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
@@ -64,3 +72,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 After installation, Synapse Admin will be accessible at: `https://matrix.example.com/synapse-admin/`
 
 To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-synapse-admin`.

docs/configuring-playbook-synapse-usage-exporter.md

@@ -1,6 +1,8 @@
 # Enabling synapse-usage-exporter for Synapse usage statistics (optional)
 
-[synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) allows you to export the usage statistics of a Synapse homeserver to this container service and for the collected metrics to later be scraped by Prometheus.
+The playbook can install and configure [synapse-usage-exporter](https://github.com/loelkes/synapse-usage-exporter) for you.
+
+It allows you to export the usage statistics of a Synapse homeserver to this container service and for the collected metrics to later be scraped by Prometheus.
 
 Synapse does not include usage statistics in its Prometheus metrics. They can be reported to an HTTP `PUT` endpoint 5 minutes after startup and from then on at a fixed interval of once every three hours. This role integrates a simple [Flask](https://flask.palletsprojects.com) project that offers an HTTP `PUT` endpoint and holds the most recent received record available to be scraped by Prometheus.
 
@@ -11,6 +13,8 @@ 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
 
+See the project's [documentation](https://github.com/loelkes/synapse-usage-exporter/blob/main/README.md) to learn what it does and why it might be useful to you.
+
 ## Adjusting DNS records (optional)
 
 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.
@@ -48,6 +52,14 @@ If you've changed the default hostname, you may need to create a CNAME record fo
 
 When setting, replace `example.com` with your own.
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-synapse-usage-exporter/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
 ## Installing
 
 After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
@@ -60,3 +72,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
 
 `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-synapse-usage-exporter`.

roles/custom/matrix-bot-mjolnir/templates/production.yaml.j2

@@ -57,10 +57,9 @@ managementRoom: {{ matrix_bot_mjolnir_management_room | to_json }}
 # mainly involves "all-OK" messages, and debugging messages for when mjolnir checks bans in a room.
 verboseLogging: false
 
-# The log level of terminal (or container) output,
-# can be one of DEBUG, INFO, WARN and ERROR, in increasing order of importance and severity.
+# The log level of terminal (or container) output.
 #
-# This should be at INFO or DEBUG in order to get support for Mjolnir problems.
+# Valid values: ERROR, WARN, INFO, DEBUG
 logLevel: "INFO"
 
 # Whether or not Mjolnir should synchronize policy lists immediately after startup.

roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2

@@ -48,7 +48,7 @@ auth:
   usePrivilegedIntents: {{ matrix_appservice_discord_auth_usePrivilegedIntents|to_json }}
 logging:
   # What level should the logger output to the console at.
-  console: "warn" #silly, verbose, info, http, warn, error, silent
+  console: "warn" # Valid values: silent, error, warn, http, info, verbose, silly
   lineDateFormat: "MMM-D HH:mm:ss.SSS" # This is in moment.js format
   # files:
   #   - file: "debug.log"