From 90bb956a2e129057474305a84e2525c557691f37 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 26 Dec 2024 22:22:17 -0500 Subject: [PATCH 01/20] Update configuring-playbook-bridge-appservice-discord.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bridge-appservice-discord.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/configuring-playbook-bridge-appservice-discord.md b/docs/configuring-playbook-bridge-appservice-discord.md index 5368db974..d7ce54893 100644 --- a/docs/configuring-playbook-bridge-appservice-discord.md +++ b/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: From 97a7540e5d0588d95af9d383fa2fd34ecc239a00 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 28 Jan 2025 02:52:16 +0900 Subject: [PATCH 02/20] Update docs/configuring-playbook-bridge-appservice-discord.md: add the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- ...figuring-playbook-bridge-appservice-discord.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/configuring-playbook-bridge-appservice-discord.md b/docs/configuring-playbook-bridge-appservice-discord.md index d7ce54893..a8ad36fc7 100644 --- a/docs/configuring-playbook-bridge-appservice-discord.md +++ b/docs/configuring-playbook-bridge-appservice-discord.md @@ -108,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" #silly, verbose, info, http, warn, error, silent +``` From 811abc09a83980fb46a13046d48fa7375c5be4ee Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 28 Jan 2025 02:54:51 +0900 Subject: [PATCH 03/20] Update files for matrix-appservice-discord: sort the logging levels Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bridge-appservice-discord.md | 2 +- .../matrix-bridge-appservice-discord/templates/config.yaml.j2 | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bridge-appservice-discord.md b/docs/configuring-playbook-bridge-appservice-discord.md index a8ad36fc7..6ea6b88db 100644 --- a/docs/configuring-playbook-bridge-appservice-discord.md +++ b/docs/configuring-playbook-bridge-appservice-discord.md @@ -121,5 +121,5 @@ The default logging level for this component is `warn`. If you want to increase matrix_appservice_discord_configuration_extension_yaml: | logging: # What level should the logger output to the console at. - console: "info" #silly, verbose, info, http, warn, error, silent + console: "info" # Valid values: silent, error, warn, http, info, verbose, silly ``` diff --git a/roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2 b/roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2 index 64f2923cc..a304a4f24 100644 --- a/roles/custom/matrix-bridge-appservice-discord/templates/config.yaml.j2 +++ b/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" From 18983f66031b11896820eceb8c41aaade08d42fc Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 14:29:43 +0900 Subject: [PATCH 04/20] Update docs/configuring-playbook-conduit.md: add the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-conduit.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuring-playbook-conduit.md b/docs/configuring-playbook-conduit.md index 760307b22..be5b46f6a 100644 --- a/docs/configuring-playbook-conduit.md +++ b/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`. From 85b766124975dba1470226466ee41444485d300e Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 14:41:39 +0900 Subject: [PATCH 05/20] Update docs/configuring-playbook-dendrite.md: add the common section "Troubleshooting" See: https://matrix-org.github.io/dendrite/administration/troubleshooting#1-logs Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-dendrite.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/configuring-playbook-dendrite.md b/docs/configuring-playbook-dendrite.md index 83510e7af..7496e918d 100644 --- a/docs/configuring-playbook-dendrite.md +++ b/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 +``` From bd7f35d38392efb1f998d02ac69311a83b778dce Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 29 Dec 2024 10:03:09 -0500 Subject: [PATCH 06/20] Update docs/configuring-playbook-client-cinny.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-client-cinny.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/configuring-playbook-client-cinny.md b/docs/configuring-playbook-client-cinny.md index 4e9decb4f..9e1aabc30 100644 --- a/docs/configuring-playbook-client-cinny.md +++ b/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: From 69c64073726974320a3887cfb9c4ada4bd05f01e Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 18:48:48 +0900 Subject: [PATCH 07/20] Update docs/configuring-playbook-client-cinny.md: adopt the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-client-cinny.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuring-playbook-client-cinny.md b/docs/configuring-playbook-client-cinny.md index 9e1aabc30..2ba895eb9 100644 --- a/docs/configuring-playbook-client-cinny.md +++ b/docs/configuring-playbook-client-cinny.md @@ -61,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`. From 533ab41f7975015a411f287527372b06acffba76 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 29 Dec 2024 10:20:24 -0500 Subject: [PATCH 08/20] Update docs/configuring-playbook-client-hydrogen.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-client-hydrogen.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/configuring-playbook-client-hydrogen.md b/docs/configuring-playbook-client-hydrogen.md index db44e6a62..c99856873 100644 --- a/docs/configuring-playbook-client-hydrogen.md +++ b/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: From f38c69b30bb76efb62fa74e66c7bf34700dda52e Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 19:31:44 +0900 Subject: [PATCH 09/20] Update docs/configuring-playbook-client-hydrogen.md: adopt the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-client-hydrogen.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuring-playbook-client-hydrogen.md b/docs/configuring-playbook-client-hydrogen.md index c99856873..cf9b30335 100644 --- a/docs/configuring-playbook-client-hydrogen.md +++ b/docs/configuring-playbook-client-hydrogen.md @@ -58,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`. From 74b95b57f1d8b78b54f29ff1ad150bd9aef2674a Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 28 Dec 2024 07:51:02 -0500 Subject: [PATCH 10/20] Update docs/configuring-playbook-matrix-media-repo.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-matrix-media-repo.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index 748d3aaf0..0a8302db3 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/docs/configuring-playbook-matrix-media-repo.md @@ -88,7 +88,13 @@ matrix_media_repo_datastore_s3_opts_bucket_name: "your-media-bucket" ``` -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) +### Extending the configuration + +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 ## Signing Keys From 66bb56db1821ac16b7891869eda7e297189eda49 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 26 Jan 2025 03:41:12 +0900 Subject: [PATCH 11/20] Update docs/configuring-playbook-matrix-media-repo.md: add the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-matrix-media-repo.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index 0a8302db3..da4250b0d 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/docs/configuring-playbook-matrix-media-repo.md @@ -167,3 +167,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 +``` From cc3fa496efe5df14ff697d08746be1d350d974f7 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 01:06:59 +0900 Subject: [PATCH 12/20] Update docs/configuring-playbook-matrix-media-repo.md: adopt the common format - Adopt the common introduction - Remove the ToC - Merge sections for additional configuration options and extending the configuration Signed-off-by: Suguru Hirahara --- .../configuring-playbook-matrix-media-repo.md | 38 ++++++++----------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index da4250b0d..b832e4b85 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/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,17 +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" - ``` -### Extending the configuration - -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 - ## 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. From 1242281fa2fca16a2544db2061bec2a840dbbf86 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 28 Dec 2024 09:30:04 -0500 Subject: [PATCH 13/20] Update docs/configuring-playbook-synapse-usage-exporter.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse-usage-exporter.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index e07fc6d0d..59f2b42d1 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/docs/configuring-playbook-synapse-usage-exporter.md @@ -48,6 +48,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: From a67fea982c488d12503255dc7fbd47258f221ab3 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 18:19:51 +0900 Subject: [PATCH 14/20] Update docs/configuring-playbook-synapse-usage-exporter.md: adopt the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse-usage-exporter.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index 59f2b42d1..ca1881667 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/docs/configuring-playbook-synapse-usage-exporter.md @@ -68,3 +68,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`. From 17761aaa876dbb3cd1b7c384df5823d22c957ce6 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 16:35:47 +0900 Subject: [PATCH 15/20] Update docs/configuring-playbook-synapse-usage-exporter.md: adopt the common description for the introduction Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse-usage-exporter.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/configuring-playbook-synapse-usage-exporter.md b/docs/configuring-playbook-synapse-usage-exporter.md index ca1881667..3eb98921f 100644 --- a/docs/configuring-playbook-synapse-usage-exporter.md +++ b/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. From 39066954b3d53254fc647023ba57c958c3747896 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 28 Dec 2024 09:23:34 -0500 Subject: [PATCH 16/20] Update docs/configuring-playbook-synapse-admin.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse-admin.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md index b5e8991bd..0ce5e9d6f 100644 --- a/docs/configuring-playbook-synapse-admin.md +++ b/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: From 57172d85e48c12ea2ae52ba8e0a39887ace2d820 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 15:51:58 +0900 Subject: [PATCH 17/20] Update docs/configuring-playbook-synapse-admin.md: add the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse-admin.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuring-playbook-synapse-admin.md b/docs/configuring-playbook-synapse-admin.md index 0ce5e9d6f..bd07a8bb9 100644 --- a/docs/configuring-playbook-synapse-admin.md +++ b/docs/configuring-playbook-synapse-admin.md @@ -72,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`. From 42694883e6cdb855f6ddbea4a972845b7c04e821 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 31 Jan 2025 00:18:15 +0900 Subject: [PATCH 18/20] Update files for Mjolnir: add the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-mjolnir.md | 14 ++++++++++++++ .../templates/production.yaml.j2 | 5 ++--- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index 2f068e7fa..ec56f345f 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/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" +``` diff --git a/roles/custom/matrix-bot-mjolnir/templates/production.yaml.j2 b/roles/custom/matrix-bot-mjolnir/templates/production.yaml.j2 index 35aac3af4..ec2b0ea28 100644 --- a/roles/custom/matrix-bot-mjolnir/templates/production.yaml.j2 +++ b/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. From 6bd94d860f06e1120d7a9b134ded180b21c5edd9 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 01:29:07 +0900 Subject: [PATCH 19/20] Update docs/configuring-playbook-jitsi.md: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-jitsi.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index b9aca9819..9e976b691 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/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: From 25298cb6966c9f7812eb2a0f07dbbffb57d041c1 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 30 Jan 2025 15:41:48 +0900 Subject: [PATCH 20/20] Update docs/configuring-playbook-sygnal.md: add the common section "Troubleshooting" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-sygnal.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuring-playbook-sygnal.md b/docs/configuring-playbook-sygnal.md index 7ce58714e..9db6ee290 100644 --- a/docs/configuring-playbook-sygnal.md +++ b/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`.