Merge branch 'master' of https://github.com/spantaleev/matrix-docker-ansible-deploy

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

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-nginx.md

@@ -55,3 +55,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.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/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.