mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2024-11-06 02:37:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Edit line breaks in sentences and paragraphs

Browse Source 
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara 2024-10-19 02:32:11 +09:00
parent 2f24299597
commit 6995f3990e
No known key found for this signature in database
GPG Key ID: E4F9743DAB4B7B75
50 changed files with 135 additions and 243 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/ansible.md
View File

@ -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.
If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
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).
## 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.
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`).
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`).
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.
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.
**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.
## 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.
Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
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:
- 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.
The `/work` directory contains the playbook's code.
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.
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`).
If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part.
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.
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.
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.
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

1
docs/configuring-captcha.md
View File

@ -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

16
docs/configuring-dns.md
View File

@ -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 install anything on the actual `example.com` server.
To use an identifier like `@<username>:example.com`, you don't actually need 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.
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.
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.
## 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.
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 `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.
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
SPF (TXT), DMARC (TXT), DKIM (TXT) and MX records
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

3
docs/configuring-playbook-appservice-draupnir-for-all.md
View File

@ -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
and invites to the management room.
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.
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.

8
docs/configuring-playbook-backup-borg.md
View File

@ -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
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.
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.

10
docs/configuring-playbook-base-domain-serving.md
View File

@ -1,8 +1,6 @@
# Serving the base domain
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.
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.
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`.
The content of this page is taken from the `matrix_static_files_file_index_html_template` variable.
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.
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 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 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.
## Serving a more complicated website at the base domain

12
docs/configuring-playbook-bot-draupnir.md
View File

@ -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).
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).
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).
### 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.
If you are using traefik, this playbook can set this up for you:
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:
```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).
To enable it, set `pollReports: true` in Draupnir's config:
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:
```yaml
matrix_bot_draupnir_configuration_extension_yaml: |
pollReports: true

10
docs/configuring-playbook-bot-matrix-registration-bot.md
View File

@ -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.
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.
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.
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.
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.
## 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:

9
docs/configuring-playbook-bot-maubot.md
View File

@ -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.
The default location of the management interface is `matrix.example.com/_matrix/maubot/`
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/`
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.
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.
## 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
and the plugin (how the bot will behave)
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)
## Obtaining an access token

3
docs/configuring-playbook-bot-postmoogle.md
View File

@ -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 runs an SMTP email server and allows you to assign mailbox addresses 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.
See the project's [documentation](https://github.com/etkecc/postmoogle) to learn what it does and why it might be useful to you.

3
docs/configuring-playbook-bridge-appservice-webhooks.md
View File

@ -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`
you can adjust this in `inventory/host_vars/matrix.example.com/vars.yml` as well.
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.
**Note**: default value is: `info` and availabe log levels are : `info`, `verbose`

7
docs/configuring-playbook-bridge-go-skype-bridge.md
View File

@ -1,7 +1,6 @@
# Setting up Go Skype Bridge (optional)
The playbook can install and configure
[go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.
The playbook can install and configure [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`
with the handle `@skypebridgebot:example.com` (where `example.com` is your base
domain, not the `matrix.` domain).
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).
Send `help` to the bot to see the commands available.

1
docs/configuring-playbook-bridge-mautrix-meta-messenger.md
View File

@ -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`

3
docs/configuring-playbook-bridge-mautrix-telegram.md
View File

@ -65,8 +65,7 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
'@user:example.com': admin
```
More details about permissions in this example:
https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
More details about permissions in this example: 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

5
docs/configuring-playbook-bridge-mautrix-whatsapp.md
View File

