Merge branch 'master' into signal

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/configuring-dns.md

@@ -34,7 +34,7 @@ DNS records marked with `(*)` above are optional. They refer to services that wi
 
 As the table above illustrates, you need to create 2 subdomains (`matrix.<your-domain>` and `element.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
 
-The `element.<your-domain>` subdomain is necessary, because this playbook installs the [Element](https://github.com/vector-im/riot-web) web client for you.
+The `element.<your-domain>` subdomain is necessary, because this playbook installs the [Element](https://github.com/vector-im/element-web) web client for you.
 If you'd rather instruct the playbook not to install Element (`matrix_client_element_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `element.<your-domain>` DNS record.
 
 The `dimension.<your-domain>` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. Dimension installation is disabled by default, because it's only possible to install it after the other Matrix services are working (see [Setting up Dimension](configuring-playbook-dimension.md) later). If you do not wish to set up Dimension, feel free to skip the `dimension.<your-domain>` DNS record.

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-matrix-bridge-sms.md

@@ -1,11 +1,10 @@
 # Setting up matrix-sms-bridge (optional)
 
-The playbook can install and configure
-[matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for you.
+The playbook can install and configure [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for you.
 
 See the project page to learn what it does and why it might be useful to you.
 
-First you need to ensure, that the bridge has unix read and write rights to your modem. On debian based distributions there is nothing to do. On others distributions you either add a group `dialout` to your host and assign it to your modem or you give the matrix user or group access to your modem.
+**The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.**
 
 To enable the bridge just use the following
 playbook configuration:
@@ -13,16 +12,23 @@ playbook configuration:
 
 ```yaml
 matrix_sms_bridge_enabled: true
-matrix_sms_bridge_gammu_modem: "/dev/serial/by-id/myDeviceId"
-# generate a secret passwort e.g. with pwgen -s 64 1
-matrix_sms_bridge_database_password: ""
-# (optional) a room id to a default room
+
+# (optional but recommended) a room id to a default room
 matrix_sms_bridge_default_room: "" 
-# (optional) gammu reset frequencies (see https://wammu.eu/docs/manual/smsd/config.html#option-ResetFrequency)
-matrix_sms_bridge_gammu_reset_frequency: 3600
-matrix_sms_bridge_gammu_hard_reset_frequency: 0
-# (optional) group with unix read and write rights to modem
-matrix_sms_bridge_modem_group: 'dialout'
+
+# (optional but recommended) configure your server location
+matrix_sms_bridge_default_region: DE
+matrix_sms_bridge_default_timezone: Europe/Berlin
+
+# Settings to connect to android-sms-gateway-server
+matrix_sms_bridge_provider_android_baseurl: https://192.168.24.24:9090
+matrix_sms_bridge_provider_android_username: admin
+matrix_sms_bridge_provider_android_password: supeSecretPassword
+
+# (optional) if your android-sms-gateway-server uses a self signed vertificate, the bridge needs a "truststore". This can be the certificate itself.
+matrix_sms_bridge_provider_android_truststore_local_path: android-sms-gateway-server.p12
+matrix_sms_bridge_provider_android_truststore_password: 123
+
 ```
 
 

docs/configuring-playbook-client-element.md

@@ -1,6 +1,6 @@
 # Configuring Element (optional)
 
-By default, this playbook installs the [Element](https://github.com/vector-im/riot-web) Matrix client web application.
+By default, this playbook installs the [Element](https://github.com/vector-im/element-web) Matrix client web application.
 If that's okay, you can skip this document.
 
 

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-dynamic-dns.md

@@ -0,0 +1,27 @@
+# Dynamic DNS
+
+## Setup
+
+Most cloud providers / ISPs will charge you extra for a static IP address. If you're
+not hosting a highly reliable homeserver you can workaround this via dynamic DNS. To
+set this up, you'll need to get the username/password from your DNS provider. For
+google domains, this process is described [here](https://support.google.com/domains/answer/6147083).
+After you've gotten the proper credentials you can add the following config to your `inventory/host_vars/matrix.DOMAIN/vars.yml`:
+
+```yaml
+matrix_dynamic_dns_enabled: true
+
+matrix_dynamic_dns_domain_configurations:
+  - provider: domains.google.com
+    protocol: dyndn2
+    username: XXXXXXXXXXXXXXXX
+    password: XXXXXXXXXXXXXXXX
+    domain: "{{ matrix_domain }}"
+```
+
+
+## Additional Reading
+
+Additional resources:
+
+- https://matrix.org/docs/guides/free-small-matrix-server

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

@@ -91,44 +91,33 @@ matrix_jitsi_jvb_container_extra_arguments:
 
 ## (Optional) Fine tune Jitsi
 
-You may want to suspend unused video layers until they are requested again, to save up resources on both server and clients.
+Sample **additional** `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration to save up resources (explained below):
+
+```yaml
+matrix_jitsi_web_custom_config_extension: |
+  config.enableLayerSuspension = true;
+
+  config.disableAudioLevels = true;
+
+  // Limit the number of video feeds forwarded to each client
+  config.channelLastN = 4;
+
+matrix_jitsi_web_config_resolution_width_ideal_and_max: 480
+matrix_jitsi_web_config_resolution_height_ideal_and_max: 240
+```
+
+You may want to **suspend unused video layers** until they are requested again, to save up resources on both server and clients.
 Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/)
 For this add this line to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
 
-```yaml
-matrix_jitsi_web_config_enableLayerSuspension: true
-```
+You may wish to **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.
 
-You may wish to disable audio levels to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.
-For this add this line to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
-
-```yaml
-matrix_jitsi_web_config_disableAudioLevels: true
-```
-
-You may want to limit the number of video feeds forwarded to each client, to save up resources on both server and clients. As clients’ bandwidth and CPU may not bear the load, use this setting to avoid lag and crashes.
+You may want to **limit the number of video feeds forwarded to each client**, to save up resources on both server and clients. As clients’ bandwidth and CPU may not bear the load, use this setting to avoid lag and crashes.
 This feature is found by default in other webconference applications such as Office 365 Teams (limit is set to 4).
-Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/doc/last-n.md) and performance evaluation on this [study](https://jitsi.org/wp-content/uploads/2016/12/nossdav2015lastn.pdf)
-For this add this line to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
+Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/doc/last-n.md) and performance evaluation on this [study](https://jitsi.org/wp-content/uploads/2016/12/nossdav2015lastn.pdf).
 
-```yaml
-matrix_jitsi_web_config_channelLastN: 4
-```
+You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
 
-To enable the variables that allow you to manage the video configuration you must add the following line to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
-
-```yaml
-matrix_jitsi_web_config_constraints_enabled: true
-```
-
-You may want to limit the maximum video resolution, to save up resources on both server and clients.
-For example, to set resolution to 480.
-For this add this two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
-
-```yaml
-matrix_jitsi_web_config_constraints_video_height_ideal: 480
-matrix_jitsi_web_config_constraints_video_height_max: 480
-```
 
 ## Apply changes
 

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

@@ -23,3 +23,19 @@ matrix_nginx_proxy_proxy_matrix_nginx_status_allowed_addresses:
 - 8.8.8.8
 - 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:
+
+```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

@@ -113,7 +113,7 @@ With this, nginx would still be in use, but it would not bother with anything SS
 All services would be served locally on `127.0.0.1:81` and `127.0.0.1:8449` (as per the example configuration above).
 
 You can then set up another reverse-proxy server on ports 80/443/8448 for all of the expected domains and make traffic go to these local ports.
-The expected domains vary depending on the services you have enabled (`matrix.DOMAIN` for sure; `element.DOMAIN` and `dimension.DOMAIN` are optional).
+The expected domains vary depending on the services you have enabled (`matrix.DOMAIN` for sure; `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN` are optional).
 
 ### Sample configuration for running behind Traefik 2.0
 
@@ -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 }}`)"'
+  - '--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"'
@@ -172,7 +172,7 @@ matrix_synapse_container_extra_arguments:
   - '--label "traefik.http.services.matrix-synapse.loadbalancer.server.port=8048"'
 ```
 
-This method uses labels attached to the Nginx and Synapse containers to provide the Traefik Docker provider with the information it needs to proxy `matrix.DOMAIN`, `element.DOMAIN`, and `dimension.DOMAIN`. Some [static configuration](https://docs.traefik.io/v2.0/reference/static-configuration/file/) is required in Traefik; namely, having endpoints on ports 443 and 8448 and having a certificate resolver.
+This method uses labels attached to the Nginx and Synapse containers to provide the Traefik Docker provider with the information it needs to proxy `matrix.DOMAIN`, `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN`. Some [static configuration](https://docs.traefik.io/v2.0/reference/static-configuration/file/) is required in Traefik; namely, having endpoints on ports 443 and 8448 and having a certificate resolver.
 
 Note that this configuration on its own does **not** redirect traffic on port 80 (plain HTTP) to port 443 for HTTPS, which may cause some issues, since the built-in Nginx proxy usually does this. If you are not already doing this in Traefik, it can be added to Traefik in a [file provider](https://docs.traefik.io/v2.0/providers/file/) as follows:
 
@@ -193,3 +193,38 @@ Note that this configuration on its own does **not** redirect traffic on port 80
       scheme = "https"
       permanent = true
 ```
+
+You can use the following `docker-compose.yml` as example to launch Traefik.
+
+```yaml
+version: "3.3"
+
+services:
+
+  traefik:
+    image: "traefik:v2.3"
+    restart: always
+    container_name: "traefik"
+    networks:
+      - traefik
+    command:
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--providers.docker.network=traefik"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web-secure.address=:443"
+      - "--entrypoints.synapse.address=:8448"
+      - "--certificatesresolvers.default.acme.tlschallenge=true"
+      - "--certificatesresolvers.default.acme.email=YOUR EMAIL"
+      - "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"
+    ports:
+      - "443:443"
+      - "8080:8080"
+    volumes:
+      - "./letsencrypt:/letsencrypt"
+      - "/var/run/docker.sock:/var/run/docker.sock:ro"
+
+networks:
+  traefik:
+    external: true
+```

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-synapse-admin.md

@@ -15,6 +15,8 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
 matrix_synapse_admin_enabled: true
 ```
 
+**Note**: Synapse Admin requires Synapse's [Admin APIs](https://github.com/matrix-org/synapse/tree/master/docs/admin_api) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, we **automatically** exposes them publicly for you (equivalent to `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true`).
+
 
 ## Installing
 

docs/configuring-playbook-synapse.md

@@ -21,3 +21,8 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
 ## Synapse Admin
 
 Certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace, if you install [Synapse Admin](configuring-playbook-synapse-admin.md).
+
+
+## Synapse + OpenID Connect for Single-Sign-On
+
+If you'd like to use OpenID Connect authentication with Synapse, you'll need some additional reverse-proxy configuration (see [our nginx reverse-proxy doc page](configuring-playbook-nginx.md#synapse-openid-connect-for-single-sign-on)).

docs/configuring-playbook.md

@@ -33,6 +33,7 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up the Jitsi video-conferencing platform](configuring-playbook-jitsi.md) (optional)
 
+- [Setting Dynamic DNS](configuring-playbook-dynamic-dns.md) (optional)
 
 ### Core service adjustments
 

docs/howto-server-delegation.md

@@ -89,7 +89,7 @@ matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: /matrix/ssl/
 If your files are not in `/matrix/ssl` but in some other location, you would need to mount them into the container:
 
 ```yaml
-matrix_synapse_container_extra_arguments:
+matrix_nginx_proxy_container_extra_arguments:
   - "--mount type=bind,src=/some/path/on/the/host,dst=/some/path/inside/the/container,ro"
 ```
 

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-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/uninstalling.md

@@ -1,24 +1,40 @@
 # Uninstalling
 
-**Note**: If you have some trouble with your installation configuration, you can just [re-run the playbook](installing.md) and it will try to set things up again. You don't need to uninstall and install fresh.
+**Warnings**:
 
-However, if you've installed this on some server where you have other stuff you wish to preserve, and now want get rid of Matrix, it's enough to do these:
+- If your server federates with others, make sure to **leave any federated rooms before nuking your Matrix server's data**. Otherwise, the next time you set up a Matrix server for this domain (regardless of the installation method you use), you'll encounter trouble federating.
 
-- ensure all Matrix services are stopped (`systemctl stop 'matrix*'`)
+- If you have some trouble with your installation, you can just [re-run the playbook](installing.md) and it will try to set things up again. **Uninstalling and then installing anew rarely solves anything**.
 
-- delete the Matrix-related systemd .service files (`rm -f /etc/systemd/system/matrix*`) and reload systemd (`systemctl daemon-reload`)
+
+-----------------
+
+
+## Uninstalling using a script
+
+Installing places a `/usr/local/bin/matrix-remove-all` script on the server.
+
+You can run it to to have it uninstall things for you automatically (see below). **Use with caution!**
+
+
+## Uninstalling manually
+
+If you prefer to uninstall manually, run these commands (most are meant to be executed on the Matrix server itself):
+
+- ensure all Matrix services are stopped: `ansible-playbook -i inventory/hosts setup.yml --tags=stop` (if you can't get Ansible working to run this command, you can run `systemctl stop 'matrix*'` manually on the server)
+
+- delete the Matrix-related systemd `.service` files (`rm -f /etc/systemd/system/matrix*.service`) and reload systemd (`systemctl daemon-reload`)
 
 - delete all Matrix-related cronjobs (`rm -f /etc/cron.d/matrix*`)
 
 - delete some helper scripts (`rm -f /usr/local/bin/matrix*`)
 
-- delete some cached Docker images (or just delete them all: `docker rmi $(docker images -aq)`)
+- delete some cached Docker images (`docker system prune -a`) or just delete them all (`docker rmi $(docker images -aq)`)
 
-- delete the Docker network: `docker network rm matrix`
+- delete the Docker network: `docker network rm matrix` (might have been deleted already if you ran the `docker system prune` command)
 
 - uninstall Docker itself, if necessary
 
 - delete the `/matrix` directory (`rm -rf /matrix`)
 
-The script `/usr/local/bin/matrix-remove-all` performs all these steps (**use with caution!**).
 

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.