From c721447e14cbbbd53c94586b65ff8aa3c94075a7 Mon Sep 17 00:00:00 2001 From: Stonewall Jackson Date: Thu, 1 Jun 2023 08:57:59 -0400 Subject: synapse: add readme --- roles/synapse/README.md | 122 +++++++++++++++++++++ .../templates/var/lib/synapse/homeserver.yaml.j2 | 2 + 2 files changed, 124 insertions(+) create mode 100644 roles/synapse/README.md diff --git a/roles/synapse/README.md b/roles/synapse/README.md new file mode 100644 index 0000000..3276e72 --- /dev/null +++ b/roles/synapse/README.md @@ -0,0 +1,122 @@ +Synapse +====== + +Description +----------- + +The `synapse` role installs and configures the [synapse](https://github.com/matrix-org/synapse/) +[Matrix](https://matrix.org/) homeserver. + +Users authenticate against the local FreeIPA domain using +the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) plugin. +The Matrix username for each user is taken from the `matrixUsername` attribute +of the FreeIPA User object. + +If your Matrix domain differs from the public hostname of your synapse server +(e.g. your MXIDs have the format `@user:example.com`, but synapse runs on +`matrix.example.com`), then you will need to configure `.well-known` delegation +in order to federate with other instances. See the [sample webserver playbook](../../playbooks/webserver_public_example.yml) +for an example of how to do this. + + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +-------------------------------------|----------------------------------------------|------------ +`synapse_version` | see [defaults](defaults/main.yml) | [synapse](https://github.com/matrix-org/synapse/) version to install +`synapse_ldap_version` | see [defaults](defaults/main.yml) | [synapse ldap](https://github.com/matrix-org/matrix-synapse-ldap3) plugin version to install +`synapse_element_version` | see [defaults](defaults/main.yml) | [element-web](https://github.com/vector-im/element-web) version to install +`synapse_domain` | `{{ email_domain }}` | Matrix domain served by the homeserver +`synapse_server_name` | `{{ ansible_fqdn }}` | Public hostname of the homeserver +`synapse_local_client_port` | 8008 | Localhost listen port for client traffic +`synapse_local_federation_port` | 8009 | Localhost listen port for federation traffic +`synapse_client_port` | 8443 | Public listen port for client traffic +`synapse_federation_port` | 8448 | Public listen port for federation traffic +`synapse_user` | `s-synapse` | FreeIPA user (will be created) +`synapse_access_group` | `role-matrix-access` | FreeIPA group for Matrix users (will be created) +`synapse_db_host` | `{{ postgresql_host }}` | PostgreSQL host +`synapse_db_name` | `synapse` | PostgreSQL database (will be created) +`synapse_sysaccount_username` | `synapse` | FreeIPA [system account](../freeipa_system_account/) username +`synapse_sysaccount_password` |   | FreeIPA [system account](../freeipa_system_account/) password +`synapse_registration_shared_secret` |   | Secret passphrase to allow registration even when disabled (optional) +`synapse_macaroon_secret_key` |   | Secret signing key for various tokens (required) +`synapse_form_secret` |   | Secret key for various form HMACs (required) +`synapse_turn_host` | `{{ coturn_realm }}` | TURN server hostname +`synapse_turn_secret` | `{{ coturn_auth_secret }}` | TURN server shared secret +`synapse_enable_email_notifications` | yes | Enable email notifications +`synapse_email_from` | `Matrix ` | Email `From` address +`synapse_enable_registration` | no | Enable new user registration +`synapse_max_upload_size` | `50m` | Maxiumum file upload size +`synapse_auto_join_rooms` | `[]` | Local rooms to join automatically +`synapse_url_preview_blacklist` | see [defaults](defaults/main.yml) | List of CIDRs to block from URL previews +`synapse_url_preview_whitelist` | `[]` | List of CIDRs to allow for URL previews + +This role **exports** the following variables: + +Variable | Description +-----------------------------------|------------ +`synapse_element_webroot` | Path to [element-web](https://github.com/vector-im/element-web) directory +`synapse_apache_client_config` | Apache config block for client reverse proxy +`synapse_apache_federation_config` | Apache config block for federation reverse proxy + + +Usage +----- + +The following example playbook installs synapse and configures an Apache +reverse proxy. The client API is served on port 8443, the federation API +is served on port 8448, and the Element web client is served on the standard +HTTPS port. + +````yaml +- name: configure synapse matrix homeserver + hosts: matrix_servers + vars: + synapse_domain: example.com + synapse_server_name: matrix.example.com + synapse_client_port: 8443 + synapse_federation_port: 8448 + synapse_access_group: role-example-matrix-access + synapse_macaroon_secret_key: s3cret + synapse_form_secret: s3cret + synapse_sysaccount_password: s3cret + synapse_turn_host: turn.example.com + synapse_turn_secret: s3cret + synapse_email_from: 'Matrix ' + synapse_enable_registration: no + roles: + - role: synapse + tags: synapse + + - role: apache_vhost + apache_server_name: '{{ synapse_server_name }}' + apache_server_aliases: [] + apache_ssl_only: yes + apache_letsencrypt: yes + apache_listen_port: '{{ synapse_federation_port }}' + apache_config: '{{ synapse_apache_federation_config }}' + apache_config_name: '{{ synapse_server_name }}-federation' + tags: apache + + - role: apache_vhost + apache_server_name: '{{ synapse_server_name }}' + apache_server_aliases: [] + apache_ssl_only: yes + apache_letsencrypt: yes + apache_listen_port: '{{ synapse_client_port }}' + apache_config: '{{ synapse_apache_client_config }}' + apache_config_name: '{{ synapse_server_name }}-client' + tags: apache + + - role: apache_vhost + apache_server_name: '{{ synapse_server_name }}' + apache_server_aliases: [] + apache_letsencrypt: yes + apache_redirect_to_https: yes + apache_document_root: '{{ synapse_element_webroot }}' + apache_config_name: '{{ synapse_server_name }}-element' + tags: apache +```` diff --git a/roles/synapse/templates/var/lib/synapse/homeserver.yaml.j2 b/roles/synapse/templates/var/lib/synapse/homeserver.yaml.j2 index 8aefce7..6b27585 100644 --- a/roles/synapse/templates/var/lib/synapse/homeserver.yaml.j2 +++ b/roles/synapse/templates/var/lib/synapse/homeserver.yaml.j2 @@ -54,7 +54,9 @@ url_preview_ip_range_blacklist: {{ synapse_url_preview_blacklist | to_yaml }} url_preview_ip_range_whitelist: {{ synapse_url_preview_whitelist | to_yaml }} enable_registration: {{ synapse_enable_registration | bool | to_yaml }} +{% if synapse_registration_shared_secret is defined %} registration_shared_secret: {{ synapse_registration_shared_secret | to_yaml }} +{% endif %} {% if synapse_auto_join_rooms %} auto_join_rooms: -- cgit