@ -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`.
Use `!wa unset-relay` to deactivate.
If you want to activate the relay bot in a room, send `!wa set-relay`. To deactivate, send `!wa unset-relay`.
## Installing

15
docs/configuring-playbook-dimension.md
View File

@ -1,7 +1,6 @@
# Setting up Dimension (optional)
**[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.
**[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.** If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later.
**Note**: 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.
Add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
These users can modify the integrations this Dimension supports. 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).
Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
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**.
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).
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).
**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 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 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.
You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).

8
docs/configuring-playbook-dynamic-dns.md
View File

@ -2,10 +2,10 @@
## Setup
Most cloud providers / ISPs will charge you extra for a static IP address. If you're
not hosting a highly reliable homeserver you can workaround this via dynamic DNS. To
set this up, you'll need to get the username/password from your DNS provider. For
google domains, this process is described [here](https://support.google.com/domains/answer/6147083).
Most cloud providers / ISPs will charge you extra for a static IP address. If you're not hosting a highly reliable homeserver you can workaround this via dynamic DNS.
To set this up, you'll need to get the username/password from your DNS provider. For google domains, this process is described [here](https://support.google.com/domains/answer/6147083).
After you've gotten the proper credentials you can add the following config to your `inventory/host_vars/matrix.example.com/vars.yml`:
```yaml

3
docs/configuring-playbook-email.md
View File

@ -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.
This may or may not work, depending on your domain configuration (SPF settings, etc.)
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.)
By default, emails are sent from `matrix@matrix.example.com`, as specified by the `exim_relay_sender_address` playbook variable.

3
docs/configuring-playbook-federation.md
View File

@ -1,7 +1,6 @@
# Controlling Matrix federation (optional)
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.
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.
## Federating only with select servers

43
docs/configuring-playbook-jitsi.md
View File

@ -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.
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.
**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.
### 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.
If a registered host is not yet present, guests are put on hold in individual waiting rooms.
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.
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).
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).
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).
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.
Read more on this feature [here](https://jitsi.org/blog/new-off-stage-layer-suppression-feature/)
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/)
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.
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 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).
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:
`ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
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`
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.
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:
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:
``` 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
`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:
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:
```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
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:
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:
```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
to route conferences too.
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 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.
Since element already sends the url of configured Matrix avatars to Jitsi, we disabled 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.
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).
Besides metadata, this includes the Matrix user_id and possibly the room identifier (via `referrer` header).
**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).
## Installing

10
docs/configuring-playbook-ma1sd.md
View File

@ -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
(in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.
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.
## 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.
You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
Still, ma1sd can do much more. 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
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.
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.
## Example: SMS verification

7
docs/configuring-playbook-matrix-corporal.md
View File

@ -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.
See that project's documentation to learn what it does and why it might be useful to 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. 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.
By default, it's `matrix-corporal` (controllable by the `matrix_corporal_reconciliation_user_id_local_part` setting, see above).
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).
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

6
docs/configuring-playbook-matrix-ldap-registration-proxy.md
View File

@ -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
implementation of a basic password registration.
**Note**: This does support the full Matrix specification for registrations. It only provide a very coarse 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)
you can use the following values as 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:
```yaml
# Use the LDAP values specified for the synapse role to setup LDAP proxy

3
docs/configuring-playbook-matrix-registration.md
View File

@ -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.
Adjust the `one_time` and `ex_date` variables as you see fit.
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.
Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.

4
docs/configuring-playbook-mautrix-bridges.md
View File

@ -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.
This is a common guide for configuring 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.
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.

3
docs/configuring-playbook-own-webserver.md
View File

@ -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.
If you don't pass the `Host` header correctly, you would get a 404 not found error from Traefik.
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.
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.

3
docs/configuring-playbook-prometheus-grafana.md
View File

@ -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`.
It will look a bit like this:
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:
```yaml
scrape_configs:
- job_name: 'synapse'

8
docs/configuring-playbook-prometheus-nginxlog.md
View File

@ -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
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:
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:
```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.
Please make sure you change the default Grafana password.
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.
## Save metrics on an external Prometheus server

3
docs/configuring-playbook-s3-goofys.md
View File

@ -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),
you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
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.
Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md).

3
docs/configuring-playbook-sliding-sync-proxy.md
View File

@ -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.
Simply open your client which supports Sliding Sync (like Element X) and log in.
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.
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`).

3
docs/configuring-playbook-sygnal.md
View File

@ -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 do that, the above example configuration:
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:
- 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`.

3
docs/configuring-playbook-synapse-auto-accept-invite.md
View File

@ -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.
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.
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.
**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.

4
docs/configuring-playbook-synapse-auto-compressor.md
View File

@ -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
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.
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.

3
docs/configuring-playbook-synapse-s3-storage-provider.md
View File

