From ddac4fb11022cd6b217be650d890bd8c08f5935e Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 11 Jan 2025 01:01:54 +0900 Subject: [PATCH] Update docs/configuring-playbook-synapse.md: move down the section "Extending the configuration" Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-synapse.md | 38 ++++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md index ce0a4f4ef..ea4433048 100644 --- a/docs/configuring-playbook-synapse.md +++ b/docs/configuring-playbook-synapse.md @@ -2,25 +2,6 @@ By default, this playbook configures the [Synapse](https://github.com/element-hq/synapse) Matrix server, so that it works for the general case. If that's okay, you can skip this document. -## Extending the configuration - -There are some additional things you may wish to configure about the server. - -Take a look at: - -- `roles/custom/matrix-synapse/defaults/main.yml` for some variables that you can customize via your `vars.yml` file -- `roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2` for the server's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_synapse_configuration_extension_yaml` variable - -**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. - -Alternatively, **if there is no pre-defined variable** for a Synapse setting you wish to change: - -- 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 Synapse's various settings that rarely get used. - -- or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. - -- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). - ## Load balancing with workers To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html). @@ -157,6 +138,25 @@ matrix_synapse_container_image_customizations_templates_git_repository_ssh_priva As mentioned in Synapse's Templates documentation, Synapse will fall back to its own templates if a template is not found in that directory. Due to this, it's recommended to only store and maintain template files in your repository if you need to make custom changes. Other files (which you don't need to change), should not be duplicated, so that you don't need to worry about getting out-of-sync with the original Synapse templates. +## Extending the configuration + +There are some additional things you may wish to configure about the server. + +Take a look at: + +- `roles/custom/matrix-synapse/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2` for the server's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_synapse_configuration_extension_yaml` variable + +**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. + +Alternatively, **if there is no pre-defined variable** for a Synapse setting you wish to change: + +- 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 Synapse's various settings that rarely get used. + +- or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. + +- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). + ## Monitoring Synapse Metrics with Prometheus and Grafana This playbook allows you to enable Synapse metrics, which can provide insight into the performance and activity of Synapse.