Make Synapse configuration extensible

This commit is contained in:
Slavi Pantaleev 2019-08-22 09:49:22 +03:00
parent b440d5b73c
commit 10a9deba4a
5 changed files with 69 additions and 2 deletions

View file

@ -1,3 +1,18 @@
# 2019-08-22
## Extensible Synapse configuration
Previously, we had to create custom Ansible variables for each and every Synapse setting.
This lead to too much effort (and configuration ugliness) to all of Synapse's settings, so naturally, not all features of Synapse could be controlled through the playbook.
From now on, you can extend/override the Synapse server's configuration by making use of the `matrix_synapse_configuration_extension_yaml` variable.
This should be enough for most customization needs.
If you need even more power, you can now also take full control and override `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`) directly.
Learn more here in [Configuring Synapse](docs/configuring-playbook-synapse.md).
# 2019-08-21 # 2019-08-21
## Slack bridging support ## Slack bridging support

View file

@ -0,0 +1,18 @@
# Configuring Synapse (optional)
By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, so that it works for the general case.
If that's enough for you, you can skip this document.
The playbook provides lots of customization variables you could use to change Synapse's settings.
Their defaults are defined in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml) and they ultimately end up in the generated `/matrix/synapse/config/homeserver.yaml` file (on the server). This file is generated from the [`roles/matrix-synapse/templates/synapse/homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.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.<your-domain>/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/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).
- 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`). You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).

View file

@ -34,6 +34,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
### Core service adjustments ### Core service adjustments
- [Configuring Synapse](configuring-playbook-synapse.md) (optional)
- [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional) - [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional)
- [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) (optional) - [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) (optional)

View file

@ -295,3 +295,33 @@ matrix_synapse_room_list_publication_rules:
action: allow action: allow
matrix_synapse_default_room_version: "4" matrix_synapse_default_room_version: "4"
# Default Synapse configuration template which covers the generic use case.
# You can customize it by controlling the various variables inside it.
#
# For a more advanced customization, you can extend the default (see `matrix_synapse_configuration_extension_yaml`)
# or completely replace this variable with your own template.
matrix_synapse_configuration_yaml: "{{ lookup('template', 'templates/synapse/homeserver.yaml.j2') }}"
matrix_synapse_configuration_extension_yaml: |
# Your custom YAML configuration for Synapse goes here.
# This configuration extends the default starting configuration (`matrix_synapse_configuration_yaml`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# completely redefining `matrix_synapse_configuration_yaml`.
#
# Example configuration extension follows:
#
# server_notices:
# system_mxid_localpart: notices
# system_mxid_display_name: "Server Notices"
# system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ"
# room_name: "Server Notices"
matrix_synapse_configuration_extension: "{{ matrix_synapse_configuration_extension_yaml|from_yaml if matrix_synapse_configuration_extension_yaml|from_yaml is mapping else {} }}"
# Holds the final Synapse configuration (a combination of the default and its extension).
# You most likely don't need to touch this variable. Instead, see `matrix_synapse_configuration_yaml`.
matrix_synapse_configuration: "{{ matrix_synapse_configuration_yaml|from_yaml|combine(matrix_synapse_configuration_extension, recursive=True) }}"

View file

@ -53,10 +53,12 @@
when: "not matrix_synapse_signing_key_stat.stat.exists" when: "not matrix_synapse_signing_key_stat.stat.exists"
- name: Ensure Synapse homeserver config installed - name: Ensure Synapse homeserver config installed
template: copy:
src: "{{ matrix_synapse_template_synapse_homeserver }}" content: "{{ matrix_synapse_configuration|to_nice_yaml }}"
dest: "{{ matrix_synapse_config_dir_path }}/homeserver.yaml" dest: "{{ matrix_synapse_config_dir_path }}/homeserver.yaml"
mode: 0644 mode: 0644
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_username }}"
- name: Ensure Synapse log config installed - name: Ensure Synapse log config installed
template: template: