Merge remote-tracking branch 'origin/master' into synapse-workers

Sync with upstream

docs/README.md

@@ -10,13 +10,13 @@
 
 - [Installing](installing.md)
 
-- **Importing data from another Synapse server installation**
+- **Importing data from another server installation**
 
-  - [Importing an existing SQLite database (from another installation)](importing-sqlite.md) (optional)
+  - [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)
 
   - [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)
 
-  - [Importing `media_store` data files from an existing installation](importing-media-store.md) (optional)
+  - [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
 
 - [Registering users](registering-users.md)
 

docs/ansible.md

@@ -9,9 +9,9 @@ If your local computer cannot run Ansible, you can also run Ansible on some serv
 
 ## Supported Ansible versions
 
-Ansible 2.7.0 or newer is required.
+Ansible 2.7.1 or newer is required ([last discussion about Ansible versions](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/743)).
 
-Ubuntu (at least 20.04) ships with a buggy version (see this [bug](https://bugs.launchpad.net/ubuntu/+source/ansible/+bug/1880359)), which can't be used in combination with a host running new systemd (more detaisl in [#517](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/517), [#669]([669](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/669))). If this problem affects you, you can: avoid running Ubuntu 20.04 on your host; run Ansible from another machine targeting your host; or try to upgrade to a newer Ansible version (see below).
+Note: Ubuntu 20.04 ships with Ansible 2.9.6 which is a buggy version (see this [bug](https://bugs.launchpad.net/ubuntu/+source/ansible/+bug/1880359)), which can't be used in combination with a host running new systemd (more details in [#517](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/517), [#669](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/669)). If this problem affects you, you can: avoid running Ubuntu 20.04 on your host; run Ansible from another machine targeting your host; or try to upgrade to a newer Ansible version (see below).
 
 
 ## Checking your Ansible version
@@ -51,7 +51,7 @@ docker run -it --rm \
 -v `pwd`:/work \
 -v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
 --entrypoint=/bin/sh \
-devture/ansible:2.9.13-r0
+docker.io/devture/ansible:2.9.14-r0
 ```
 
 The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`).

docs/configuring-playbook-bridge-appservice-discord.md

@@ -22,10 +22,10 @@ matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
 matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
 ```
 
-4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
-5. Retrieve Discord invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
-6. Invite the Bot to Discord servers you wish to bridge. Administrator permission is recommended.
-7. Room addresses follow this syntax: `#_discord_guildid_channelid`. You can easily find the guild and channel ids by logging into Discord in a browser and opening the desired channel. The URL will have this format: `discordapp.com/channels/guild_id/channel_id`. Once you have figured out the appropriate room addrss, you can join by doing `/join #_discord_guildid_channelid` in your Matrix client.
+5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
+6. Retrieve Discord invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
+7. Invite the Bot to Discord servers you wish to bridge. Administrator permission is recommended.
+8. Room addresses follow this syntax: `#_discord_guildid_channelid`. You can easily find the guild and channel ids by logging into Discord in a browser and opening the desired channel. The URL will have this format: `discordapp.com/channels/guild_id/channel_id`. Once you have figured out the appropriate room addrss, you can join by doing `/join #_discord_guildid_channelid` in your Matrix client.
 
 Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.
 

docs/configuring-playbook-bridge-mautrix-signal.md

@@ -0,0 +1,46 @@
+# Setting up Mautrix Signal (optional)
+
+The playbook can install and configure [mautrix-signal](https://github.com/tulir/mautrix-signal) for you.
+
+See the project's [documentation](https://github.com/tulir/mautrix-signal/wiki) to learn what it does and why it might be useful to you.
+
+**Note/Prerequisite**: If you're running with the Postgres database server integrated by the playbook (which is the default), you don't need to do anything special and can easily proceed with installing. However, if you're [using an external Postgres server](configuring-playbook-external-postgres.md), you'd need to manually prepare a Postgres database for this bridge and adjust the variables related to that (`matrix_mautrix_signal_database_*`).
+
+Use the following playbook configuration:
+
+```yaml
+matrix_mautrix_signal_enabled: true
+```
+
+## Set up Double Puppeting
+
+If you'd like to use [Double Puppeting](https://github.com/tulir/mautrix-whatsapp/wiki/Authentication#replacing-whatsapp-accounts-matrix-puppet-with-matrix-account) (hint: you most likely do), you have 2 ways of going about it.
+
+### Method 1: automatically, by enabling Shared Secret Auth
+
+The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
+
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
+
+### Method 2: manually, by asking each user to provide a working access token
+
+**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
+
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. You can use the following command:
+
+```
+curl \
+--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Signal", "initial_device_display_name": "Mautrix-Signal"}' \
+https://matrix.DOMAIN/_matrix/client/r0/login
+```
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature
+
+
+## Usage
+
+You then need to start a chat with `@signalbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).

docs/configuring-playbook-dimension.md

@@ -3,6 +3,9 @@
 **[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.**
 If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later.
 
+**Note**: enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
+
+
 ## Prerequisites
 
 This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and an [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environment. This is handled automatically based on the value of `matrix_synapse_federation_enabled`.
@@ -48,7 +51,7 @@ To get an access token for the Dimension user, you can follow one of two options
 3. Copy the highlighted text to your configuration.
 4. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
 
-*With CURL* 
+*With CURL*
 
 ```
 curl -X POST --header 'Content-Type: application/json' -d '{

docs/configuring-playbook-federation.md

@@ -37,3 +37,13 @@ matrix_synapse_federation_enabled: false
 ```
 
 With that, your server's users will only be able to talk among themselves, but not to anyone who is on another server.
+
+**Disabling federation does not necessarily disable the federation port** (`8448`). Services like [Dimension](configuring-playbook-dimension.md) and [ma1sd](configuring-playbook-ma1sd.md) normally rely on `openid` APIs exposed on that port. Even if you disable federation and only if necessary, we may still be exposing the federation port and serving the `openid` APIs there. To override this and completely disable Synapse's federation port use:
+
+```yaml
+# This stops the federation port on the Synapse side (normally `matrix-synapse:8048` on the container network).
+matrix_synapse_federation_port_enabled: false
+
+# This removes the `8448` virtual host from the matrix-nginx-proxy reverse-proxy server.
+matrix_nginx_proxy_proxy_matrix_federation_api_enabled: false
+```

docs/configuring-playbook-jitsi.md

@@ -99,7 +99,7 @@ matrix_jitsi_web_custom_config_extension: |
 
   config.disableAudioLevels = true;
 
-  # Limit the number of video feeds forwarded to each client
+  // Limit the number of video feeds forwarded to each client
   config.channelLastN = 4;
 
 matrix_jitsi_web_config_resolution_width_ideal_and_max: 480

docs/configuring-playbook-ma1sd.md

@@ -4,7 +4,9 @@ By default, this playbook configures an [ma1sd](https://github.com/ma1uta/ma1sd)
 
 This server is private by default, potentially at the expense of user discoverability.
 
-ma1sd is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.
+*ma1sd is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.*
+
+**Note**: enabling ma1sd (which is also the default), means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
 
 
 ## Disabling ma1sd
@@ -50,6 +52,9 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
 
 - `matrix_ma1sd_configuration_extension_yaml` - to configure ma1sd as required. See the [Registration feature's docs](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_ma1sd_configuration_extension_yaml`.
 
+**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.DOMAIN:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
+
+
 ## Authentication
 
 [Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver. The following configuration can be used to authenticate against an LDAP server:

docs/configuring-playbook-nginx.md

@@ -24,7 +24,6 @@ matrix_nginx_proxy_proxy_matrix_nginx_status_allowed_addresses:
 - 1.1.1.1
 ```
 
-
 ## Synapse + OpenID Connect for Single-Sign-On
 
 If you want to use OpenID Connect as an SSO provider (as per the [Synapse OpenID docs](https://github.com/matrix-org/synapse/blob/develop/docs/openid.md)), you need to use the following configuration (in your `vars.yml` file) to instruct nginx to forward `/_synapse/oidc` to Synapse:
@@ -32,3 +31,11 @@ If you want to use OpenID Connect as an SSO provider (as per the [Synapse OpenID
 ```yaml
 matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_oidc_api_enabled: true
 ```
+
+## Disable Nginx access logs
+
+This will disable the access logging for nginx.
+
+```yaml
+matrix_nginx_proxy_access_log_enabled: false
+```

docs/configuring-playbook-own-webserver.md

@@ -144,7 +144,7 @@ matrix_nginx_proxy_container_extra_arguments:
   - '--label "traefik.enable=true"'
 
   # The Nginx proxy container will receive traffic from these subdomains
-  - '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`{{ matrix_server_fqn_matrix }}`,`{{ matrix_server_fqn_element }}`,`{{ matrix_server_fqn_dimension }},`{{ matrix_server_fqn_jitsi }}`)"'
+  - '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`{{ matrix_server_fqn_matrix }}`,`{{ matrix_server_fqn_element }}`,`{{ matrix_server_fqn_dimension }}`,`{{ matrix_server_fqn_jitsi }}`)"'
 
   # (The 'web-secure' entrypoint must bind to port 443 in Traefik config)
   - '--label "traefik.http.routers.matrix-nginx-proxy.entrypoints=web-secure"'
@@ -219,7 +219,7 @@ services:
       - "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
     ports:
       - "443:443"
-      - "8080:8080"
+      - "8448:8448"
     volumes:
       - "./letsencrypt:/letsencrypt"
       - "/var/run/docker.sock:/var/run/docker.sock:ro"

docs/configuring-playbook-ssl-certificates.md

@@ -67,6 +67,7 @@ By default, it obtains certificates for:
 - possibly for `element.<your-domain>`, unless you have disabled the [Element client component](configuring-playbook-client-element.md) using `matrix_client_element_enabled: false`
 - possibly for `riot.<your-domain>`, if you have explicitly enabled Riot to Element redirection (for background compatibility) using `matrix_nginx_proxy_proxy_riot_compat_redirect_enabled: true`
 - possibly for `dimension.<your-domain>`, if you have explicitly [set up Dimension](configuring-playbook-dimension.md).
+- possibly for `jitsi.<your-domain>`, if you have explicitly [set up Jitsi](configuring-playbook-jitsi.md).
 - possibly for your base domain (`<your-domain>`), if you have explicitly configured [Serving the base domain](configuring-playbook-base-domain-serving.md)
 
 If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too.
@@ -80,6 +81,7 @@ matrix_ssl_domains_to_obtain_certificates_for:
   - '{{ matrix_server_fqn_matrix }}'
   - '{{ matrix_server_fqn_element }}'
   - '{{ matrix_server_fqn_dimension }}'
+  - '{{ matrix_server_fqn_jitsi }}'
   - '{{ matrix_domain }}'
 ```
 

docs/configuring-playbook.md

@@ -94,6 +94,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Mautrix Hangouts bridging](configuring-playbook-bridge-mautrix-hangouts.md) (optional)
 
+- [Setting up Mautrix Signal bridging](configuring-playbook-bridge-mautrix-signal.md) (optional)
+
 - [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional)
 
 - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional)

docs/howto-server-delegation.md

@@ -22,20 +22,20 @@ If this is okay with you, feel free to not read ahead.
 
 Server Delegation by means of a `/.well-known/matrix/server` file is the most straightforward, but suffers from the following downsides:
 
-- you need to have a working HTTPS server for the base domain (`<your-domain>`)
+- you need to have a working HTTPS server for the base domain (`<your-domain>`). If you don't have any server for the base domain at all, you can easily solve it by making the playbook [serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md).
 
 - any downtime on the base domain (`<your-domain>`) or network trouble between the matrix subdomain (`matrix.<your-domain>`) and the base `<domain>` may cause Matrix Federation outages. As the [Server-Server spec says](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery):
 
 > Errors are recommended to be cached for up to an hour, and servers are encouraged to exponentially back off for repeated failures.
 
-If this is not a concern for you, feel free to not read ahead.
+**For most people, this is a reasonable tradeoff** given that it's easy and straightforward to set up. We recommend you stay on this path.
 
-Otherwise, you can decide to go against the default for this playbook, and instead set up [Server Delegation via a DNS SRV record (advanced)](#server-delegation-via-a-dns-srv-record-advanced).
+Otherwise, you can decide to go against the default for this playbook, and instead set up [Server Delegation via a DNS SRV record (advanced)](#server-delegation-via-a-dns-srv-record-advanced) (much more complicated).
 
 
 ## Server Delegation via a DNS SRV record (advanced)
 
-**NOTE**: doing Server Delegation via a DNS SRV record is a more advanced way to do it and is not the default for this playbook.
+**NOTE**: doing Server Delegation via a DNS SRV record is a more **advanced** way to do it and is not the default for this playbook. This is usually **much more complicated** to set up, so **we don't recommend it**. If you're not an experience sysadmin, you'd better stay away from this.
 
 As per the [Server-Server spec](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), it's possible to do Server Delegation using only a SRV record (without a `/.well-known/matrix/server` file).
 
@@ -47,7 +47,7 @@ To use DNS SRV record validation, you need to:
 
 - ensure that you have a `_matrix._tcp` DNS SRV record for your base domain (`<your-domain>`) with a value of `10 0 8448 matrix.<your-domain>`
 
-- ensure that you are serving the Matrix Federation API (tcp/8448) with a certificate for `<your-domain>` (not `matrix.<your-domain>`!). See below.
+- ensure that you are serving the Matrix Federation API (tcp/8448) with a certificate for `<your-domain>` (not `matrix.<your-domain>`!). Getting this certificate to the `matrix.<your-domain>` server may be complicated. The playbook's automatic SSL obtaining/renewal flow will likely not work and you'll need to copy certificates around manually. See below.
 
 
 ### Obtaining certificates

docs/importing-postgres.md

@@ -1,7 +1,7 @@
 # Importing an existing Postgres database from another installation (optional)
 
-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)).
+Run this if you'd like to import your database from a previous installation.
+(don't forget to import your Synapse `media_store` files as well - see [the importing-synape-media-store guide](importing-synapse-media-store.md)).
 
 
 ## Prerequisites

docs/importing-synapse-media-store.md

@@ -1,4 +1,4 @@
-# Importing `media_store` data files from an existing installation (optional)
+# Importing `media_store` data files from an existing Synapse installation (optional)
 
 Run this if you'd like to import your `media_store` files from a previous installation of Synapse.
 
@@ -17,6 +17,6 @@ As an alternative, you can perform a manual restore using the [AWS CLI tool](htt
 
 Run this command (make sure to replace `<server-path-to-media_store>` with a path on your server):
 
-	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_media_store=<server-path-to-media_store>' --tags=import-media-store
+	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_media_store=<server-path-to-media_store>' --tags=import-synapse-media-store
 
 **Note**: `<server-path-to-media_store>` must be a file path to a `media_store` directory on the server (not on your local machine!).

docs/importing-synapse-sqlite.md

@@ -1,7 +1,7 @@
-# Importing an existing SQLite database from another installation (optional)
+# Importing an existing SQLite database from another Synapse installation (optional)
 
 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)).
+(don't forget to import your `media_store` files as well - see [the importing-synapse-media-store guide](importing-synapse-media-store.md)).
 
 While this playbook always sets up PostgreSQL, by default a Synapse installation would run
 using an SQLite database.
@@ -18,7 +18,7 @@ Before doing the actual import, **you need to upload your SQLite database file t
 
 Run this command (make sure to replace `<server-path-to-homeserver.db>` with a file path on your server):
 
-	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_homeserver_db=<server-path-to-homeserver.db>' --tags=import-sqlite-db
+	ansible-playbook -i inventory/hosts setup.yml --extra-vars='server_path_homeserver_db=<server-path-to-homeserver.db>' --tags=import-synapse-sqlite-db
 
 **Notes**:
 

docs/installing.md

@@ -21,11 +21,11 @@ Feel free to **re-run this setup command any time** you think something is off w
 
 After installing, but before starting the services, you may want to do additional things like:
 
-- [Importing an existing SQLite database (from another installation)](importing-sqlite.md) (optional)
+- [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)
 
 - [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)
 
-- [Importing `media_store` data files from an existing installation](importing-media-store.md) (optional)
+- [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
 
 
 ## Starting the services

docs/maintenance-postgres.md

@@ -45,7 +45,7 @@ docker run \
 --log-driver=none \
 --network=matrix \
 --env-file=/matrix/postgres/env-postgres-psql \
-postgres:13.0-alpine \
+docker.io/postgres:13.1-alpine \
 pg_dumpall -h matrix-postgres \
 | gzip -c \
 > /postgres.sql.gz
@@ -69,7 +69,7 @@ This playbook can upgrade your existing Postgres setup with the following comman
 
 	ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres
 
-**The old Postgres data directory is backed up** automatically, by renaming it to `/matrix/postgres-auto-upgrade-backup`.
+**The old Postgres data directory is backed up** automatically, by renaming it to `/matrix/postgres/data-auto-upgrade-backup`.
 To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="postgres_auto_upgrade_backup_data_path=/another/disk/matrix-postgres-before-upgrade"`
 
 The auto-upgrade-backup directory stays around forever, until you **manually decide to delete it**.

docs/maintenance-synapse.md

@@ -4,14 +4,11 @@ This document shows you how to perform various maintenance tasks related to the
 
 Table of contents:
 
-- [Purging unused data with synapse-janitor](#purging-unused-data-with-synapse-janitor), for when you wish to delete unused data from the Synapse database
-
 - [Purging old data with the Purge History API](#purging-old-data-with-the-purge-history-api), for when you wish to delete in-use (but old) data from the Synapse database
 
 - [Synapse maintenance](#synapse-maintenance)
 	- [Purging old data with the Purge History API](#purging-old-data-with-the-purge-history-api)
 	- [Compressing state with rust-synapse-compress-state](#compressing-state-with-rust-synapse-compress-state)
-	- [Purging unused data with synapse-janitor](#purging-unused-data-with-synapse-janitor)
 	- [Browse and manipulate the database](#browse-and-manipulate-the-database)
 
 - [Browse and manipulate the database](#browse-and-manipulate-the-database), for when you really need to take matters into your own hands
@@ -57,27 +54,6 @@ If you need to adjust this, pass: `--extra-vars='matrix_synapse_rust_synapse_com
 After state compression, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
 
 
-## Purging unused data with synapse-janitor
-
-**NOTE**: There are [reports](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/465) that **synapse-janitor is dangerous to use and causes database corruption**. You may wish to refrain from using it.
-
-When you **leave** and **forget** a room, Synapse can clean up its data, but currently doesn't.
-This **unused and unreachable data** remains in your database forever.
-
-There are external tools (like [synapse-janitor](https://github.com/xwiki-labs/synapse_scripts)), which are meant to solve this problem.
-
-To ask the playbook to run synapse-janitor, execute:
-
-```bash
-ansible-playbook -i inventory/hosts setup.yml --tags=run-postgres-synapse-janitor,start
-```
-
-**Note**: this will automatically stop Synapse temporarily and restart it later.
-
-Running synapse-janitor potentially deletes a lot of data from the Postgres database.
-You may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql) after that.
-
-
 ## Browse and manipulate the database
 
 When the [matrix admin API](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) and the other tools do not provide a more convenient way, having a look at synapse's postgresql database can satisfy a lot of admins' needs.

docs/prerequisites.md

@@ -10,7 +10,7 @@ This playbook doesn't support running on ARM (see [this issue](https://github.co
 
 - `root` access to your server (or a user capable of elevating to `root` via `sudo`).
 
-- [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python`).
+- [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python3`). On some distros, Ansible may incorrectly [detect the Python version](https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html) (2 vs 3) and you may need to explicitly specify the interpreter path in `inventory/hosts` during installation (e.g. `ansible_python_interpreter=/usr/bin/python3`)
 
 - A `cron`-like tool installed on the server such as `cron` or `anacron` to automatically schedule the Let's Encrypt SSL certificates's renewal. *This can be ignored if you use your own SSL certificates.*
 
@@ -22,6 +22,17 @@ This playbook doesn't support running on ARM (see [this issue](https://github.co
 
 - Properly configured DNS records for `<your-domain>` (details in [Configuring DNS](configuring-dns.md)).
 
-- Some TCP/UDP ports open. This playbook configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports: `80/tcp` (HTTP webserver), `443/tcp` (HTTPS webserver), `3478/tcp` (TURN over TCP), `3478/udp` (TURN over UDP), `5349/tcp` (TURN over TCP), `5349/udp` (TURN over UDP), `8448/tcp` (Matrix Federation API HTTPS webserver), the range `49152-49172/udp` (TURN over UDP), `4443/tcp` (Jitsi Harvester fallback), `10000/udp` (Jitsi video RTP). Depending on your firewall/NAT setup, incoming RTP packets on port 10000 may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/matrix-jitsi/defaults/main.yml)).
+- Some TCP/UDP ports open. This playbook configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports:
+
+  - `80/tcp`: HTTP webserver
+  - `443/tcp`: HTTPS webserver
+  - `3478/tcp`: TURN over TCP (used by Coturn)
+  - `3478/udp`: TURN over UDP (used by Coturn)
+  - `5349/tcp`: TURN over TCP (used by Coturn)
+  - `5349/udp`: TURN over UDP (used by Coturn)
+  - `8448/tcp`: Matrix Federation API HTTPS webserver. In some cases, this **may necessary even with federation disabled**. Integration Servers (like Dimension) and Identity Servers (like ma1sd) may need to access `openid` APIs on the federation port.
+  - the range `49152-49172/udp`: TURN over UDP
+  - `4443/tcp`: Jitsi Harvester fallback
+  - `10000/udp`: Jitsi video RTP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/matrix-jitsi/defaults/main.yml)).
 
 When ready to proceed, continue with [Configuring DNS](configuring-dns.md).

docs/self-building.md

@@ -15,6 +15,7 @@ List of roles where self-building the Docker image is currently possible:
 - `matrix-client-element`
 - `matrix-registration`
 - `matrix-coturn`
+- `matrix-corporal`
 - `matrix-ma1sd`
 - `matrix-mailer`
 - `matrix-bridge-mautrix-facebook`

docs/updating-users-passwords.md

@@ -26,7 +26,7 @@ and then connecting to the postgres server and executing:
 ```
 UPDATE users SET password_hash = '<password-hash>' WHERE name = '@someone:server.com'
 ```
-`
+
 where `<password-hash>` is the hash returned by the docker command above.