Merge pull request #3667 from luixxiul/fix

Edit line breaks in sentences and paragraphs

docs/ansible.md

@@ -3,8 +3,7 @@
 
 This playbook is meant to be run using [Ansible](https://www.ansible.com/).
 
-Ansible typically runs on your local computer and carries out tasks on a remote server.
+Ansible typically runs on your local computer and carries out tasks on a remote server. If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
-If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
 
 
 ## Supported Ansible versions
@@ -13,8 +12,7 @@ To manually check which version of Ansible you're on, run: `ansible --version`.
 
 For the **best experience**, we recommend getting the **latest version of Ansible available**.
 
-We're not sure what's the minimum version of Ansible that can run this playbook successfully.
+We're not sure what's the minimum version of Ansible that can run this playbook successfully. The lowest version that we've confirmed (on 2022-11-26) to be working fine is: `ansible-core` (`2.11.7`) combined with `ansible` (`4.10.0`).
-The lowest version that we've confirmed (on 2022-11-26) to be working fine is: `ansible-core` (`2.11.7`) combined with `ansible` (`4.10.0`).
 
 If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
 
@@ -30,8 +28,7 @@ Depending on your distribution, you may be able to upgrade Ansible in a few diff
 If using the `pip` method, do note that the `ansible-playbook` binary may not be on the `$PATH` (https://linuxconfig.org/linux-path-environment-variable), but in some more special location like `/usr/local/bin/ansible-playbook`. You may need to invoke it using the full path.
 
 
-**Note**: Both of the above methods are a bad way to run system software such as Ansible.
+**Note**: Both of the above methods are a bad way to run system software such as Ansible. If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
-If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
 
 
 ## Using Ansible via Docker
@@ -45,8 +42,7 @@ You can either [run Ansible in a container on the Matrix server itself](#running
 
 ### Running Ansible in a container on the Matrix server itself
 
-To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation.
+To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation. Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
-Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
 
 - you **either** need to install Docker manually first. Follow [the upstream instructions](https://docs.docker.com/engine/install/) for your distribution and consider setting `matrix_playbook_docker_installation_enabled: false` in your `vars.yml` file, to prevent the playbook from installing Docker
 - **or** you need to run the playbook in another way (e.g. [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)) at least the first time around
@@ -54,6 +50,7 @@ Docker is normally installed by the playbook, so this may be a bit of a chicken
 Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/..`, etc.), as described in [configuring the playbook](configuring-playbook.md).
 
 You would then need to add `ansible_connection=community.docker.nsenter` to the host line in `inventory/hosts`. This tells Ansible to connect to the "remote" machine by switching Linux namespaces with [nsenter](https://man7.org/linux/man-pages/man1/nsenter.1.html), instead of using SSH.
+
 Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `ansible-playbook --connection=community.docker.nsenter ...`
 
 Run this from the playbook's directory:
@@ -68,8 +65,7 @@ docker run -it --rm \
 docker.io/devture/ansible:2.17.0-r0-1
 ```
 
-Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container.
+Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container. The `/work` directory contains the playbook's code.
-The `/work` directory contains the playbook's code.
 
 First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
 
@@ -89,11 +85,9 @@ docker run -it --rm \
 docker.io/devture/ansible:2.17.0-r0-1
 ```
 
-The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`).
+The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`). If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part.
-If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part.
 
-Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container.
+Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container. The `/work` directory contains the playbook's code.
-The `/work` directory contains the playbook's code.
 
 First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
 
@@ -103,6 +97,7 @@ Finally, you execute `ansible-playbook ...` commands as per normal now.
 #### If you don't use SSH keys for authentication
 
 If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
+
 To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it ...` command), run:
 ```bash
 apk add sshpass

docs/configuring-captcha.md

@@ -2,6 +2,7 @@
 
 # Overview
 Captcha can be enabled for this home server. This file explains how to do that.
+
 The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.
 
 ## ReCaptcha

docs/configuring-dns.md

@@ -2,18 +2,16 @@
 
 To set up Matrix on your domain, you'd need to do some DNS configuration.
 
-To use an identifier like `@<username>:example.com`, you don't actually need
+To use an identifier like `@<username>:example.com`, you don't actually need to install anything on the actual `example.com` server.
-to install anything on the actual `example.com` server.
+
+You do, however, need to instruct the Matrix network that Matrix services for `example.com` are delegated over to `matrix.example.com`.
 
-You do, however need to instruct the Matrix network that Matrix services for `example.com` are delegated
-over to `matrix.example.com`.
 As we discuss in [Server Delegation](howto-server-delegation.md), there are 2 different ways to set up such delegation:
 
 - either by serving a `https://example.com/.well-known/matrix/server` file (from the base domain!)
 - or by using a `_matrix._tcp` DNS SRV record (don't confuse this with the `_matrix-identity._tcp` SRV record described below)
 
-This playbook mostly discusses the well-known file method, because it's easier to manage with regard to certificates.
+This playbook mostly discusses the well-known file method, because it's easier to manage with regard to certificates. If you decide to go with the alternative method ([Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)), please be aware that the general flow that this playbook guides you through may not match what you need to do.
-If you decide to go with the alternative method ([Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)), please be aware that the general flow that this playbook guides you through may not match what you need to do.
 
 ## DNS settings for services enabled by default
 
@@ -57,8 +55,7 @@ When setting up a SRV record, if you are asked for a service and protocol instea
 
 As the table above illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` record is fine).
 
-The `element.example.com` subdomain may be necessary, because this playbook installs the [Element](https://github.com/element-hq/element-web) web client for you.
+The `element.example.com` subdomain may be necessary, because this playbook installs the [Element](https://github.com/element-hq/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.example.com` DNS record.
-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.example.com` DNS record.
 
 The `dimension.example.com` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. The installation of Dimension 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.example.com` DNS record.
 
@@ -100,5 +97,4 @@ When you're done with the DNS configuration and ready to proceed, continue with
 
 ## `_dmarc`, `postmoogle._domainkey` TXT and `matrix` MX records setup
 
-To make the [postmoogle](configuring-playbook-bot-postmoogle.md) email bridge enable its email sending features, you need to configure
+To make the [postmoogle](configuring-playbook-bot-postmoogle.md) email bridge enable its email sending features, you need to configure SPF (TXT), DMARC (TXT), DKIM (TXT) and MX records
-SPF (TXT), DMARC (TXT), DKIM (TXT) and MX records

docs/configuring-playbook-appservice-draupnir-for-all.md

@@ -24,8 +24,7 @@ Draupnir for all does not support external tooling like [MRU](https://mru.rory.g
 
 The playbook does not create a management room for your Main Draupnir. This task you have to do on your own.
 
-The management room has to be given an alias and be public when you are setting up the bot for the first time as the bot does not differentiate between invites
+The management room has to be given an alias and be public when you are setting up the bot for the first time as the bot does not differentiate between invites and invites to the management room.
-and invites to the management room.
 
 This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element calls this powerlevel.
 

docs/configuring-playbook-backup-borg.md

@@ -1,8 +1,8 @@
 # Setting up borg backup (optional)
 
 The playbook can install and configure [borgbackup](https://www.borgbackup.org/) with [borgmatic](https://torsion.org/borgmatic/) for you.
-BorgBackup is a deduplicating backup program with optional compression and encryption.
+
-That means your daily incremental backups can be stored in a fraction of the space and is safe whether you store it at home or on a cloud service.
+BorgBackup is a deduplicating backup program with optional compression and encryption. That means your daily incremental backups can be stored in a fraction of the space and is safe whether you store it at home or on a cloud service.
 
 You will need a remote server where borg will store the backups. There are hosted, borg compatible solutions available, such as [BorgBase](https://www.borgbase.com).
 
@@ -76,6 +76,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
 ## Manually start a backup
 
-For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server
+For testing your setup it can be helpful to not wait until 4am. If you want to run the backup immediately, log onto the server and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly a long time. Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.
-and run `systemctl start matrix-backup-borg`. This will not return until the backup is done, so possibly a long time.
-Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

docs/configuring-playbook-base-domain-serving.md

@@ -1,8 +1,6 @@
 # Serving the base domain
 
-This playbook sets up services on your Matrix server (`matrix.example.com`).
+This playbook sets up services on your Matrix server (`matrix.example.com`). To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up [Server Delegation](howto-server-delegation.md). This is normally done by [configuring well-known](configuring-well-known.md) files on the base domain.
-To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up [Server Delegation](howto-server-delegation.md).
-This is normally done by [configuring well-known](configuring-well-known.md) files on the base domain.
 
 People who don't have a separate server to dedicate to the base domain have trouble arranging this.
 
@@ -31,8 +29,7 @@ Doing this, the playbook will:
 
 ## Serving a static website at the base domain
 
-By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage at `/matrix/static-files/public/index.html`.
+By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage at `/matrix/static-files/public/index.html`. The content of this page is taken from the `matrix_static_files_file_index_html_template` variable.
-The content of this page is taken from the `matrix_static_files_file_index_html_template` variable.
 
 If you'd like to host your own static website (more than a single `index.html` page) at the base domain, you can disable the creation of this default `index.html` page like this:
 
@@ -50,8 +47,7 @@ matrix_static_files_container_labels_base_domain_root_path_redirection_enabled:
 
 With this configuration, Ansible will no longer mess around with the `/matrix/static-files/public/index.html` file.
 
-You are then free to upload any static website files to `/matrix/static-files/public` and they will get served at the base domain.
+You are then free to upload any static website files to `/matrix/static-files/public` and they will get served at the base domain. You can do so manually or by using the [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role, which is part of this playbook already.
-You can do so manually or by using the [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role, which is part of this playbook already.
 
 
 ## Serving a more complicated website at the base domain

docs/configuring-playbook-bot-draupnir.md

@@ -110,6 +110,7 @@ matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
 ### 5c. Migrating from Mjolnir (Only required if migrating.)
 
 Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable Mjolnir if you're doing migration.
+
 That is all you need to do due to that Draupnir can complete migration on its own.
 
 ## 6. Installing
@@ -137,8 +138,7 @@ Draupnir can be told to self-join public rooms, but it's better to follow this f
 
 3. Tell it to protect the room (using the [rooms command](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#using-the-draupnir-rooms-command)) by sending the following command to the Management Room: `!draupnir rooms add !qporfwt:example.com`
 
-To have Draupnir provide useful room protection, you need do to a bit more work (at least the first time around).
+To have Draupnir provide useful room protection, you need do to a bit more work (at least the first time around). You may wish to [Subscribe to a public policy list](#subscribing-to-a-public-policy-list), [Create your own own policy and rules](#creating-your-own-policy-lists-and-rules) and [Enabling built-in protections](#enabling-built-in-protections).
-You may wish to [Subscribe to a public policy list](#subscribing-to-a-public-policy-list), [Create your own own policy and rules](#creating-your-own-policy-lists-and-rules) and [Enabling built-in protections](#enabling-built-in-protections).
 
 ### Giving Draupnir permissions to do its job
 
@@ -213,14 +213,14 @@ matrix_bot_draupnir_configuration_extension_yaml: |
 
 Draupnir supports two methods to receive reports in the management room.
 
-The first method intercepts the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver.
+The first method intercepts the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver. If you are using traefik, this playbook can set this up for you:
-If you are using traefik, this playbook can set this up for you:
+
 ```yaml
 matrix_bot_draupnir_abuse_reporting_enabled: true
 ```
 
-The other method polls an synapse admin API endpoint and is hence only available when using synapse and when the Draupnir user is an admin user (see step 1).
+The other method polls an synapse admin API endpoint and is hence only available when using synapse and when the Draupnir user is an admin user (see step 1). To enable it, set `pollReports: true` in Draupnir's config:
-To enable it, set `pollReports: true` in Draupnir's config:
+
 ```yaml
 matrix_bot_draupnir_configuration_extension_yaml: |
   pollReports: true

docs/configuring-playbook-bot-matrix-registration-bot.md

@@ -2,11 +2,9 @@
 
 The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
 
-The bot allows you to easily **create and manage registration tokens** aka. invitation codes.
+The bot allows you to easily **create and manage registration tokens** aka. invitation codes. It can be used for an invitation-based server, where you invite someone by sending them a registration token (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process.
-It can be used for an invitation-based server, where you invite someone by sending them a registration token (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process.
 
-See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
+See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it does and why it might be useful to you.
-does and why it might be useful to you.
 
 
 ## Configuration
@@ -43,8 +41,8 @@ To use the bot, start a chat with `@bot.matrix-registration-bot:example.com` (wh
 In this room send `help` and the bot will reply with all options.
 
 You can also refer to the upstream [Usage documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands).
-If you have any questions, or if you need help setting it up, read the [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md)
+
-or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
+If you have any questions, or if you need help setting it up, read the [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md) or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
 
 To clean the cache (session & encryption data) after you changed the bot's username, changed the login method from access_token to password etc... you can use:
 

docs/configuring-playbook-bot-maubot.md

@@ -2,11 +2,9 @@
 
 The playbook can install and configure [maubot](https://github.com/maubot/maubot) for you.
 
-After setting up maubot, you can use the web management interface to make it do things.
+After setting up maubot, you can use the web management interface to make it do things. The default location of the management interface is `matrix.example.com/_matrix/maubot/`
-The default location of the management interface is `matrix.example.com/_matrix/maubot/`
 
-See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) to learn what it
+See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) to learn what it does and why it might be useful to you.
-does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
@@ -64,8 +62,7 @@ By default, you can visit `matrix.example.com/_matrix/maubot/` to manage your av
 You should start in the following order
 1. **Create one or more clients**: A client is a Matrix account which the bot will use to message. By default, the playbook creates a `bot.maubot` account (as per the configuration above). You only need to [obtain an access token](#obtaining-an-access-token) for it
 2. **Upload some Plugins**: Plugins can be obtained from [here](https://github.com/maubot/maubot#plugins) or any other source.
-3. **Create an instance**: An instance is the actual bot. You have to specify a client which the bot instance will use
+3. **Create an instance**: An instance is the actual bot. You have to specify a client which the bot instance will use and the plugin (how the bot will behave)
-and the plugin (how the bot will behave)
 
 ## Obtaining an access token
 

docs/configuring-playbook-bot-postmoogle.md

@@ -4,8 +4,7 @@
 
 The playbook can install and configure [Postmoogle](https://github.com/etkecc/postmoogle) for you.
 
-It's a bot/bridge you can use to forward emails to Matrix rooms.
+Postmoogle is a bot/bridge you can use to forward emails to Matrix rooms. It runs an SMTP email server and allows you to assign mailbox addresses to Matrix rooms.
-Postmoogle runs an SMTP email server and allows you to assign mailbox addresses to Matrix rooms.
 
 See the project's [documentation](https://github.com/etkecc/postmoogle) to learn what it does and why it might be useful to you.
 

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

@@ -17,8 +17,7 @@ matrix_appservice_webhooks_enabled: true
 matrix_appservice_webhooks_api_secret: '<your_secret>'
 ```
 
-2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
+2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service` you can adjust this in `inventory/host_vars/matrix.example.com/vars.yml` as well.
-you can adjust this in `inventory/host_vars/matrix.example.com/vars.yml` as well.
 
 **Note**: default value is: `info` and availabe log levels are : `info`, `verbose`
 

docs/configuring-playbook-bridge-go-skype-bridge.md

@@ -1,7 +1,6 @@
 # Setting up Go Skype Bridge (optional)
 
-The playbook can install and configure
+The playbook can install and configure [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.
-[go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.
 
 See the project page to learn what it does and why it might be useful to you.
 
@@ -19,8 +18,6 @@ After configuring the playbook, run the [installation](installing.md) command: `
 
 ## Usage
 
-Once the bot is enabled, you need to start a chat with `Skype bridge bot`
+Once the bot is enabled, you need to start a chat with `Skype bridge bot` with the handle `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
-with the handle `@skypebridgebot:example.com` (where `example.com` is your base
-domain, not the `matrix.` domain).
 
 Send `help` to the bot to see the commands available.

docs/configuring-playbook-bridge-mautrix-meta-messenger.md

@@ -30,6 +30,7 @@ Before proceeding to [re-running the playbook](./installing.md), you may wish to
 ### Bridge mode
 
 As mentioned above, the [mautrix-meta](https://github.com/mautrix/meta) bridge supports multiple modes of operation.
+
 The bridge can pull your Messenger messages via 3 different methods:
 
 - (`facebook`) Facebook via `facebook.com`

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

@@ -65,8 +65,7 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
       '@user:example.com': admin
 ```
 
-More details about permissions in this example:
+More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
-https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
 
 If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration:
 ```yaml

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

@@ -15,17 +15,18 @@ matrix_mautrix_whatsapp_enabled: true
 Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
 
 The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file:
+
 ```yaml
 matrix_mautrix_whatsapp_bridge_relay_enabled: true
 ```
 
 By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users add this to your `vars.yml` file:
+
 ```yaml
 matrix_mautrix_whatsapp_bridge_relay_admin_only: false
 ```
 
-If you want to activate the relay bot in a room, use `!wa set-relay`.
+If you want to activate the relay bot in a room, send `!wa set-relay`. To deactivate, send `!wa unset-relay`.
-Use `!wa unset-relay` to deactivate.
 
 ## Installing
 

docs/configuring-playbook-dimension.md

@@ -1,7 +1,6 @@
 # Setting up Dimension (optional)
 
-**[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.**
+**[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.
-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**: Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
 
@@ -17,8 +16,7 @@ matrix_dimension_enabled: true
 
 ### Define admin users
 
-These users can modify the integrations this Dimension supports.
+These users can modify the integrations this Dimension supports. Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
-Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
 
 ```yaml
 matrix_dimension_admins:
@@ -30,11 +28,9 @@ The admin interface is accessible within Element by accessing it in any room and
 
 ### Access token
 
-We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username).
+We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username). Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
-Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
 
-You are required to specify an access token (belonging to this new user) for Dimension to work.
+You are required to specify an access token (belonging to this new user) for Dimension to work. To get an access token for the Dimension user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
-To get an access token for the Dimension user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
 
 **Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
 
@@ -91,7 +87,6 @@ In the interim until the above limitation is resolved, an admin user needs to co
 
 ## Additional features
 
-To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it.
+To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.
-To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.
 
 You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).

docs/configuring-playbook-dynamic-dns.md

@@ -2,10 +2,10 @@
 
 ## Setup
 
-Most cloud providers / ISPs will charge you extra for a static IP address. If you're
+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.
-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
+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).
-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.example.com/vars.yml`:
 
 ```yaml

docs/configuring-playbook-email.md

@@ -2,8 +2,7 @@
 
 By default, this playbook sets up an [Exim](https://www.exim.org/) email server through which all Matrix services send emails.
 
-The email server would attempt to deliver emails directly to their final destination.
+The email server would attempt to deliver emails directly to their final destination. This may or may not work, depending on your domain configuration (SPF settings, etc.)
-This may or may not work, depending on your domain configuration (SPF settings, etc.)
 
 By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.
 

docs/configuring-playbook-federation.md

@@ -1,7 +1,6 @@
 # Controlling Matrix federation (optional)
 
-By default, your server federates with the whole Matrix network.
+By default, your server federates with the whole Matrix network. That is, people on your server can communicate with people on any other Matrix server.
-That is, people on your server can communicate with people on any other Matrix server.
 
 
 ## Federating only with select servers

docs/configuring-playbook-jitsi.md

@@ -49,16 +49,14 @@ By default the Jitsi Meet instance does not require any kind of login and is ope
 If you're fine with such an open Jitsi instance, please skip to [Apply changes](#apply-changes).
 
 If you would like to control who is allowed to open meetings on your new Jitsi instance, then please follow the following steps to enable Jitsi's authentication and optionally guests mode.
+
 Currently, there are three supported authentication modes: 'internal' (default), 'matrix' and 'ldap'.
 
-**Note**: Authentication is not tested via the playbook's self-checks.
+**Note**: Authentication is not tested via the playbook's self-checks. We therefore recommend that you manually verify if authentication is required by jitsi. For this, try to manually create a conference on jitsi.example.com in your browser.
-We therefore recommend that you manually verify if authentication is required by jitsi.
-For this, try to manually create a conference on jitsi.example.com in your browser.
 
 ### Authenticate using Jitsi accounts (Auth-Type 'internal')
-The default authentication mechanism is 'internal' auth, which requires jitsi-accounts to be setup and is the recommended setup, as it also works in federated rooms.
+
-With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join.
+The default authentication mechanism is 'internal' auth, which requires jitsi-accounts to be setup and is the recommended setup, as it also works in federated rooms. With authentication enabled, all meeting rooms have to be opened by a registered user, after which guests are free to join. If a registered host is not yet present, guests are put on hold in individual waiting rooms.
-If a registered host is not yet present, guests are put on hold in individual waiting rooms.
 
 Add these lines to your `inventory/host_vars/matrix.example.com/vars.yml` configuration:
 
@@ -80,8 +78,7 @@ jitsi_prosody_auth_internal_accounts:
 
 **Attention: Probably breaks Jitsi in federated rooms and does not allow sharing conference links with guests.**
 
-Using this authentication type require a [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service).
+Using this authentication type require a [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service). By default, this playbook creates and configures a user-verification-service to run locally, see [configuring-user-verification-service](configuring-playbook-user-verification-service.md).
-By default, this playbook creates and configures a user-verification-service to run locally, see [configuring-user-verification-service](configuring-playbook-user-verification-service.md).
 
 To enable set this configuration at host level:
 
@@ -150,14 +147,11 @@ jitsi_web_config_resolution_width_ideal_and_max: 480
 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.
+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/)
-Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/)
 
 You may wish to **disable audio levels** to avoid excessive refresh of the client-side page and decrease the CPU consumption involved.
 
-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).
-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).
 
 You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
 
@@ -175,8 +169,7 @@ jitsi_prosody_max_participants: 4 # example value
 
 By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)) is deployed on the same host as the Matrix server. To allow more video-conferences to happen at the same time, you may need to provision additional JVB services on other hosts.
 
-There is an ansible playbook that can be run with the following tag:
+There is an ansible playbook that can be run with the following tag: `ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
-`ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
 
 For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
 ```
@@ -184,9 +177,7 @@ For this role to work you will need an additional section in the ansible hosts f
 <your jvb hosts> ansible_host=<ip address of the jvb host>
 ```
 
-Each JVB will require a server ID to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB.
+Each JVB will require a server ID to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB. The server ID is set with the variable `jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container. This variable can be set via the host file, a parameter to the ansible command or in the `vars.yaml` for the host which will have the additional JVB. For example:
-The server ID is set with the variable `jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container.
-This variable can be set via the host file, a parameter to the ansible command or in the `vars.yaml` for the host which will have the additional JVB. For example:
 
 ``` yaml
 jitsi_jvb_server_id: 'jvb-2'
@@ -206,8 +197,7 @@ The additional JVB will also need to expose the colibri web socket port and this
 jitsi_jvb_container_colibri_ws_host_bind_port: 9090
 ```
 
-The JVB will also need to know where the prosody xmpp server is located, similar to the server ID this can be set in the vars for the JVB by using the variable
+The JVB will also need to know where the prosody xmpp server is located, similar to the server ID this can be set in the vars for the JVB by using the variable `jitsi_xmpp_server`. The Jitsi prosody container is deployed on the Matrix server by default so the value can be set to the Matrix domain. For example:
-`jitsi_xmpp_server`. The Jitsi prosody container is deployed on the Matrix server by default so the value can be set to the Matrix domain. For example:
 
 ```yaml
 jitsi_xmpp_server: "{{ matrix_domain }}"
@@ -219,9 +209,7 @@ However, it can also be set the ip address of the Matrix server. This can be use
 jitsi_xmpp_server: "192.168.0.1"
 ```
 
-For the JVB to be able to contact the XMPP server, the latter must expose the XMPP port (5222). By default, the Matrix server does not expose the
+For the JVB to be able to contact the XMPP server, the latter must expose the XMPP port (5222). By default, the Matrix server does not expose the port; only the XMPP container exposes it internally inside the host, which means that the first JVB (which runs on the Matrix server) can reach it but the additional JVB cannot. The port is exposed by setting `jitsi_prosody_container_jvb_host_bind_port` like this:
-port; only the XMPP container exposes it internally inside the host, which means that the first JVB (which runs on the Matrix server) can reach it but
-the additional JVB cannot. The port is exposed by setting `jitsi_prosody_container_jvb_host_bind_port` like this:
 
 ```yaml
 jitsi_prosody_container_jvb_host_bind_port: 5222
@@ -229,8 +217,7 @@ jitsi_prosody_container_jvb_host_bind_port: 5222
 
 (The default is empty; if it's set then docker forwards the port.)
 
-Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo
+Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo to route conferences too.
-to route conferences too.
 
 To make Traefik reverse-proxy to these additional JVBs (living on other hosts), **you would need to add the following Traefik configuration extension**:
 
@@ -270,8 +257,7 @@ traefik_provider_configuration_extension_yaml: |
 
 ## (Optional) Enable Gravatar
 
-In the default Jisti Meet configuration, gravatar.com is enabled as an avatar service. This results in third party request leaking data to gravatar.
+In the default Jisti Meet configuration, gravatar.com is enabled as an avatar service. This results in third party request leaking data to gravatar. Since element already sends the url of configured Matrix avatars to Jitsi, we disabled gravatar.
-Since element already sends the url of configured Matrix avatars to Jitsi, we disabled gravatar.
 
 To enable Gravatar set:
 
@@ -279,8 +265,7 @@ To enable Gravatar set:
 jitsi_disable_gravatar: false
 ```
 
-**Beware**: This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com).
+**Beware**: This leaks information to a third party, namely the Gravatar-Service (unless configured otherwise: gravatar.com). Besides metadata, this includes the Matrix user_id and possibly the room identifier (via `referrer` header).
-Besides metadata, this includes the Matrix user_id and possibly the room identifier (via `referrer` header).
 
 ## Installing
 

docs/configuring-playbook-ma1sd.md

@@ -32,8 +32,7 @@ matrix_ma1sd_matrixorg_forwarding_enabled: true
 
 ### Customizing email templates
 
-If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables
+If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables (in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.
-(in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.
 
 ## Installing
 
@@ -84,12 +83,9 @@ What this playbook configures for your is some bare minimum Identity Server func
 
 A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
 
-Still, ma1sd can do much more.
+Still, ma1sd can do much more. You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
-You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
 
-To use a more custom configuration, you can define a `matrix_ma1sd_configuration_extension_yaml` string variable
+To use a more custom configuration, you can define a `matrix_ma1sd_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
-and put your configuration in it.
-To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
 
 ## Example: SMS verification
 

docs/configuring-playbook-matrix-corporal.md

@@ -8,8 +8,7 @@
 
 The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you.
 
-In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment.
+In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment. See that project's documentation to learn what it does and why it might be useful to you.
-See that project's documentation to learn what it does and why it might be useful to you.
 
 If you decide that you'd like to let this playbook install it for you, you'd need to also:
 - (required) [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md)
@@ -71,8 +70,8 @@ matrix_synapse_rc_login:
     burst_count: 3
 ```
 
-Matrix Corporal operates with a specific Matrix user on your server.
+Matrix Corporal operates with a specific Matrix user on your server. By default, it's `matrix-corporal` (controllable by the `matrix_corporal_reconciliation_user_id_local_part` setting, see above).
-By default, it's `matrix-corporal` (controllable by the `matrix_corporal_reconciliation_user_id_local_part` setting, see above).
+
 No matter what Matrix user ID you configure to run it with, make sure that:
 
 - the Matrix Corporal user is created by [registering it](registering-users.md) **with administrator privileges**. Use a password you remember, as you'll need to log in from time to time to create or join rooms

docs/configuring-playbook-matrix-ldap-registration-proxy.md

@@ -4,8 +4,7 @@ The playbook can install and configure [matrix-ldap-registration-proxy](https://
 
 This proxy handles Matrix registration requests and forwards them to LDAP.
 
-**Note**: This does support the full Matrix specification for registrations. It only provide a very coarse
+**Note**: This does support the full Matrix specification for registrations. It only provide a very coarse implementation of a basic password registration.
-implementation of a basic password registration.
 
 ## Quickstart
 
@@ -20,8 +19,7 @@ matrix_ldap_registration_proxy_ldap_user: <USER>
 matrix_ldap_registration_proxy_ldap_password: <password>
 ```
 
-If you already use the [synapse external password provider via LDAP](configuring-playbook-ldap-auth.md) (that is, you have `matrix_synapse_ext_password_provider_ldap_enabled: true` and other options in your configuration)
+If you already use the [synapse external password provider via LDAP](configuring-playbook-ldap-auth.md) (that is, you have `matrix_synapse_ext_password_provider_ldap_enabled: true` and other options in your configuration) you can use the following values as configuration:
-you can use the following values as configuration:
 
 ```yaml
 # Use the LDAP values specified for the synapse role to setup LDAP proxy

docs/configuring-playbook-matrix-registration.md

@@ -78,8 +78,7 @@ ansible-playbook -i inventory/hosts setup.yml \
 --extra-vars="one_time=yes ex_date=2021-12-31"
 ```
 
-The above command creates and returns a **one-time use** token, which **expires** on the 31st of December 2021.
+The above command creates and returns a **one-time use** token, which **expires** on the 31st of December 2021. Adjust the `one_time` and `ex_date` variables as you see fit.
-Adjust the `one_time` and `ex_date` variables as you see fit.
 
 Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
 

docs/configuring-playbook-mautrix-bridges.md

@@ -1,7 +1,6 @@
 # Setting up a Generic Mautrix Bridge (optional)
 
-The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, facebook, instagram, signal, hangouts, googlechat, etc.), as well as many other (non-mautrix) bridges.
+The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, facebook, instagram, signal, hangouts, googlechat, etc.), as well as many other (non-mautrix) bridges. This is a common guide for configuring mautrix bridges.
-This is a common guide for configuring mautrix bridges.
 
 You can see each bridge's features at in the `ROADMAP.md` file in its corresponding [mautrix](https://github.com/mautrix) repository.
 
@@ -132,4 +131,5 @@ If you run into trouble, check the [Troubleshooting](#troubleshooting) section b
 ## Troubleshooting
 
 For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
+
 Reporting bridge bugs should happen upstream, in the corresponding mautrix repository, not to us.

docs/configuring-playbook-own-webserver.md

@@ -189,8 +189,7 @@ Such a configuration would expose all services on a local port `81` and Matrix F
 
 Your reverse-proxy configuration needs to send traffic to these ports. The [`examples/reverse-proxies` directory](../examples/reverse-proxies/) contains sample configuration for various webservers (Apache2, Caddy, HAproxy, nginx, Nginx Proxy Manager).
 
-It's important that these webservers proxy-pass requests to the correct place and also set the `Host` HTTP header appropriately.
+It's important that these webservers proxy-pass requests to the correct place and also set the `Host` HTTP header appropriately. If you don't pass the `Host` header correctly, you would get a 404 not found error from Traefik.
-If you don't pass the `Host` header correctly, you would get a 404 not found error from Traefik.
 
 To put it another way, `curl http://127.0.0.1:81` would give you a 404, but `curl -H 'Host: matrix.example.com' http://127.0.0.1:81` should work.
 

docs/configuring-playbook-prometheus-grafana.md

@@ -112,8 +112,7 @@ Name | Description
 
 If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.example.com/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`.
 
-The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`.
+The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`. It will look a bit like this:
-It will look a bit like this:
 ```yaml
 scrape_configs:
   - job_name: 'synapse'

docs/configuring-playbook-prometheus-nginxlog.md

@@ -26,10 +26,7 @@ After configuring the playbook, run the [installation](installing.md) command: `
 
 ## Docker Image Compatibility
 
-At the moment of writing only images for `amd64` and `arm64` architectures are available
+At the moment of writing only images for `amd64` and `arm64` architectures are available. The playbook currently does not support [self-building](./self-building.md) a container image on other architectures. You can however use a custom-build image by setting:
-
-The playbook currently does not support [self-building](./self-building.md) a container image on other architectures.
-You can however use a custom-build image by setting:
 
 ```yaml
 matrix_prometheus_nginxlog_exporter_docker_image_arch_check_enabled: false
@@ -38,8 +35,7 @@ matrix_prometheus_nginxlog_exporter_docker_image: path/to/docker/image:tag
 
 ## Security and privacy
 
-Metrics and resulting graphs can contain a lot of information. NginX logs contain information like IP address, URLs, UserAgents and more. This information can reveal usage patterns and could be considered Personally Identifiable Information (PII). Think about this before enabling (anonymous) access.
+Metrics and resulting graphs can contain a lot of information. NginX logs contain information like IP address, URLs, UserAgents and more. This information can reveal usage patterns and could be considered Personally Identifiable Information (PII). Think about this before enabling (anonymous) access. Please make sure you change the default Grafana password.
-Please make sure you change the default Grafana password.
 
 ## Save metrics on an external Prometheus server
 

docs/configuring-playbook-s3-goofys.md

@@ -1,7 +1,6 @@
 # Storing Matrix media files on Amazon S3 with Goofys (optional)
 
-If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
+If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service), you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
-you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
 
 Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md).
 

docs/configuring-playbook-sliding-sync-proxy.md

@@ -60,8 +60,7 @@ matrix_sliding_sync_database_name: 'matrix_sliding_sync'
 
 ## Usage
 
-You **don't need to do anything special** to make use of the Sliding Sync Proxy.
+You **don't need to do anything special** to make use of the Sliding Sync Proxy. Simply open your client which supports Sliding Sync (like Element X) and log in.
-Simply open your client which supports Sliding Sync (like Element X) and log in.
 
 When the Sliding Sync proxy is [installed](#installing), your `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc3575.proxy` section and `url` property are added there and made to point to your Sliding Sync proxy's base URL (e.g. `https://matrix.example.com/sliding-sync`).
 

docs/configuring-playbook-sygnal.md

@@ -44,8 +44,7 @@ For a more complete example of available fields and values they can take, see `r
 
 Configuring [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/) is easier, as it only requires that you provide some config values.
 
-To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Notification Service), you'd need to provide one or more certificate files.
+To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Notification Service), you'd need to provide one or more certificate files. To do that, the above example configuration:
-To do that, the above example configuration:
 
 - makes use of the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) (and its `aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See [`defaults/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml) of the `aux` role for usage examples. It also makes sure the files are owned by `matrix:matrix`, so that Sygnal can read them. Of course, you can also install these files manually yourself, if you'd rather not use `aux`.
 

docs/configuring-playbook-synapse-auto-accept-invite.md

@@ -2,8 +2,7 @@
 
 The playbook can install and configure [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) for you.
 
-See that project's [documentation](https://github.com/matrix-org/synapse-auto-accept-invite) to learn what it does and why it might be useful to you.
+See that project's [documentation](https://github.com/matrix-org/synapse-auto-accept-invite) to learn what it does and why it might be useful to you. In short, it automatically accepts room invites. You can specify that only 1:1 room invites are auto-accepted. Defaults to false if not specified.
-In short, it automatically accepts room invites. You can specify that only 1:1 room invites are auto-accepted. Defaults to false if not specified.
 
 **Note**: Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the same feature [has been merged](https://github.com/element-hq/synapse/pull/17147) into Synapse (see the [Native alternative](#native-alternative) section below). You'd better use the native feature, instead of the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module.
 

docs/configuring-playbook-synapse-auto-compressor.md

@@ -31,6 +31,4 @@ After installation, `synapse_auto_compressor` will run automatically every day a
 
 ## Manually start the tool
 
-For testing your setup it can be helpful to not wait until 00:00. If you want to run the tool immediately, log onto the server
+For testing your setup it can be helpful to not wait until 00:00. If you want to run the tool immediately, log onto the server and run `systemctl start matrix-synapse-auto-compressor`. Running this command will not return control to your terminal until the compression run is done, which may take a long time. Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.
-and run `systemctl start matrix-synapse-auto-compressor`. Running this command will not return control to your terminal until the compression run is done, which may take a long time.
-Consider using [tmux](https://en.wikipedia.org/wiki/Tmux) if your SSH connection is unstable.

docs/configuring-playbook-synapse-s3-storage-provider.md

@@ -1,7 +1,6 @@
 # Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider (optional)
 
-If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service),
+If you'd like to store Synapse's content repository (`media_store`) files on Amazon S3 (or other S3-compatible service), you can use the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) media provider module for Synapse.
-you can use the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) media provider module for Synapse.
 
 An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).
 

docs/configuring-playbook-synapse-simple-antispam.md

@@ -2,8 +2,7 @@
 
 The playbook can install and configure [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) for you.
 
-See that project's documentation to learn what it does and why it might be useful to you.
+See that project's documentation to learn what it does and why it might be useful to you. In short, it lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).
-In short, it lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-synapse.md

@@ -154,8 +154,7 @@ matrix_synapse_container_image_customizations_templates_git_repository_ssh_priva
   -----END OPENSSH PRIVATE KEY-----
 ```
 
-As mentioned in Synapse's Templates documentation, Synapse will fall back to its own templates if a template is not found in that directory.
+As mentioned in Synapse's Templates documentation, Synapse will fall back to its own templates if a template is not found in that directory. Due to this, it's recommended to only store and maintain template files in your repository if you need to make custom changes. Other files (which you don't need to change), should not be duplicated, so that you don't need to worry about getting out-of-sync with the original Synapse templates.
-Due to this, it's recommended to only store and maintain template files in your repository if you need to make custom changes. Other files (which you don't need to change), should not be duplicated, so that you don't need to worry about getting out-of-sync with the original Synapse templates.
 
 
 ## Monitoring Synapse Metrics with Prometheus and Grafana

docs/configuring-playbook-telemetry.md

@@ -2,9 +2,7 @@
 
 By default, this playbook configures your Matrix homeserver to not send any telemetry data anywhere.
 
-The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting
+The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting usage statistics from your homeserver. Enabling usage statistics helps track the growth of the Matrix community, and helps to make Matrix a success.
-usage statistics from your homeserver. Enabling usage statistics helps track the
-growth of the Matrix community, and helps to make Matrix a success.
 
 
 ## Enabling Telemetry
@@ -20,9 +18,6 @@ matrix_dendrite_report_stats: true # for dendrite
 
 ## Usage statistics being submitted
 
-When enabled, your homeserver will regularly upload a few dozen statistics about your server.
+When enabled, your homeserver will regularly upload a few dozen statistics about your server. This data includes your homeserver's domain, the total number of users, the number of active users, the total number of rooms, and the number of messages sent per day on your homeserver.
-This data includes your homeserver's domain, the total number of users, the number of active
-users, the total number of rooms, and the number of messages sent per day on your homeserver.
 
-See [Synapse's documentation](https://github.com/element-hq/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics) or [Dendrite's documentation](https://github.com/matrix-org/dendrite/blob/main/docs/FAQ.md#what-is-being-reported-when-enabling-phone-home-statistics)
+See [Synapse's documentation](https://github.com/element-hq/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics) or [Dendrite's documentation](https://github.com/matrix-org/dendrite/blob/main/docs/FAQ.md#what-is-being-reported-when-enabling-phone-home-statistics) for the full list of statistics that are reported.
-for the full list of statistics that are reported.

docs/configuring-playbook-turn.md

@@ -65,8 +65,7 @@ matrix_synapse_turn_uris:
 - turn:HOSTNAME_OR_IP?transport=tcp
 ```
 
-If you have or want to enable [Jitsi](configuring-playbook-jitsi.md), you might want to enable the TURN server there too.
+If you have or want to enable [Jitsi](configuring-playbook-jitsi.md), you might want to enable the TURN server there too. If you do not do it, Jitsi will fall back to an upstream service.
-If you do not do it, Jitsi will fall back to an upstream service.
 
 ```yaml
 jitsi_web_stun_servers:

docs/configuring-playbook-user-verification-service.md

@@ -1,7 +1,6 @@
 # Setting up Matrix User Verification Service (optional)
 
-**[Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (hereafter: UVS) can only be installed after Matrix services are installed and running.**
+**[Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (hereafter: UVS) 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.
-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.
 
 Currently, the main purpose of this role is to allow Jitsi to authenticate Matrix users and check if they are authorized to join a conference. Please refer to the documentation of the [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) to understand how it works.
 
@@ -16,13 +15,9 @@ UVS can be used to verify two claims:
 * (A) Whether a given OpenID token is valid for a given server and
 * (B) whether a user is member of a given room and the corresponding PowerLevel
 
-Verifying an OpenID token ID done by finding the corresponding Homeserver via  '.well-known/matrix/server' for the given domain.
+Verifying an OpenID token ID done by finding the corresponding Homeserver via  '.well-known/matrix/server' for the given domain. The configured `matrix_user_verification_service_uvs_homeserver_url` does **not** factor into this. By default, this playbook only checks against `matrix_server_fqn_matrix`. Therefore, the request will be made against the public openid API for `matrix_server_fqn_matrix`.
-The configured `matrix_user_verification_service_uvs_homeserver_url` does **not** factor into this.
-By default, this playbook only checks against `matrix_server_fqn_matrix`.
-Therefore, the request will be made against the public openid API for `matrix_server_fqn_matrix`.
 
-Verifying RoomMembership and PowerLevel is done against `matrix_user_verification_service_uvs_homeserver_url` which is by default done via the docker network.
+Verifying RoomMembership and PowerLevel is done against `matrix_user_verification_service_uvs_homeserver_url` which is by default done via the docker network. UVS will verify the validity of the token beforehand though.
-UVS will verify the validity of the token beforehand though.
 
 ## Prerequisites
 
@@ -40,21 +35,17 @@ matrix_user_verification_service_enabled: true
 
 The only required configuration variable is `matrix_user_verification_service_uvs_access_token` (see below).
 
-For a list of all configuration options see the role defaults [`roles/matrix-user-verification-service/defaults/main.yml`](../roles/custom/matrix-user-verification-service/defaults/main.yml).
+For a list of all configuration options see the role defaults [`roles/matrix-user-verification-service/defaults/main.yml`](../roles/custom/matrix-user-verification-service/defaults/main.yml). But be aware of all the plugging happening in `group_vars/matrix_servers`.
-But be aware of all the plugging happening in `group_vars/matrix_servers`.
 
-In the default configuration, the UVS Server is only reachable via the docker network, which is fine if e.g. Jitsi is also running in a container on the host.
+In the default configuration, the UVS Server is only reachable via the docker network, which is fine if e.g. Jitsi is also running in a container on the host. However, it is possible to expose UVS via setting `matrix_user_verification_service_container_http_host_bind_port`.
-However, it is possible to expose UVS via setting `matrix_user_verification_service_container_http_host_bind_port`.
 
 ### Access token
 
 The Synapse Access Token is used to verify RoomMembership and PowerLevel against `matrix_user_verification_service_uvs_homeserver_url`.
 
-We recommend that you create a dedicated Matrix user for uvs (`uvs` is a good username).
+We recommend that you create a dedicated Matrix user for uvs (`uvs` is a good username). Follow our [Registering users](registering-users.md) guide to register a user with administration privileges.
-Follow our [Registering users](registering-users.md) guide to register a user with administration privileges.
 
-You are required to specify an access token (belonging to this new user) for UVS to work.
+You are required to specify an access token (belonging to this new user) for UVS to work. To get an access token for the UVS user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
-To get an access token for the UVS user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
 
 **Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
 
@@ -67,6 +58,7 @@ matrix_user_verification_service_uvs_access_token: "YOUR ACCESS TOKEN HERE"
 It is possible to set an API Auth Token to restrict access to the UVS. If this is enabled, anyone making a request to UVS must provide it via the header "Authorization: Bearer TOKEN"
 
 By default, the token will be derived from `matrix_homeserver_generic_secret_key` in `group_vars/matrix_servers`.
+
 To set your own Token, simply put the following in your host_vars.
 
 ```yaml
@@ -94,8 +86,7 @@ matrix_user_verification_service_uvs_pin_openid_verify_server_name: false
 
 in your host_vars.
 
-This will instruct UVS to verify the OpenID token against any domain given in a request.
+This will instruct UVS to verify the OpenID token against any domain given in a request. Homeserver discovery is done via '.well-known/matrix/server' of the given domain.
-Homeserver discovery is done via '.well-known/matrix/server' of the given domain.
 
 ## Installing
 

docs/configuring-well-known.md

@@ -17,8 +17,7 @@ As [per the Server-Server specification](https://matrix.org/docs/spec/server_ser
 
 Server delegation can be configured using DNS SRV records or by setting up a `/.well-known/matrix/server` file on the base domain (`example.com`).
 
-Both methods have their place and will continue to do so. You only need to use just one of these delegation methods.
+Both methods have their place and will continue to do so. You only need to use just one of these delegation methods. For simplicity reasons, our setup advocates for the `/.well-known/matrix/server` method and guides you into using that.
-For simplicity reasons, our setup advocates for the `/.well-known/matrix/server` method and guides you into using that.
 
 To learn how to set up `/.well-known/matrix/server`, read the Installing section below.
 
@@ -43,6 +42,7 @@ To learn how to set it up, read the Installing section below.
 The two playbook variables that you could look for, if you're interested in being an early adopter, are: `matrix_static_files_file_matrix_support_property_m_contacts` and `matrix_static_files_file_matrix_support_property_m_support_page`.
 
 Example snippet for `vars.yml`:
+
 ```
 # Enable generation of `/.well-known/matrix/support`.
 matrix_static_files_file_matrix_support_enabled: true
@@ -69,9 +69,7 @@ To learn how to set up `/.well-known/matrix/support` for the base domain, read t
 
 To implement the two service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to run an HTTPS-capable webserver.
 
-If you don't have a server for your base domain at all, you can use the Matrix server for this.
+If you don't have a server for your base domain at all, you can use the Matrix server for this. See [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up. If you decide to go this route, you don't need to read ahead in this document. When **Serving the base domain**, the playbook takes care to serve the appropriate well-known files automatically.
-See [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up.
-If you decide to go this route, you don't need to read ahead in this document. When **Serving the base domain**, the playbook takes care to serve the appropriate well-known files automatically.
 
 If you're managing the base domain by yourself somehow, you'll need to set up serving of some `/.well-known/matrix/*` files from it via HTTPS.
 
@@ -90,8 +88,7 @@ All you need to do is:
 
 - set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Element) may fail to work. Setting up headers for the `/.well-known/matrix/server` file is not necessary, as this file is only consumed by non-browsers, which don't care about CORS.
 
-This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server.
+This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server. It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known files and you may need to notice that and copy them over again.
-It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known files and you may need to notice that and copy them over again.
 
 
 ### (Option 2): **Serving the base domain** from the Matrix server via the playbook

docs/faq.md

@@ -346,11 +346,9 @@ Refer to both of these for inspiration. Still, as mentioned in [Configuring the
 
 ### I'd like to adjust some configuration which doesn't have a corresponding variable. How do I do it?
 
-The playbook doesn't aim to expose all configuration settings for all services using variables.
+The playbook doesn't aim to expose all configuration settings for all services using variables. Doing so would amount to hundreds of variables that we have to create and maintain.
-Doing so would amount to hundreds of variables that we have to create and maintain.
 
-Instead, we only try to make some important basics configurable using dedicated variables you can see in each role.
+Instead, we only try to make some important basics configurable using dedicated variables you can see in each role. See [What configuration variables are available?](#what-configuration-variables-are-available).
-See [What configuration variables are available?](#what-configuration-variables-are-available).
 
 Besides that, each role (component) aims to provide a `matrix_SOME_COMPONENT_configuration_extension_yaml` (or `matrix_SOME_COMPONENT_configuration_extension_json`) variable, which can be used to override the configuration.
 

docs/getting-the-playbook.md

@@ -21,19 +21,16 @@ Once you've installed git on your computer, you can go to any directory of your
 git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
 ```
 
-This will create a new `matrix-docker-ansible-deploy` directory.
+This will create a new `matrix-docker-ansible-deploy` directory. You're supposed to execute all other installation commands inside that directory.
-You're supposed to execute all other installation commands inside that directory.
 
 
 ## Downloading the playbook as a ZIP archive
 
-Alternatively, you can download the playbook as a ZIP archive.
+Alternatively, you can download the playbook as a ZIP archive. This is not recommended, as it's not easy to keep up to date with future updates. We suggest you [use git](#using-git-to-get-the-playbook) instead.
-This is not recommended, as it's not easy to keep up to date with future updates. We suggest you [use git](#using-git-to-get-the-playbook) instead.
 
 The latest version is always at the following URL: https://github.com/spantaleev/matrix-docker-ansible-deploy/archive/master.zip
 
-You can extract this archive anywhere. You'll get a directory called `matrix-docker-ansible-deploy-master`.
+You can extract this archive anywhere. You'll get a directory called `matrix-docker-ansible-deploy-master`. You're supposed to execute all other installation commands inside that directory.
-You're supposed to execute all other installation commands inside that directory.
 
 
 ---------------------------------------------

docs/howto-server-delegation.md

@@ -2,8 +2,7 @@
 
 To have a server on a subdomain (e.g. `matrix.example.com`) handle Matrix federation traffic for the base domain (`example.com`), we need to instruct the Matrix network of such a delegation.
 
-By default, this playbook guides you into setting up [Server Delegation via a well-known file](#server-delegation-via-a-well-known-file).
+By default, this playbook guides you into setting up [Server Delegation via a well-known file](#server-delegation-via-a-well-known-file). However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation.
-However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation.
 
 It is a complicated matter, so unless you are affected by the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation), we suggest you stay on the simple/default path.
 
@@ -12,8 +11,7 @@ It is a complicated matter, so unless you are affected by the [Downsides of well
 
 Serving a `/.well-known/matrix/server` file from the base domain is the most straightforward way to set up server delegation, but it suffers from some problems that we list in [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation).
 
-As we already mention in [Configuring DNS](configuring-dns.md) and [Configuring Service Discovery via .well-known](configuring-well-known.md),
+As we already mention in [Configuring DNS](configuring-dns.md) and [Configuring Service Discovery via .well-known](configuring-well-known.md), this playbook already properly guides you into setting up such delegation by means of a `/.well-known/matrix/server` file served from the base domain (`example.com`).
-this playbook already properly guides you into setting up such delegation by means of a `/.well-known/matrix/server` file served from the base domain (`example.com`).
 
 If this is okay with you, feel free to not read ahead.
 
@@ -57,8 +55,7 @@ How you can obtain a valid certificate for `example.com` on the `matrix.example.
 
 If `example.com` and `matrix.example.com` are hosted on the same machine, you can let the playbook obtain the certificate for you, by following our [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) guide.
 
-If `example.com` and `matrix.example.com` are not hosted on the same machine, you can copy over the certificate files manually.
+If `example.com` and `matrix.example.com` are not hosted on the same machine, you can copy over the certificate files manually. Don't forget that they may get renewed once in a while, so you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire.
-Don't forget that they may get renewed once in a while, so you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire.
 
 
 ### Serving the Federation API with your certificates
@@ -81,8 +78,7 @@ Based on your setup, you have different ways to go about it:
 
 ### Serving the Federation API with your certificates and another webserver
 
-**If you are using some other webserver**, you can set up reverse-proxying for the `tcp/8448` port by yourself.
+**If you are using some other webserver**, you can set up reverse-proxying for the `tcp/8448` port by yourself. Make sure to use the proper certificates for `example.com` (not for `matrix.example.com`) when serving the `tcp/8448` port.
-Make sure to use the proper certificates for `example.com` (not for `matrix.example.com`) when serving the `tcp/8448` port.
 
 As recommended in our [Fronting the integrated reverse-proxy webserver with another reverse-proxy](./configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) documentation section, we recommend you to expose the Matrix Federation entrypoint from traffic at a local port (e.g. `127.0.0.1:8449`), so your reverese-proxy should send traffic there.
 
@@ -105,5 +101,4 @@ matrix_synapse_tls_certificate_path: /some/path/inside/the/container/certificate
 matrix_synapse_tls_private_key_path: /some/path/inside/the/container/private.key
 ```
 
-Make sure to reload Synapse once in a while (`systemctl reload matrix-synapse`), so that newer certificates can kick in.
+Make sure to reload Synapse once in a while (`systemctl reload matrix-synapse`), so that newer certificates can kick in. Reloading doesn't cause any downtime.
-Reloading doesn't cause any downtime.

docs/importing-postgres.md

@@ -6,14 +6,11 @@ Run this if you'd like to import your database from a previous installation.
 
 ## Prerequisites
 
-For this to work, **the database name in Postgres must match** what this playbook uses.
+For this to work, **the database name in Postgres must match** what this playbook uses. This playbook uses a Postgres database name of `synapse` by default (controlled by the `matrix_synapse_database_database` variable). If your database name differs, be sure to change `matrix_synapse_database_database` to your desired name and to re-run the playbook before proceeding.
-This playbook uses a Postgres database name of `synapse` by default (controlled by the `matrix_synapse_database_database` variable).
-If your database name differs, be sure to change `matrix_synapse_database_database` to your desired name and to re-run the playbook before proceeding.
 
-The playbook supports importing Postgres dump files in **text** (e.g. `pg_dump > dump.sql`) or **gzipped** formats (e.g. `pg_dump | gzip -c > dump.sql.gz`).
+The playbook supports importing Postgres dump files in **text** (e.g. `pg_dump > dump.sql`) or **gzipped** formats (e.g. `pg_dump | gzip -c > dump.sql.gz`). Importing multiple databases (as dumped by `pg_dumpall`) is also supported.
 
-Importing multiple databases (as dumped by `pg_dumpall`) is also supported.
+The migration might be a good moment, to "reset" a not properly working bridge. Be aware, that it might affect all users (new link to bridge, new rooms, ...)
-But the migration might be a good moment, to "reset" a not properly working bridge. Be aware, that it might affect all users (new link to bridge, new rooms, ...)
 
 Before doing the actual import, **you need to upload your Postgres dump file to the server** (any path is okay).
 
@@ -94,6 +91,7 @@ If not, you probably get this error. `synapse` is the correct table owner, but t
 ```
 
 Once the database is clear and the ownership of the tables has been fixed in the SQL file, the import task should succeed.
+
 Check, if `--dbname` is set to `synapse` (not `matrix`) and replace paths (or even better, copy this line from your terminal)
 
 ```

docs/importing-synapse-media-store.md

@@ -8,6 +8,7 @@ Run this if you'd like to import your `media_store` files from a previous instal
 Before doing the actual data restore, **you need to upload your media store directory to the server** (any path is okay).
 
 If you are [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional), restoring with this tool is not possible right now.
+
 As an alternative, you can perform a manual restore using the [AWS CLI tool](https://aws.amazon.com/cli/) (e.g. `aws s3 sync /path/to/server/media_store/. s3://name-of-bucket/`)
 
 **Note for Mac users**: Due to case-sensitivity issues on certain Mac filesystems (HFS or HFS+), filename corruption may occur if you copy a `media_store` directory to your Mac. If you're transferring a `media_store` directory between 2 servers, make sure you do it directly (from server to server with a tool such as [rsync](https://rsync.samba.org/)), and not by downloading the files to your Mac.

docs/importing-synapse-sqlite.md

@@ -1,7 +1,6 @@
 # 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.
+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-synapse-media-store guide](importing-synapse-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 only supports running Synapse in combination with PostgreSQL, a Synapse instance installed manually usually defaults to using an SQLite database.
 

docs/installing.md

@@ -56,8 +56,7 @@ Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-t
 
 ### Installing a server into which you'll import old data
 
-If you will be importing data into your newly created Matrix server, install it, but **do not** start its services just yet.
+If you will be importing data into your newly created Matrix server, install it, but **do not** start its services just yet. Starting its services or messing with its database now will affect your data import later on.
-Starting its services or messing with its database now will affect your data import later on.
 
 To do the installation **without** starting services, run only the `install-all` tag:
 

docs/maintenance-postgres.md

@@ -28,8 +28,7 @@ To change to another database (for example `synapse`), run `\connect synapse` (o
 
 You can then proceed to write queries. Example: `SELECT COUNT(*) FROM users;`
 
-**Be careful**. Modifying the database directly (especially as services are running) is dangerous and may lead to irreversible database corruption.
+**Be careful**. Modifying the database directly (especially as services are running) is dangerous and may lead to irreversible database corruption. When in doubt, consider [making a backup](#backing-up-postgresql).
-When in doubt, consider [making a backup](#backing-up-postgresql).
 
 
 ## Vacuuming PostgreSQL
@@ -76,8 +75,7 @@ Restoring a backup made this way can be done by [importing it](importing-postgre
 
 Unless you are using an [external Postgres server](configuring-playbook-external-postgres.md), this playbook initially installs Postgres for you.
 
-Once installed, the playbook attempts to preserve the Postgres version it starts with.
+Once installed, the playbook attempts to preserve the Postgres version it starts with. This is because newer Postgres versions cannot start with data generated by older Postgres versions.
-This is because newer Postgres versions cannot start with data generated by older Postgres versions.
 
 Upgrades must be performed manually.
 
@@ -87,17 +85,14 @@ This playbook can upgrade your existing Postgres setup with the following comman
 just run-tags upgrade-postgres
 ```
 
-**The old Postgres data directory is backed up** automatically, by renaming it to `/matrix/postgres/data-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"`
-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**.
 
-As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty Postgres server is started, and then the dump is restored into the new server.
+As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty Postgres server is started, and then the dump is restored into the new server. To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`
-To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`
 
 To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage.
-If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`.
+If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`. Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
-Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
 
 **All databases, roles, etc. on the Postgres server are migrated**.
 
@@ -106,8 +101,7 @@ Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
 
 PostgreSQL can be [tuned](https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server) to make it run faster. This is done by passing extra arguments to the Postgres process.
 
-The [Postgres Ansible role](https://github.com/mother-of-all-self-hosting/ansible-role-postgres) **already does some tuning by default**, which matches the [tuning logic](https://github.com/le0pard/pgtune/blob/master/src/features/configuration/configurationSlice.js) done by websites like https://pgtune.leopard.in.ua/.
+The [Postgres Ansible role](https://github.com/mother-of-all-self-hosting/ansible-role-postgres) **already does some tuning by default**, which matches the [tuning logic](https://github.com/le0pard/pgtune/blob/master/src/features/configuration/configurationSlice.js) done by websites like https://pgtune.leopard.in.ua/. You can manually influence some of the tuning variables. These parameters (variables) are injected via the `postgres_postgres_process_extra_arguments_auto` variable.
-You can manually influence some of the tuning variables . These parameters (variables) are injected via the `postgres_postgres_process_extra_arguments_auto` variable.
 
 Most users should be fine with the automatically-done tuning. However, you may wish to:
 

docs/maintenance-synapse.md

@@ -39,8 +39,7 @@ To ask the playbook to run rust-synapse-compress-state, execute:
 ansible-playbook -i inventory/hosts setup.yml --tags=rust-synapse-compress-state
 ```
 
-By default, all rooms with more than `100000` state group rows will be compressed.
+By default, all rooms with more than `100000` state group rows will be compressed. If you need to adjust this, pass: `--extra-vars='matrix_synapse_rust_synapse_compress_state_min_state_groups_required=SOME_NUMBER_HERE'` to the command above.
-If you need to adjust this, pass: `--extra-vars='matrix_synapse_rust_synapse_compress_state_min_state_groups_required=SOME_NUMBER_HERE'` to the command above.
 
 After state compression, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
 

docs/registering-users.md

@@ -70,8 +70,7 @@ If you're using the [Matrix Authentication Service](./configuring-playbook-matri
 # Example: `/matrix/matrix-authentication-service/bin/register-user john secret-password 1`
 ```
 
-This `register-user` script actually invokes the `mas-cli manage register-user` command under the hood.
+This `register-user` script actually invokes the `mas-cli manage register-user` command under the hood. If you'd like more control over the registration process, consider invoking the `mas-cli` command directly:
-If you'd like more control over the registration process, consider invoking the `mas-cli` command directly:
 
 ```sh
 /matrix/matrix-authentication-service/bin/mas-cli manage register-user --help