From a4da1535dd267f4eb4bb6a3f4cf40bbb8003682a Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Fri, 19 Apr 2019 09:54:18 +0300 Subject: [PATCH 1/5] Split additional configuration options in groups It's too many configuration options to keep them in a single list. Trying to put some order. --- docs/configuring-playbook.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index c56cf11d..fad46203 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -27,11 +27,12 @@ When you're done with all the configuration you'd like to do, continue with [Ins ## Other configuration options -- [Enabling Telemetry for your Matrix server](configuring-playbook-telemetry.md) (optional) +### Additional useful services -- [Controlling Matrix federation](configuring-playbook-federation.md) (optional) +- [Setting up the Dimension Integration Manager](configuring-playbook-dimension.md) (optional, but recommended; after [installing](installing.md)) -- [Adjusting email-sending settings](configuring-playbook-email.md) (optional) + +### Core service adjustments - [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional) @@ -45,6 +46,18 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced) + +### Server connectivity + +- [Enabling Telemetry for your Matrix server](configuring-playbook-telemetry.md) (optional) + +- [Controlling Matrix federation](configuring-playbook-federation.md) (optional) + +- [Adjusting email-sending settings](configuring-playbook-email.md) (optional) + + +### Authentication and user-related + - [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional, advanced) - [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional, advanced) @@ -53,6 +66,9 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced) + +### Bridging other networks + - [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional) - [Setting up Mautrix Whatsapp bridging](configuring-playbook-bridge-mautrix-whatsapp.md) (optional) @@ -60,5 +76,3 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional) - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional) - -- [Setting up Dimension](configuring-playbook-dimension.md) (optional) From 9ea5088761e2e97770f20e598b790e9e155bebdf Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Fri, 19 Apr 2019 09:57:41 +0300 Subject: [PATCH 2/5] Add TURN server configuration documentation --- docs/configuring-playbook-turn.md | 33 +++++++++++++++++++++++++++++++ docs/configuring-playbook.md | 2 ++ 2 files changed, 35 insertions(+) create mode 100644 docs/configuring-playbook-turn.md diff --git a/docs/configuring-playbook-turn.md b/docs/configuring-playbook-turn.md new file mode 100644 index 00000000..547f2bef --- /dev/null +++ b/docs/configuring-playbook-turn.md @@ -0,0 +1,33 @@ +# TURN server + +The playbook installs a [Coturn](https://github.com/coturn/coturn) TURN server by default, so that clients can make audio/video calls even from [NAT](https://en.wikipedia.org/wiki/Network_address_translation)-ed networks. + +By default, the Synapse chat server is configured, so that it points to the Coturn TURN server installed by the playbook. + + +## Disabling Coturn + +If, for some reason, you'd like to prevent the playbook from installing Coturn, you can use the following configuration: + +```yaml +matrix_coturn_enabled: false +``` + +In that case, Synapse would not point to any Coturn servers and audio/video call functionality may fail. + + +## Using your own external Coturn server + +If you'd like to use another TURN server (be it Coturn or some other one), you can configure the playbook like this: + +```yaml +# Disable integrated Coturn server +matrix_coturn_enabled: false + +# Point Synapse to your other Coturn server +matrix_synapse_turn_uris: +- turns:HOSTNAME_OR_IP?transport=udp +- turns:HOSTNAME_OR_IP?transport=tcp +- turn:HOSTNAME_OR_IP?transport=udp +- turn:HOSTNAME_OR_IP?transport=tcp +``` diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index fad46203..37de226a 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -46,6 +46,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced) +- [Adjusting TURN server configuration](configuring-playbook-turn.md) (optional, advanced) + ### Server connectivity From 18a562c000e818674a44d212418894285de0a480 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sun, 21 Apr 2019 08:57:49 +0300 Subject: [PATCH 3/5] Upgrade services --- roles/matrix-mailer/defaults/main.yml | 2 +- roles/matrix-nginx-proxy/defaults/main.yml | 2 +- roles/matrix-riot-web/defaults/main.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/roles/matrix-mailer/defaults/main.yml b/roles/matrix-mailer/defaults/main.yml index f4b2e917..ffd00e36 100644 --- a/roles/matrix-mailer/defaults/main.yml +++ b/roles/matrix-mailer/defaults/main.yml @@ -2,7 +2,7 @@ matrix_mailer_enabled: true matrix_mailer_base_path: "{{ matrix_base_data_path }}/mailer" -matrix_mailer_docker_image: "devture/exim-relay:4.91-r1-0" +matrix_mailer_docker_image: "devture/exim-relay:4.91-r3-0" # The user/group that the container runs with. # These match the `exim` user/group within the container image. diff --git a/roles/matrix-nginx-proxy/defaults/main.yml b/roles/matrix-nginx-proxy/defaults/main.yml index 3576f4c4..674757f9 100644 --- a/roles/matrix-nginx-proxy/defaults/main.yml +++ b/roles/matrix-nginx-proxy/defaults/main.yml @@ -3,7 +3,7 @@ matrix_nginx_proxy_enabled: true # We use an official nginx image, which we fix-up to run unprivileged. # An alternative would be an `nginxinc/nginx-unprivileged` image, but # those as more frequently out of date. -matrix_nginx_proxy_docker_image: "nginx:1.15.10-alpine" +matrix_nginx_proxy_docker_image: "nginx:1.15.12-alpine" matrix_nginx_proxy_base_path: "{{ matrix_base_data_path }}/nginx-proxy" matrix_nginx_proxy_data_path: "{{ matrix_nginx_proxy_base_path }}/data" diff --git a/roles/matrix-riot-web/defaults/main.yml b/roles/matrix-riot-web/defaults/main.yml index 5f2ad164..4c6424dc 100644 --- a/roles/matrix-riot-web/defaults/main.yml +++ b/roles/matrix-riot-web/defaults/main.yml @@ -1,6 +1,6 @@ matrix_riot_web_enabled: true -matrix_riot_web_docker_image: "bubuntux/riot-web:v1.0.7" +matrix_riot_web_docker_image: "bubuntux/riot-web:v1.0.8" matrix_riot_web_data_path: "{{ matrix_base_data_path }}/riot-web" From 39566aa7fe17cd80dfb78f430bd27946a51a693b Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Tue, 23 Apr 2019 10:06:42 +0300 Subject: [PATCH 4/5] Generate a Synapse signing key file, if missing The code used to check for a `homeserver.yaml` file and generate a configuration (+ key) only if such a configuration file didn't exist. Certain rare cases (setting up with one server name and then changing to another) lead to `homeserver.yaml` being there, but a `matrix.DOMAIN.signing.key` file missing (because the domain changed). A new signing key file would never get generated, because `homeserver.yaml`'s existence used to be (incorrectly) satisfactory for us. From now on, we don't mix things up like that. We don't care about `homeserver.yaml` anymore, but rather about the actual signing key. The rest of the configuration (`homeserver.yaml` and `matrix.DOMAIN.log.config`) is rebuilt by us in any case, so whether it exists or not is irrelevant and doesn't need checking. --- .../matrix-synapse/tasks/setup_synapse_main.yml | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/roles/matrix-synapse/tasks/setup_synapse_main.yml b/roles/matrix-synapse/tasks/setup_synapse_main.yml index 388e28ce..f1bb1430 100644 --- a/roles/matrix-synapse/tasks/setup_synapse_main.yml +++ b/roles/matrix-synapse/tasks/setup_synapse_main.yml @@ -22,17 +22,19 @@ docker_image: name: "{{ matrix_synapse_docker_image }}" -- name: Check if a Matrix Synapse configuration exists +- name: Check if a Synapse signing key exists stat: - path: "{{ matrix_synapse_config_dir_path }}/homeserver.yaml" - register: matrix_synapse_config_stat + path: "{{ matrix_synapse_config_dir_path }}/{{ matrix_server_fqn_matrix }}.signing.key" + register: matrix_synapse_signing_key_stat -# We do this mostly so that the keys would get generated. -# We'll replace the rest of the configuration with our own templates below. +# We do this so that the signing key would get generated. +# +# This will also generate a default homeserver.yaml configuration file and a log configuration file. +# We don't care about those configuraiton files, as we replace them with our own anyway (see below). # # We don't use the `docker_container` module, because using it with `cap_drop` requires # a very recent version, which is not available for a lot of people yet. -- name: Generate initial Matrix config +- name: Generate initial Matrix config and signing key command: | docker run --rm @@ -45,7 +47,7 @@ -e SYNAPSE_REPORT_STATS=no {{ matrix_synapse_docker_image }} generate - when: "not matrix_synapse_config_stat.stat.exists" + when: "not matrix_synapse_signing_key_stat.stat.exists" - name: Ensure Matrix homeserver config installed template: From 892abdc7004ce53638027f8bc392bd2260334780 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Tue, 23 Apr 2019 10:20:56 +0300 Subject: [PATCH 5/5] Do not refer to Synapse as "Matrix Synapse" --- README.md | 2 +- docs/configuring-playbook-s3.md | 6 +++--- docs/importing-media-store.md | 4 ++-- docs/importing-postgres.md | 2 +- docs/importing-sqlite.md | 8 ++++---- roles/matrix-synapse/defaults/main.yml | 10 +++++----- roles/matrix-synapse/tasks/import_media_store.yml | 2 +- roles/matrix-synapse/tasks/register_user.yml | 2 +- roles/matrix-synapse/tasks/setup_synapse_main.yml | 12 ++++++------ roles/matrix-synapse/tasks/setup_synapse_pre.yml | 4 ++-- .../synapse/systemd/matrix-synapse.service.j2 | 2 +- 11 files changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index cc3c8fe4..388b1c29 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up w This playbook sets up your server using the following Docker images: -- [matrixdotorg/synapse](https://hub.docker.com/r/matrixdotorg/synapse/) - the official [Matrix Synapse](https://github.com/matrix-org/synapse) server +- [matrixdotorg/synapse](https://hub.docker.com/r/matrixdotorg/synapse/) - the official [Synapse](https://github.com/matrix-org/synapse) Matrix homeserver - [instrumentisto/coturn](https://hub.docker.com/r/instrumentisto/coturn/) - the [Coturn](https://github.com/coturn/coturn) STUN/TURN server (optional) diff --git a/docs/configuring-playbook-s3.md b/docs/configuring-playbook-s3.md index e0687d8d..dda75cf2 100644 --- a/docs/configuring-playbook-s3.md +++ b/docs/configuring-playbook-s3.md @@ -1,9 +1,9 @@ # Storing Matrix media files on Amazon S3 (optional) -By default, this playbook configures your server to store Matrix Synapse's content repository (`media_store`) files on the local filesystem. +By default, this playbook configures your server to store Synapse's content repository (`media_store`) files on the local filesystem. If that's alright, you can skip this. -If you'd like to store Matrix Synapse's content repository (`media_store`) files on Amazon S3, +If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3, you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you. You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example security policy: @@ -36,4 +36,4 @@ matrix_s3_media_store_bucket_name: "your-bucket-name" matrix_s3_media_store_aws_access_key: "access-key-goes-here" matrix_s3_media_store_aws_secret_key: "secret-key-goes-here" matrix_s3_media_store_region: "eu-central-1" -``` \ No newline at end of file +``` diff --git a/docs/importing-media-store.md b/docs/importing-media-store.md index 7aa6c5b5..0d86370b 100644 --- a/docs/importing-media-store.md +++ b/docs/importing-media-store.md @@ -1,6 +1,6 @@ # Importing `media_store` data files from an existing installation (optional) -Run this if you'd like to import your `media_store` files from a previous installation of Matrix Synapse. +Run this if you'd like to import your `media_store` files from a previous installation of Synapse. ## Prerequisites @@ -19,4 +19,4 @@ Run this command (make sure to replace `` with a pat ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_media_store=' --tags=import-media-store -**Note**: `` must be a file path to a `media_store` directory on the server (not on your local machine!). \ No newline at end of file +**Note**: `` must be a file path to a `media_store` directory on the server (not on your local machine!). diff --git a/docs/importing-postgres.md b/docs/importing-postgres.md index 7fd1ba97..878888f0 100644 --- a/docs/importing-postgres.md +++ b/docs/importing-postgres.md @@ -1,6 +1,6 @@ # Importing an existing Postgres database from another installation (optional) -Run this if you'd like to import your database from a previous installation of Matrix Synapse. +Run this if you'd like to import your database from a previous installation of Synapse. (don't forget to import your `media_store` files as well - see [the importing-media-store guide](importing-media-store.md)). diff --git a/docs/importing-sqlite.md b/docs/importing-sqlite.md index af705a79..cb30d098 100644 --- a/docs/importing-sqlite.md +++ b/docs/importing-sqlite.md @@ -1,12 +1,12 @@ # Importing an existing SQLite database from another installation (optional) -Run this if you'd like to import your database from a previous default installation of Matrix Synapse. +Run this if you'd like to import your database from a previous default installation of Synapse. (don't forget to import your `media_store` files as well - see [the importing-media-store guide](importing-media-store.md)). -While this playbook always sets up PostgreSQL, by default a Matrix Synapse installation would run +While this playbook always sets up PostgreSQL, by default a Synapse installation would run using an SQLite database. -If you have such a Matrix Synapse setup and wish to migrate it here (and over to PostgreSQL), this command is for you. +If you have such a Synapse setup and wish to migrate it here (and over to PostgreSQL), this command is for you. ## Prerequisites @@ -20,4 +20,4 @@ Run this command (make sure to replace `` with a f ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_homeserver_db=' --tags=import-sqlite-db -**Note**: `` must be a file path to a `homeserver.db` file on the server (not on your local machine!). \ No newline at end of file +**Note**: `` must be a file path to a `homeserver.db` file on the server (not on your local machine!). diff --git a/roles/matrix-synapse/defaults/main.yml b/roles/matrix-synapse/defaults/main.yml index d6a4f047..8edc6b62 100644 --- a/roles/matrix-synapse/defaults/main.yml +++ b/roles/matrix-synapse/defaults/main.yml @@ -119,26 +119,26 @@ matrix_synapse_auto_join_rooms: [] # automatically if they don't already exist. matrix_synapse_autocreate_auto_join_rooms: true -# Controls password-peppering for Matrix Synapse. Not to be changed after initial setup. +# Controls password-peppering for Synapse. Not to be changed after initial setup. matrix_synapse_password_config_pepper: "" -# Controls the number of events that Matrix Synapse caches in memory. +# Controls the number of events that Synapse caches in memory. matrix_synapse_event_cache_size: "100K" -# Controls cache sizes for Matrix Synapse via the SYNAPSE_CACHE_FACTOR environment variable. +# Controls cache sizes for Synapse via the SYNAPSE_CACHE_FACTOR environment variable. # Raise this to increase cache sizes or lower it to potentially lower memory use. # To learn more, see: # - https://github.com/matrix-org/synapse#help-synapse-eats-all-my-ram # - https://github.com/matrix-org/synapse/issues/3939 matrix_synapse_cache_factor: 0.5 -# Controls whether Matrix Synapse will federate at all. +# Controls whether Synapse will federate at all. # Disable this to completely isolate your server from the rest of the Matrix network. # Also see: `matrix_synapse_tls_federation_listener_enabled` if you wish to keep federation enabled, # but want to stop the TLS listener (port 8448). matrix_synapse_federation_enabled: true -# A list of domain names that are allowed to federate with the given Matrix Synapse server. +# A list of domain names that are allowed to federate with the given Synapse server. # An empty list value (`[]`) will also effectively stop federation, but if that's the desired # result, it's better to accomplish it by changing `matrix_synapse_federation_enabled`. matrix_synapse_federation_domain_whitelist: ~ diff --git a/roles/matrix-synapse/tasks/import_media_store.yml b/roles/matrix-synapse/tasks/import_media_store.yml index f3f606fd..8d964715 100644 --- a/roles/matrix-synapse/tasks/import_media_store.yml +++ b/roles/matrix-synapse/tasks/import_media_store.yml @@ -73,7 +73,7 @@ # We don't chown for Goofys, because due to the way it's mounted, # all files become owned by whoever needs to own them. -- name: Ensure Matrix Synapse is started (if it previously was) +- name: Ensure Synapse is started (if it previously was) service: name: "{{ item }}" state: started diff --git a/roles/matrix-synapse/tasks/register_user.yml b/roles/matrix-synapse/tasks/register_user.yml index 1a4bd446..c476adfe 100644 --- a/roles/matrix-synapse/tasks/register_user.yml +++ b/roles/matrix-synapse/tasks/register_user.yml @@ -22,7 +22,7 @@ daemon_reload: yes register: start_result -- name: Wait a while, so that Matrix Synapse can manage to start +- name: Wait a while, so that Synapse can manage to start pause: seconds: 7 when: start_result.changed diff --git a/roles/matrix-synapse/tasks/setup_synapse_main.yml b/roles/matrix-synapse/tasks/setup_synapse_main.yml index f1bb1430..6e56b659 100644 --- a/roles/matrix-synapse/tasks/setup_synapse_main.yml +++ b/roles/matrix-synapse/tasks/setup_synapse_main.yml @@ -1,7 +1,7 @@ --- # This will throw a Permission Denied error if already mounted using fuse -- name: Check Matrix Synapse media store path +- name: Check Synapse media store path stat: path: "{{ matrix_synapse_media_store_path }}" register: local_path_media_store_stat @@ -9,7 +9,7 @@ # This is separate and conditional, to ensure we don't execute it # if the path already exists or we failed to check, because it's mounted using fuse. -- name: Ensure Matrix media store path exists +- name: Ensure Synapse media store path exists file: path: "{{ matrix_synapse_media_store_path }}" state: directory @@ -18,7 +18,7 @@ group: "{{ matrix_user_username }}" when: "not local_path_media_store_stat.failed and not local_path_media_store_stat.stat.exists" -- name: Ensure Matrix Docker image is pulled +- name: Ensure Synapse Docker image is pulled docker_image: name: "{{ matrix_synapse_docker_image }}" @@ -34,7 +34,7 @@ # # We don't use the `docker_container` module, because using it with `cap_drop` requires # a very recent version, which is not available for a lot of people yet. -- name: Generate initial Matrix config and signing key +- name: Generate initial Synapse config and signing key command: | docker run --rm @@ -49,13 +49,13 @@ generate when: "not matrix_synapse_signing_key_stat.stat.exists" -- name: Ensure Matrix homeserver config installed +- name: Ensure Synapse homeserver config installed template: src: "{{ matrix_synapse_template_synapse_homeserver }}" dest: "{{ matrix_synapse_config_dir_path }}/homeserver.yaml" mode: 0644 -- name: Ensure Matrix log config installed +- name: Ensure Synapse log config installed template: src: "{{ matrix_synapse_template_synapse_log }}" dest: "{{ matrix_synapse_config_dir_path }}/{{ matrix_server_fqn_matrix }}.log.config" diff --git a/roles/matrix-synapse/tasks/setup_synapse_pre.yml b/roles/matrix-synapse/tasks/setup_synapse_pre.yml index 2871ef26..f95c3eb2 100644 --- a/roles/matrix-synapse/tasks/setup_synapse_pre.yml +++ b/roles/matrix-synapse/tasks/setup_synapse_pre.yml @@ -4,7 +4,7 @@ matrix_synapse_media_store_parent_path: "{{ matrix_synapse_media_store_path|dirname }}" matrix_synapse_media_store_directory_name: "{{ matrix_synapse_media_store_path|basename }}" -- name: Ensure Matrix Synapse paths exist +- name: Ensure Synapse paths exist file: path: "{{ item }}" state: directory @@ -17,4 +17,4 @@ - "{{ matrix_synapse_ext_path }}" # We handle matrix_synapse_media_store_path elsewhere (in setup_synapse_main.yml), # because if it's using Goofys and it's already mounted (from before), - # trying to chown/chmod it here will cause trouble. \ No newline at end of file + # trying to chown/chmod it here will cause trouble. diff --git a/roles/matrix-synapse/templates/synapse/systemd/matrix-synapse.service.j2 b/roles/matrix-synapse/templates/synapse/systemd/matrix-synapse.service.j2 index f11e99d4..fe8d0c8a 100644 --- a/roles/matrix-synapse/templates/synapse/systemd/matrix-synapse.service.j2 +++ b/roles/matrix-synapse/templates/synapse/systemd/matrix-synapse.service.j2 @@ -1,5 +1,5 @@ [Unit] -Description=Matrix Synapse server +Description=Synapse server {% for service in matrix_synapse_systemd_required_services_list %} Requires={{ service }} After={{ service }}