@ -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),
you can use the [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) media provider module for Synapse.
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.
An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).

3
docs/configuring-playbook-synapse-simple-antispam.md
View File

@ -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.
In short, it lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).
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).
## Adjusting the playbook configuration

3
docs/configuring-playbook-synapse.md
View File

@ -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.
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.
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.
## Monitoring Synapse Metrics with Prometheus and Grafana

11
docs/configuring-playbook-telemetry.md
View File

@ -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
usage statistics from your homeserver. Enabling usage statistics helps track the
growth of the Matrix community, and helps to make Matrix a success.
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.
## 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.
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.
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.
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.
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.

3
docs/configuring-playbook-turn.md
View File

@ -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 do not do it, Jitsi will fall back to an upstream service.
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.
```yaml
jitsi_web_stun_servers:

27
docs/configuring-playbook-user-verification-service.md
View File

@ -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.**
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.
**[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.
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.
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 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`.
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.
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.
## 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).
But be aware of all the plugging happening in `group_vars/matrix_servers`.
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`.
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`.
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`.
### 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).
Follow our [Registering users](registering-users.md) guide to register a user with administration privileges.
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.
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).
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).
**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.
Homeserver discovery is done via '.well-known/matrix/server' of the given domain.
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.
## Installing

11
docs/configuring-well-known.md
View File

@ -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.
For simplicity reasons, our setup advocates for the `/.well-known/matrix/server` method and guides you into using that.
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.
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.
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 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.
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.
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.
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.
### (Option 2): **Serving the base domain** from the Matrix server via the playbook

6
docs/faq.md
View File

@ -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.
Doing so would amount to hundreds of variables that we have to create and maintain.
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.
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).
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).
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.

9
docs/getting-the-playbook.md
View File

@ -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.
You're supposed to execute all other installation commands inside that directory.
This will create a new `matrix-docker-ansible-deploy` 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.
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.
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.
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're supposed to execute all other installation commands inside that directory.
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.
---------------------------------------------

15
docs/howto-server-delegation.md
View File

@ -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).
However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation.
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.
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),
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`).
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`).
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.
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.
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.
### 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.
Make sure to use the proper certificates for `example.com` (not for `matrix.example.com`) when serving the `tcp/8448` port.
**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.
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.
Reloading doesn't cause any downtime.
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.

10
docs/importing-postgres.md
View File

@ -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.
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.
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.
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.
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, ...)
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)
```

1
docs/importing-synapse-media-store.md
View File

@ -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.

3
docs/importing-synapse-sqlite.md
View File

@ -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.
(don't forget to import your `media_store` files as well - see [the importing-synapse-media-store guide](importing-synapse-media-store.md)).
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)).
While this playbook only supports running Synapse in combination with PostgreSQL, a Synapse instance installed manually usually defaults to using an SQLite database.

3
docs/installing.md
View File

@ -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.
Starting its services or messing with its database now will affect your data import later on.
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.
To do the installation **without** starting services, run only the `install-all` tag:

18
docs/maintenance-postgres.md
View File

@ -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.
When in doubt, consider [making a backup](#backing-up-postgresql).
**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).
## 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.
This is because newer Postgres versions cannot start with data generated by older Postgres versions.
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.
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`.
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 old Postgres data directory is backed up** automatically, by renaming it to `/matrix/postgres/data-auto-upgrade-backup`. To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="postgres_auto_upgrade_backup_data_path=/another/disk/matrix-postgres-before-upgrade"`
The auto-upgrade-backup directory stays around forever, until you **manually decide to delete it**.
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"`
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 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`.
Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
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"`
**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/.
You can manually influence some of the tuning variables . These parameters (variables) are injected via the `postgres_postgres_process_extra_arguments_auto` variable.
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.
Most users should be fine with the automatically-done tuning. However, you may wish to:

3
docs/maintenance-synapse.md
View File

@ -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.
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.
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.
After state compression, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).

3
docs/registering-users.md
View File

@ -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.
If you'd like more control over the registration process, consider invoking the `mas-cli` command directly:
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:
```sh
/matrix/matrix-authentication-service/bin/mas-cli manage register-user --help