fossilfranv/matrix-docker-ansible-deploy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into wsproxy-merge

Browse Source
This commit is contained in:
Johan Swetzén 2022-11-11 10:43:59 +01:00
commit 588e607784
799 changed files with 9430 additions and 3943 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.config/ansible-lint.yml
View File

@ -9,5 +9,8 @@ skip_list:
- schema
- command-instead-of-shell
- role-name
# We frequently load configuration from a template (into a variable), then merge that with another variable (configuration extension)
# before finally dumping it to a file.
- template-instead-of-copy
offline: false

2
.github/workflows/matrix.yml vendored
View File

@ -13,7 +13,7 @@ jobs:
- name: Check out
uses: actions/checkout@v3
- name: Run yamllint
uses: frenck/action-yamllint@v1.2.0
uses: frenck/action-yamllint@v1.3.1
ansible-lint:
name: ansible-lint
runs-on: ubuntu-latest

6
.gitignore vendored
View File

@ -2,6 +2,10 @@
!/inventory/.gitkeep
!/inventory/host_vars/.gitkeep
!/inventory/scripts
/roles/*/files/scratchpad
/roles/**/files/scratchpad
.DS_Store
.python-version
# ignore roles pulled by ansible-galaxy
/roles/galaxy/*
!/roles/galaxy/.gitkeep

3
.yamllint
View File

@ -1,8 +1,5 @@
---
extends: default
ignore: |
roles/matrix-synapse/vars/workers.yml
rules:
line-length: disable

256
CHANGELOG.md
View File

@ -1,3 +1,247 @@
# 2022-11-05
## (Backward Compatibility Break) A new default standalone mode for Etherpad
Until now, [Etherpad](https://etherpad.org/) (which [the playbook could install for you](docs/configuring-playbook-etherpad.md)) required the [Dimension integration manager](docs/configuring-playbook-dimension.md) to also be installed, because Etherpad was hosted on the Dimension domain (at `dimension.DOMAIN/etherpad`).
From now on, Etherpad can be installed in `standalone` mode on `etherpad.DOMAIN` and used even without Dimension. This is much more versatile, so the playbook now defaults to this new mode (`matrix_etherpad_mode: standalone`).
If you've already got both Etherpad and Dimension in use you could:
- **either** keep hosting Etherpad under the Dimension domain by adding `matrix_etherpad_mode: dimension` to your `vars.yml` file. All your existing room widgets will continue working at the same URLs and no other changes will be necessary.
- **or**, you could change to hosting Etherpad separately on `etherpad.DOMAIN`. You will need to [configure a DNS record](docs/configuring-dns.md) for this new domain. You will also need to reconfigure Dimension to use the new pad URLs (`https://etherpad.DOMAIN/...`) going forward (refer to our [configuring Etherpad documentation](docs/configuring-playbook-etherpad.md)). All your existing room widgets (which still use `https://dimension.DOMAIN/etherpad/...`) will break as Etherpad is not hosted there anymore. You will need to re-add them or to consider not using `standalone` mode
# 2022-11-04
## The playbook now uses external roles for some things
**TLDR**: when updating the playbook and before running it, you'll need to run `make roles` to make [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) download dependency roles (see the [`requirements.yml` file](requirements.yml)) to the `roles/galaxy` directory. Without this, the playbook won't work.
We're in the process of trimming the playbook and making it reuse Ansible roles.
Starting now, the playbook is composed of 2 types of Ansible roles:
- those that live within the playbook itself (`roles/custom/*`)
- those downloaded from other sources (using [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to `roles/galaxy`, based on the [`requirements.yml` file](requirements.yml)). These roles are maintained by us or by other people from the Ansible community.
We're doing this for greater code-reuse (across Ansible playbooks, including our own related playbooks [gitea-docker-ansible-deploy](https://github.com/spantaleev/gitea-docker-ansible-deploy) and [nextcloud-docker-ansible-deploy](https://github.com/spantaleev/nextcloud-docker-ansible-deploy)) and decreased maintenance burden. Until now, certain features were copy-pasted across playbooks or were maintained separately in each one, with improvements often falling behind. We've also tended to do too much by ourselves - installing Docker on the server from our `matrix-base` role, etc. - something that we'd rather not do anymore by switching to the [geerlingguy.docker](https://galaxy.ansible.com/geerlingguy/docker) role.
Some variable names will change during the transition to having more and more external (galaxy) roles. There's a new `custom/matrix_playbook_migration` role added to the playbook which will tell you about these changes each time you run the playbook.
**From now on**, every time you update the playbook (well, every time the `requirements.yml` file changes), it's best to run `make roles` to update the roles downloaded from other sources. `make roles` is a shortcut (a `roles` target defined in [`Makefile`](Makefile) and executed by the [`make`](https://www.gnu.org/software/make/) utility) which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles. If you don't have `make`, you can also manually run the commands seen in the `Makefile`.
# 2022-10-14
## synapse-s3-storage-provider support
**`synapse-s3-storage-provider` support is very new and still relatively untested. Using it may cause data loss.**
You can now store your Synapse media repository files on Amazon S3 (or another S3-compatible object store) using [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) - a media provider for Synapse (Python module), which should work faster and more reliably than our previous [Goofys](docs/configuring-playbook-s3-goofys.md) implementation (Goofys will continue to work).
This is not just for initial installations. Users with existing files (stored in the local filesystem) can also migrate their files to `synapse-s3-storage-provider`.
To get started, see our [Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider](docs/configuring-playbook-synapse-s3-storage-provider.md) documentation.
## Synapse container image customization support
We now support customizing the Synapse container image by adding additional build steps to its [`Dockerfile`](https://docs.docker.com/engine/reference/builder/).
Our [synapse-s3-storage-provider support](#synapse-s3-storage-provider-support) is actually built on this. When `s3-storage-provider` is enabled, we automatically add additional build steps to install its Python module into the Synapse image.
Besides this kind of auto-added build steps (for components supported by the playbook), we also let you inject your own custom build steps using configuration like this:
```yaml
matrix_synapse_container_image_customizations_enabled: true
matrix_synapse_container_image_customizations_dockerfile_body_custom: |
RUN echo 'This is a custom step for building the customized Docker image for Synapse.'
RUN echo 'You can override matrix_synapse_container_image_customizations_dockerfile_body_custom to add your own steps.'
RUN echo 'You do NOT need to include a FROM clause yourself.'
```
People who have needed to customize Synapse previously had to fork the git repository, make their changes to the `Dockerfile` there, point the playbook to the new repository (`matrix_synapse_container_image_self_build_repo`) and enable self-building from scratch (`matrix_synapse_container_image_self_build: true`). This is harder and slower.
With the new Synapse-customization feature in the playbook, we use the original upstream (pre-built, if available) Synapse image and only build on top of it, right on the Matrix server. This is much faster than building all of Synapse from scratch.
# 2022-10-02
## matrix-ldap-registration-proxy support
Thanks to [@TheOneWithTheBraid](https://github.com/TheOneWithTheBraid), we now support installing [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) - a proxy which handles Matrix registration requests and forwards them to LDAP.
See our [Setting up the ldap-registration-proxy](docs/configuring-playbook-matrix-ldap-registration-proxy.md) documentation to get started.
# 2022-09-15
## (Potential Backward Compatibility Break) Major improvements to Synapse workers
People who are interested in running a Synapse worker setup should know that **our Synapse worker implementation is much more powerful now**:
- we've added support for [Stream writers](#stream-writers-support)
- we've added support for [multiple federation sender workers](#multiple-federation-sender-workers-support)
- we've added support for [multiple pusher workers](#multiple-pusher-workers-support)
- we've added support for [running background tasks on a worker](#background-tasks-can-run-on-a-worker)
- we've restored support for [`appservice` workers](#appservice-worker-support-is-back)
- we've restored support for [`user_dir` workers](#user-directory-worker-support-is-back)
- we've made it possible to [reliably use more than 1 `media_repository` worker](#using-more-than-1-media-repository-worker-is-now-more-reliable)
- see the [Potential Backward Incompatibilities after these Synapse worker changes](#potential-backward-incompatibilities-after-these-synapse-worker-changes)
### Stream writers support
From now on, the playbook lets you easily set up various [stream writer workers](https://matrix-org.github.io/synapse/latest/workers.html#stream-writers) which can handle different streams (`events` stream; `typing` URL endpoints, `to_device` URL endpoints, `account_data` URL endpoints, `receipts` URL endpoints, `presence` URL endpoints). All of this work was previously handled by the main Synapse process, but can now be offloaded to stream writer worker processes.
If you're using `matrix_synapse_workers_preset: one-of-each`, you'll automatically get 6 additional workers (one for each of the above stream types). Our `little-federation-helper` preset (meant to be quite minimal and focusing in improved federation performance) does not include stream writer workers.
If you'd like to customize the number of workers we also make that possible using these variables:
```yaml
# Synapse only supports more than 1 worker for the `events` stream.
# All other streams can utilize either 0 or 1 workers, not more than that.
matrix_synapse_workers_stream_writer_events_stream_workers_count: 5
matrix_synapse_workers_stream_writer_typing_stream_workers_count: 1
matrix_synapse_workers_stream_writer_to_device_stream_workers_count: 1
matrix_synapse_workers_stream_writer_account_data_stream_workers_count: 1
matrix_synapse_workers_stream_writer_receipts_stream_workers_count: 1
matrix_synapse_workers_stream_writer_presence_stream_workers_count: 1
```
### Multiple federation sender workers support
Until now, we only supported a single `federation_sender` worker (`matrix_synapse_workers_federation_sender_workers_count` could either be `0` or `1`).
From now on, you can have as many as you want to help with your federation traffic.
### Multiple pusher workers support
Until now, we only supported a single `pusher` worker (`matrix_synapse_workers_pusher_workers_count` could either be `0` or `1`).
From now on, you can have as many as you want to help with pushing notifications out.
### Background tasks can run on a worker
From now on, you can put [background task processing on a worker](https://matrix-org.github.io/synapse/latest/workers.html#background-tasks).
With `matrix_synapse_workers_preset: one-of-each`, you'll get one `background` worker automatically.
You can also control the `background` workers count with `matrix_synapse_workers_background_workers_count`. Only `0` or `1` workers of this type are supported by Synapse.
### Appservice worker support is back
We previously had an `appservice` worker type, which [Synapse deprecated in v1.59.0](https://github.com/matrix-org/synapse/blob/v1.59.0/docs/upgrade.md#deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types). So did we, at the time.
The new way to implement such workers is by using a `generic_worker` and dedicating it to the task of talking to Application Services.
From now on, we have support for this.
With `matrix_synapse_workers_preset: one-of-each`, you'll get one `appservice` worker automatically.
You can also control the `appservice` workers count with `matrix_synapse_workers_appservice_workers_count`. Only `0` or `1` workers of this type are supported by Synapse.
### User Directory worker support is back
We previously had a `user_dir` worker type, which [Synapse deprecated in v1.59.0](https://github.com/matrix-org/synapse/blob/v1.59.0/docs/upgrade.md#deprecation-of-the-synapseappappservice-and-synapseappuser_dir-worker-application-types). So did we, at the time.
The new way to implement such workers is by using a `generic_worker` and dedicating it to the task of serving the user directory.
From now on, we have support for this.
With `matrix_synapse_workers_preset: one-of-each`, you'll get one `user_dir` worker automatically.
You can also control the `user_dir` workers count with `matrix_synapse_workers_user_dir_workers_count`. Only `0` or `1` workers of this type are supported by Synapse.
### Using more than 1 media repository worker is now more reliable
With `matrix_synapse_workers_preset: one-of-each`, we only launch one `media_repository` worker.
If you've been configuring `matrix_synapse_workers_media_repository_workers_count` manually, you may have increased that to more workers.
When multiple media repository workers are in use, background tasks related to the media repository must always be configured to run on a single `media_repository` worker via `media_instance_running_background_jobs`. Until now, we weren't doing this correctly, but we now are.
### Potential Backward Incompatibilities after these Synapse worker changes
Below we'll discuss **potential backward incompatibilities**.
- **Worker names** (container names, systemd services, worker configuration files) **have changed**. Workers are now labeled sequentially (e.g. `matrix-synapse-worker_generic_worker-18111` -> `matrix-synapse-worker-generic-0`). The playbook will handle these changes automatically.
- Due to increased worker types support above, people who use `matrix_synapse_workers_preset: one-of-each` should be aware that with these changes, **the playbook will deploy 9 additional workers** (6 stream writers, 1 `appservice` worker, 1 `user_dir` worker, 1 background task worker). This **may increase RAM/CPU usage**, etc. If you find your server struggling, consider disabling some workers with the appropriate `matrix_synapse_workers_*_workers_count` variables.
- **Metric endpoints have also changed** (`/metrics/synapse/worker/generic_worker-18111` -> `/metrics/synapse/worker/generic-worker-0`). If you're [collecting metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server), consider revisiting our [Collecting Synapse worker metrics to an external Prometheus server](docs/configuring-playbook-prometheus-grafana.md#collecting-synapse-worker-metrics-to-an-external-prometheus-server) docs and updating your Prometheus configuration. **If you're collecting metrics to the integrated Prometheus server** (not enabled by default), **your Prometheus configuration will be updated automatically**. Old data (from before this change) may stick around though.
- **the format of `matrix_synapse_workers_enabled_list` has changed**. You were never advised to use this variable for directly creating workers (we advise people to control workers using `matrix_synapse_workers_preset` or by tweaking `matrix_synapse_workers_*_workers_count` variables only), but some people may have started using the `matrix_synapse_workers_enabled_list` variable to gain more control over workers. If you're one of them, you'll need to adjust its value. See `roles/custom/matrix-synapse/defaults/main.yml` for more information on the new format. The playbook will also do basic validation and complain if you got something wrong.
# 2022-09-09
## Cactus Comments support
Thanks to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s), the playbook can now set up [Cactus Comments](https://cactus.chat) - federated comment system for the web based on Matrix.
See our [Setting up a Cactus Comments server](docs/configuring-playbook-cactus-comments.md) documentation to get started.
# 2022-08-23
## Postmoogle email bridge support
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up the new [Postmoogle](https://gitlab.com/etke.cc/postmoogle) email bridge/bot. Postmoogle is like the [email2matrix bridge](https://github.com/devture/email2matrix) (also [already supported by the playbook](docs/configuring-playbook-email2matrix.md)), but more capable and with the intention to soon support *sending* emails, not just receiving.
See our [Setting up Postmoogle email bridging](docs/configuring-playbook-bot-postmoogle.md) documentation to get started.
# 2022-08-10
## mautrix-whatsapp default configuration changes
In [Pull Request #2012](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2012), we've made some changes to the default configuration used by the `mautrix-whatsapp` bridge.
If you're using this bridge, you should look into this PR and see if the new configuration suits you. If not, you can always change individual preferences in your `vars.yml` file.
Most notably, spaces support has been enabled by default. The bridge will now group rooms into a Matrix space. **If you've already bridged to Whatsapp** prior to this update, you will need to send `!wa sync space` to the bridge bot to make it create the space and put your existing rooms into it.
# 2022-08-09
## Conduit support
Thanks to [Charles Wright](https://github.com/cvwright), we now have optional experimental [Conduit](https://conduit.rs) homeserver support for new installations. This comes as a follow-up to the playbook getting [Dendrite support](#dendrite-support) earlier this year.
Existing Synapse or Dendrite installations do **not** need to be updated. **Synapse is still the default homeserver implementation** installed by the playbook.
To try out Conduit, we recommend that you **use a new server** and the following `vars.yml` configuration:
```yaml
matrix_homeserver_implementation: conduit
```
**The homeserver implementation of an existing server cannot be changed** (e.g. from Synapse or Dendrite to Conduit) without data loss.
# 2022-07-29
## mautrix-discord support
Thanks to [MdotAmaan](https://github.com/MdotAmaan)'s efforts, the playbook now supports bridging to [Discord](https://discordapp.com/) via the [mautrix-discord](https://mau.dev/mautrix/discord) bridge. See our [Setting up Mautrix Discord bridging](docs/configuring-playbook-bridge-mautrix-discord.md) documentation page for getting started.
**Note**: this is a new Discord bridge. The playbook still retains Discord bridging via [matrix-appservice-discord](docs/configuring-playbook-bridge-appservice-discord.md) and [mx-puppet-discord](docs/configuring-playbook-bridge-mx-puppet-discord.md). You're free too use the bridge that serves you better, or even all three of them (for different users and use-cases).
# 2022-07-27
## matrix-appservice-kakaotalk support
The playbook now supports bridging to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) via [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) - a bridge based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code. Thanks to [hnarjis](https://github.com/hnarjis) for helping us add support for this!
See our [Setting up Appservice Kakaotalk bridging](docs/configuring-playbook-bridge-appservice-kakaotalk.md) documentation to get started.
# 2022-07-20
## maubot support
Thanks to [Stuart Mumford (@Cadair)](https://github.com/cadair) for starting ([PR #373](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/373) and [PR #622](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/622)) and to [Julian-Samuel Gebühr (@moan0s)](https://github.com/moan0s) for finishing up (in [PR #1894](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1894)), the playbook can now help you set up [maubot](https://github.com/maubot/maubot) - a plugin-based Matrix bot system.
See our [Setting up maubot](docs/configuring-playbook-bot-maubot.md) documentation to get started.
# 2022-07-14
## mx-puppet-skype removal
@ -204,7 +448,7 @@ matrix_ma1sd_enabled: true
We now support installing the [matrix_encryption_disabler](https://github.com/digitalentity/matrix_encryption_disabler) Synapse module, which lets you prevent End-to-End-Encryption from being enabled by users on your homeserver. The popular opinion is that this is dangerous and shouldn't be done, but there are valid use cases for disabling encryption discussed [here](https://github.com/matrix-org/synapse/issues/4401).
To enable this module (and prevent encryption from being used on your homserver), add `matrix_synapse_ext_encryption_disabler_enabled: true` to your configuration. This module provides further customization. Check its other configuration settings (and defaults) in `roles/matrix-synapse/defaults/main.yml`.
To enable this module (and prevent encryption from being used on your homserver), add `matrix_synapse_ext_encryption_disabler_enabled: true` to your configuration. This module provides further customization. Check its other configuration settings (and defaults) in `roles/custom/matrix-synapse/defaults/main.yml`.
# 2022-02-01
@ -591,7 +835,7 @@ You have 3 ways to proceed:
- stop the bridge (`systemctl stop matrix-mautrix-facebook`)
- create a new `matrix_mautrix_facebook` Postgres database for it
- run [pgloader](https://pgloader.io/) manually (we import this bridge's data using default settings and it works well)
- define `matrix_mautrix_facebook_database_*` variables in your `vars.yml` file (credentials, etc.) - you can find their defaults in `roles/matrix-mautrix-facebook/defaults/main.yml`
- define `matrix_mautrix_facebook_database_*` variables in your `vars.yml` file (credentials, etc.) - you can find their defaults in `roles/custom/matrix-mautrix-facebook/defaults/main.yml`
- switch the bridge to Postgres (`matrix_mautrix_facebook_database_engine: 'postgres'` in your `vars.yml` file)
- re-run the playbook (`--tags=setup-all,start`) and ensure the bridge works (`systemctl status matrix-mautrix-facebook` and `journalctl -fu matrix-mautrix-facebook`)
- send a `login` message to the Facebook bridge bot again
@ -1469,7 +1713,7 @@ Having Synapse not be a required component potentially opens the door for instal
## Bridges are now separate from the Synapse role
Bridges are no longer part of the `matrix-synapse` role.
Each bridge now lives in its own separate role (`roles/matrix-bridge-*`).
Each bridge now lives in its own separate role (`roles/custom/matrix-bridge-*`).
These bridge roles are independent of the `matrix-synapse` role, so it should be possible to use them with a Synapse instance installed another way (not through the playbook).
@ -1763,7 +2007,7 @@ The following variables are no longer supported by this playbook:
- `matrix_mxisd_template_config`
You are encouraged to use the `matrix_mxisd_configuration_extension_yaml` variable to define your own mxisd configuration additions and overrides.
Refer to the [default variables file](roles/matrix-mxisd/defaults/main.yml) for more information.
Refer to the [default variables file](roles/custom/matrix-mxisd/defaults/main.yml) for more information.
This new way of configuring mxisd is beneficial because:
@ -1825,14 +2069,14 @@ Based on feedback from others, running Synapse on Python 3 is supposed to decrea
## Riot homepage customization
You can now customize some parts of the Riot homepage (or even completely replace it with your own custom page).
See the `matrix_riot_web_homepage_` variables in `roles/matrix-riot-web/defaults/main.yml`.
See the `matrix_riot_web_homepage_` variables in `roles/custom/matrix-riot-web/defaults/main.yml`.
# 2018-12-04
## mxisd extensibility
The [LDAP identity store for mxisd](https://github.com/kamax-matrix/mxisd/blob/master/docs/stores/ldap.md) can now be configured easily using playbook variables (see the `matrix_mxisd_ldap_` variables in `roles/matrix-server/defaults/main.yml`).
The [LDAP identity store for mxisd](https://github.com/kamax-matrix/mxisd/blob/master/docs/stores/ldap.md) can now be configured easily using playbook variables (see the `matrix_mxisd_ldap_` variables in `roles/custom/matrix-server/defaults/main.yml`).
# 2018-11-28

8
Makefile
View File

@ -1,7 +1,11 @@
.PHONY: lint
.PHONY: roles lint
help: ## Show this help.
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
@grep -F -h "##" $(MAKEFILE_LIST) | grep -v grep | sed -e 's/\\$$//' | sed -e 's/##//'
roles: ## Pull roles
rm -rf roles/galaxy
ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force
lint: ## Runs ansible-lint against all roles in the playbook
ansible-lint

20
README.md
View File

@ -19,9 +19,11 @@ Using this playbook, you can get the following services configured on your serve
- (optional, default) a [Synapse](https://github.com/matrix-org/synapse) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network
- (optional) a [Conduit](https://conduit.rs) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements
- (optional) a [Dendrite](https://github.com/matrix-org/dendrite) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse.
- (optional) [Amazon S3](https://aws.amazon.com/s3/) storage for Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys)
- (optional) [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys) or [`synapse-s3-storage-provider`](https://github.com/matrix-org/synapse-s3-storage-provider)
- (optional, default) [PostgreSQL](https://www.postgresql.org/) database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible.
@ -43,10 +45,14 @@ Using this playbook, you can get the following services configured on your serve
- (optional, advanced) the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider module
- (optional, advanced) the [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) a proxy that handles Matrix registration requests and forwards them to LDAP.
- (optional, advanced) the [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) spam checker module
- (optional, advanced) the [Matrix Corporal](https://github.com/devture/matrix-corporal) reconciliator and gateway for a managed Matrix server
- (optional) the [mautrix-discord](https://github.com/mautrix/discord) bridge for bridging your Matrix server to [Discord](https://discord.com/) - see [docs/configuring-playbook-bridge-mautrix-discord.md](docs/configuring-playbook-bridge-mautrix-discord.md) for setup documentation
- (optional) the [mautrix-telegram](https://github.com/mautrix/telegram) bridge for bridging your Matrix server to [Telegram](https://telegram.org/)
- (optional) the [mautrix-whatsapp](https://github.com/mautrix/whatsapp) bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/)
@ -63,7 +69,7 @@ Using this playbook, you can get the following services configured on your serve
- (optional) the [mautrix-signal](https://github.com/mautrix/signal) bridge for bridging your Matrix server to [Signal](https://www.signal.org/)
- (optional) the [beeper-linkedin](https://gitlab.com/beeper/linkedin) bridge for bridging your Matrix server to [LinkedIn](https://www.linkedin.com/)
- (optional) the [beeper-linkedin](https://github.com/beeper/linkedin) bridge for bridging your Matrix server to [LinkedIn](https://www.linkedin.com/)
- (optional) the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat)
@ -89,7 +95,7 @@ Using this playbook, you can get the following services configured on your serve
- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
- (optional) the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
- (optional) the [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
@ -103,8 +109,14 @@ Using this playbook, you can get the following services configured on your serve
- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation
- (optional) [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for invitations by creating and managing registration tokens - see [docs/configuring-playbook-bot-matrix-registration-bot.md](docs/configuring-playbook-bot-matrix-registration-bot.md) for setup documentation
- (optional) [maubot](https://github.com/maubot/maubot) a plugin-based Matrix bot system - see [docs/configuring-playbook-bot-maubot.md](docs/configuring-playbook-bot-maubot.md) for setup documentation
- (optional) [honoroit](https://gitlab.com/etke.cc/honoroit) helpdesk bot - see [docs/configuring-playbook-bot-honoroit.md](docs/configuring-playbook-bot-honoroit.md) for setup documentation
- (optional) [Postmoogle](https://gitlab.com/etke.cc/postmoogle) email to matrix bot - see [docs/configuring-playbook-bot-postmoogle.md](docs/configuring-playbook-bot-postmoogle.md) for setup documentation
- (optional) [Go-NEB](https://github.com/matrix-org/go-neb) multi functional bot written in Go - see [docs/configuring-playbook-bot-go-neb.md](docs/configuring-playbook-bot-go-neb.md) for setup documentation
- (optional) [Mjolnir](https://github.com/matrix-org/mjolnir), a moderation tool for Matrix - see [docs/configuring-playbook-bot-mjolnir.md](docs/configuring-playbook-bot-mjolnir.md) for setup documentation
@ -127,6 +139,8 @@ Using this playbook, you can get the following services configured on your serve
- (optional) the [Buscarron](https://gitlab.com/etke.cc/buscarron) bot - see [docs/configuring-playbook-bot-buscarron.md](docs/configuring-playbook-bot-buscarron.md) for setup documentation
- (optional) [Cactus Comments](https://cactus.chat), a federated comment system built on matrix - see [docs/configuring-playbook-cactus-comments.md](docs/configuring-playbook-cactus-comments.md) for setup documentation
Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
**Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.

28
docs/ansible.md
View File

@ -45,10 +45,7 @@ Alternatively, you can run Ansible inside a Docker container (powered by the [de
This ensures that you're using a very recent Ansible version, which is less likely to be incompatible with the playbook.
There are 2 ways to go about it:
- [Running Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself)
- [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)
You can either [run Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself) or [run Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server).
### Running Ansible in a container on the Matrix server itself
@ -73,13 +70,15 @@ docker run -it --rm \
-w /work \
-v `pwd`:/work \
--entrypoint=/bin/sh \
docker.io/devture/ansible:2.13.0-r0
docker.io/devture/ansible:2.13.6-r0
```
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.
You can execute `ansible-playbook ...` (or `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
Finally, you can execute `ansible-playbook ...` (or `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
### Running Ansible in a container on another computer (not the Matrix server)
@ -92,7 +91,7 @@ docker run -it --rm \
-v `pwd`:/work \
-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
--entrypoint=/bin/sh \
docker.io/devture/ansible:2.13.0-r0
docker.io/devture/ansible:2.13.6-r0
```
The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`).
@ -101,7 +100,10 @@ If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that
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.
You can execute `ansible-playbook ...` commands as per normal now.
First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
Finally, you execute `ansible-playbook ...` commands as per normal now.
#### If you don't use SSH keys for authentication
@ -112,3 +114,13 @@ apk add sshpass
```
Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.
#### Resolve directory ownership issues
Because you're `root` in the container running Ansible and this likely differs fom the owner (your regular user account) of the playbook directory outside of the container, certain playbook features which use `git` locally may report warnings such as:
> fatal: unsafe repository ('/work' is owned by someone else)
> To add an exception for this directory, call:
> git config --global --add safe.directory /work
These errors can be resolved by making `git` trust the playbook directory by running `git config --global --add safe.directory /work`

41
docs/configuring-dns.md
View File

@ -26,21 +26,29 @@ Be mindful as to how long it will take for the DNS records to propagate.
If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
When you're done configuring DNS, proceed to [Configuring the playbook](configuring-playbook.md).
## DNS settings for optional services/features
| Type | Host | Priority | Weight | Port | Target |
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------- |
| SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
| CNAME | `dimension` | - | - | - | `matrix.<your-domain>` |
| CNAME | `jitsi` | - | - | - | `matrix.<your-domain>` |
| CNAME | `stats` | - | - | - | `matrix.<your-domain>` |
| CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| CNAME | `ntfy` | - | - | - | `matrix.<your-domain>` |
| CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| CNAME | `wsproxy` | - | - | - | `matrix.<your-domain>` |
| CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
| Used by component | Type | Host | Priority | Weight | Port | Target |
| ----------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | --------------------------- |
| [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.<your-domain>` |
| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.<your-domain>` |
| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.<your-domain>` |
| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.<your-domain>` |
| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.<your-domain>` |
| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.<your-domain>` |
| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.<your-domain>` |
| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.<your-domain>` |
| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.<your-domain>` |
| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.<your-domain>` |
| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.<your-domain>` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.<your-domain>` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4:<your-ip> -all` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` |
| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` |
When setting up a SRV record, if you are asked for a service and protocol instead of a hostname split the host value from the table where the period is. For example use service as `_matrix-identity` and protocol as `_tcp`.
## Subdomains setup
@ -61,6 +69,8 @@ The `sygnal.<your-domain>` subdomain may be necessary, because this playbook cou
The `ntfy.<your-domain>` subdomain may be necessary, because this playbook could install the [ntfy](https://ntfy.sh/) UnifiedPush-compatible push notifications server. The installation of ntfy is disabled by default, it is not a core required component. To learn how to install it, see our [configuring ntfy guide](configuring-playbook-ntfy.md). If you do not wish to set up ntfy, feel free to skip the `ntfy.<your-domain>` DNS record.
The `etherpad.<your-domain>` subdomain may be necessary, because this playbook could install the [Etherpad](https://etherpad.org/) a highly customizable open source online editor providing collaborative editing in really real-time. The installation of etherpad is disabled by default, it is not a core required component. To learn how to install it, see our [configuring etherpad guide](configuring-playbook-etherpad.md). If you do not wish to set up etherpad, feel free to skip the `etherpad.<your-domain>` DNS record.
The `hydrogen.<your-domain>` subdomain may be necessary, because this playbook could install the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client. The installation of Hydrogen is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Hydrogen guide](configuring-playbook-client-hydrogen.md). If you do not wish to set up Hydrogen, feel free to skip the `hydrogen.<your-domain>` DNS record.
The `cinny.<your-domain>` subdomain may be necessary, because this playbook could install the [Cinny](https://github.com/ajbura/cinny) web client. The installation of cinny is disabled by default, it is not a core required component. To learn how to install it, see our [configuring cinny guide](configuring-playbook-client-cinny.md). If you do not wish to set up cinny, feel free to skip the `cinny.<your-domain>` DNS record.
@ -80,3 +90,8 @@ This is an optional feature for the optionally-installed [ma1sd service](configu
Note: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
When you're done with the DNS configuration and ready to proceed, continue with [Getting the playbook](getting-the-playbook.md).
## `_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

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

@ -43,22 +43,28 @@ matrix_backup_borg_location_repositories:
- USER@HOST:REPO
matrix_backup_borg_storage_encryption_passphrase: "PASSPHRASE"
matrix_backup_borg_ssh_key_private: |
PRIVATE KEY
-----BEGIN OPENSSH PRIVATE KEY-----
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZW
xpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRv
bG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3
RydWQgZXhlcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXgg
ZWEgY29tbW9kbyBjb25zZXF1YXQuIA==
-----END OPENSSH PRIVATE KEY-----
```
where:
* USER - SSH user of a provider/server
* HOST - SSH host of a provider/server
* REPO - borg repository name, it will be initialized on backup start, eg: `matrix`
* REPO - borg repository name, it will be initialized on backup start, eg: `matrix`, regarding Syntax see [Remote repositories](https://borgbackup.readthedocs.io/en/stable/usage/general.html#repository-urls)
* PASSPHRASE - passphrase used for encrypting backups, you may generate it with `pwgen -s 64 1` or use any password manager
* PRIVATE KEY - the content of the **private** part of the SSH key you created before
* PRIVATE KEY - the content of the **private** part of the SSH key you created before. The whole key (all of its belonging lines) under `matrix_backup_borg_ssh_key_private` needs to be indented with 2 spaces
To backup without encryption, add `matrix_backup_borg_encryption: 'none'` to your vars. This will also enable the `matrix_backup_borg_unknown_unencrypted_repo_access_is_ok` variable.
`matrix_backup_borg_location_source_directories` defines the list of directories to back up: it's set to `{{ matrix_base_data_path }}` by default, which is the base directory for every service's data, such as Synapse, Postgres and the bridges. You might want to exclude certain directories or file patterns from the backup using the `matrix_backup_borg_location_exclude_patterns` variable.
Check the `roles/matrix-backup-borg/defaults/main.yml` file for the full list of available options.
Check the `roles/custom/matrix-backup-borg/defaults/main.yml` file for the full list of available options.
## Installing
@ -67,3 +73,9 @@ After configuring the playbook, run the [installation](installing.md) command ag
```
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.

33
docs/configuring-playbook-bot-buscarron.md
View File

@ -5,20 +5,6 @@ The playbook can install and configure [buscarron](https://gitlab.com/etke.cc/bu
It's a bot you can use to setup **your own helpdesk on matrix**
It's a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) matrix room
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@bot.buscarron:DOMAIN`.
(to use a different username, adjust the `matrix_bot_buscarron_login` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.buscarron password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Adjusting the playbook configuration
@ -27,7 +13,10 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
```yaml
matrix_bot_buscarron_enabled: true
# Adjust this to whatever password you chose when registering the bot user
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_buscarron_login: bot.buscarron
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_buscarron_password: PASSWORD_FOR_THE_BOT
# Adjust accepted forms
@ -36,10 +25,10 @@ matrix_bot_buscarron_forms:
room: "!yourRoomID:DOMAIN" # (mandatory) Room ID where form submission will be posted
redirect: https://DOMAIN # (mandatory) To what page user will be redirected after the form submission
ratelimit: 1r/m # (optional) rate limit of the form, format: <max requests>r/<interval:s,m>, eg: 1r/s or 54r/m
hasemail: 1 # (optional) form has "email" field that should be validated
extensions: [] # (optional) list of form extensions (not used yet)
matrix_bot_buscarron_spam_hosts: [] # (optional) list of email domains/hosts that should be rejected automatically
matrix_bot_buscarron_spam_emails: [] # (optional) list of email addresses that should be rejected automatically
matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically
```
You will also need to add a DNS record so that buscarron can be accessed.
@ -57,9 +46,15 @@ matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_buscarron_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password
## Usage

15
docs/configuring-playbook-bot-go-neb.md
View File

@ -21,20 +21,7 @@ You can use the playbook to [register a new user](registering-users.md):
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
## Getting an access token
If you use curl, you can get an access token like this:
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "bot.go-neb" },
"password": "a strong password",
"type": "m.login.password"
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
```
Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token), but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start).
Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
## Adjusting the playbook configuration

30
docs/configuring-playbook-bot-honoroit.md
View File

@ -7,21 +7,6 @@ It's a bot you can use to setup **your own helpdesk on matrix**
See the project's [documentation](https://gitlab.com/etke.cc/honoroit#how-it-looks-like) to learn what it does with screenshots and why it might be useful to you.
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@honoroit:DOMAIN`.
(to use a different username, adjust the `matrix_bot_honoroit_login` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=honoroit password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
@ -29,7 +14,10 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
```yaml
matrix_bot_honoroit_enabled: true
# Adjust this to whatever password you chose when registering the bot user
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_honoroit_login: honoroit
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_honoroit_password: PASSWORD_FOR_THE_BOT
# Adjust this to your room ID
@ -41,9 +29,15 @@ matrix_bot_honoroit_roomid: "!yourRoomID:DOMAIN"
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_honoroit_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password
## Usage

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

@ -16,7 +16,7 @@ By default, the playbook will set use the bot with a username like this: `@bot.m
(to use a different username, adjust the `matrix_bot_matrix_registration_bot_matrix_user_id_localpart` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
For [other bots supported by the playbook](configuring-playbook.md#bots), Matrix bot user accounts are created and put to use automatically. For `matrix-registration-bot`, however, this is not the case - you **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-registration-bot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
@ -26,14 +26,7 @@ Choose a strong password for the bot. You can generate a good password with a co
## Obtaining an admin access token
In order to use the bot you need to add an admin user's access token token to the configuration. As you created an admin user for the
bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
You can expand "Access token" to copy it.
![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
In order to use the bot you need to add an admin user's access token token to the configuration. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
## Adjusting the playbook configuration
@ -63,7 +56,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
## Usage
To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain).
In this room send `help` and the bot will reply with all options.

30
docs/configuring-playbook-bot-matrix-reminder-bot.md
View File

@ -7,21 +7,6 @@ It's a bot you can use to **schedule one-off & recurring reminders and alarms**.
See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you.
## Registering the bot user
By default, the playbook will set up the bot with a username like this: `@bot.matrix-reminder-bot:DOMAIN`.
(to use a different username, adjust the `matrix_bot_matrix_reminder_bot_matrix_user_id_localpart` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-reminder-bot password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
@ -29,7 +14,10 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.
```yaml
matrix_bot_matrix_reminder_bot_enabled: true
# Adjust this to whatever password you chose when registering the bot user
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_matrix_reminder_bot_matrix_user_id_localpart: bot.matrix-reminder-bot
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
# Adjust this to your timezone
@ -41,9 +29,15 @@ matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password
## Usage

58
docs/configuring-playbook-bot-maubot.md Normal file
View File

@ -0,0 +1,58 @@
# Setting up maubot (optional)
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.<your-domain>/_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.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_maubot_enabled: true
matrix_bot_maubot_admins:
- yourusername: securepassword
```
You can add multiple admins. The admin accounts are not connected to any matrix ID and are only used to access the
maubot administration interface.
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
You can visit `matrix.<your-domain>/_matrix/maubot/` to manage your available plugins, clients and instances.
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.
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)
To add a client you first need to create an account and obtain a valid access token.
## Registering the bot user
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.maubot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Obtaining an admin access token
This can be done via `mbc login` then `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). To run these commands you'll need to open the bot docker container with `docker exec -it matrix-bot-maubot sh`
Alternatively, use Element or curl to [obtain an access token](obtaining-access-tokens.md). However these two methods won't allow the bot to work in encrypted rooms.

14
docs/configuring-playbook-bot-mjolnir.md
View File

@ -24,22 +24,12 @@ If you would like Mjolnir to be able to deactivate users, move aliases, shutdown
## 2. Get an access token
If you use curl, you can get an access token like this:
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "bot.mjolnir" },
"password": "PASSWORD_FOR_THE_BOT",
"type": "m.login.password"
}' 'https://matrix.DOMAIN/_matrix/client/r0/login'
```
Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token).
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
## 3. Make sure the account is free from rate limiting
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. [Currently there is no Synapse config option for this](https://github.com/matrix-org/synapse/issues/6286) so you have to manually edit the Synapse database. Manually editing the Synapse database is rarely a good idea but in this case it is required. Please ask for help if you are uncomfortable with these steps.
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). This can also be manually done by editing the Synapse database. Manually editing the Synapse database is rarely a good idea. Please ask for help if you are uncomfortable with these steps.
1. Copy the statement below into a text editor.

53
docs/configuring-playbook-bot-postmoogle.md Normal file
View File

@ -0,0 +1,53 @@
# Setting up Postmoogle (optional)
**Note**: email bridging can also happen via the [email2matrix](configuring-playbook-email2matrix.md) bridge supported by the playbook.
The playbook can install and configure [Postmoogle](https://gitlab.com/etke.cc/postmoogle) for you.
It's a bot/bridge you can use to forward emails to Matrix rooms
See the project's [documentation](https://gitlab.com/etke.cc/postmoogle) to learn what it does and why it might be useful to you.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_postmoogle_enabled: true
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_postmoogle_login: postmoogle
# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_postmoogle_password: PASSWORD_FOR_THE_BOT
```
You will also need to add several DNS records so that postmoogle can send emails.
See [Configuring DNS](configuring-dns.md).
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
**Notes**:
- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account
- if you change the bot password (`matrix_bot_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_postmoogle_password` to let the bot know its new password
## Usage
To use the bot, invite the `@postmoogle:DOMAIN` into a room you want to use as a mailbox.
Then send `!pm mailbox NAME` to expose this Matrix room as an inbox with the email address `NAME@matrix.domain`. Emails sent to that email address will be forwarded to the room.
Send `!pm help` to the room to see the bot's help menu for additional commands.
You can also refer to the upstream [documentation](https://gitlab.com/etke.cc/postmoogle).

6
docs/configuring-playbook-bridge-appservice-discord.md
View File

@ -1,6 +1,8 @@
# Setting up Appservice Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) bridge supported by the playbook.
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.
- For using as a Bot we are recommend the Appservice Discord bridge (the one being discussed here), because it supports plumbing.
- For personal use we recommend the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge, because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
The playbook can install and configure [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) for you.
@ -61,7 +63,7 @@ To get started with Portal Bridging:
1. To invite the bot to Discord, retrieve the invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).
2. Room addresses follow this syntax: `#_discord_<guildID>_<channelID>`. You can easily find the guild and channel IDs by logging into Discord in a browser and opening the desired channel. The URL will have this format: `discord.com/channels/<guildID>/<channelID>`.
3. Once you have figured out the appropriate room address, you can join by doing `/join #_discord_<guildID>_<channelID>` in your Matrix client.
3. Once you have figured out the appropriate room address, you can join by doing `/join #_discord_<guildID>_<channelID>` in your Matrix client.
## Getting Administrator access in a portal bridged room

64
docs/configuring-playbook-bridge-appservice-kakaotalk.md Normal file
View File

@ -0,0 +1,64 @@
# Setting up Appservice Kakaotalk (optional)
The playbook can install and configure [matrix-appservice-kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) for you. `matrix-appservice-kakaotalk` is a bridge to [Kakaotalk](https://www.kakaocorp.com/page/service/service/KakaoTalk?lang=ENG) based on [node-kakao](https://github.com/storycraft/node-kakao) (now unmaintained) and some [mautrix-facebook](https://github.com/mautrix/facebook) code.
**NOTE**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) to learn what it does and why it might be useful to you.
## Installing
To enable the bridge, add this to your `vars.yml` file:
```yaml
matrix_appservice_kakaotalk_enabled: true
```
You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
After adjusting your `vars.yml` file, re-run the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
To make use of the Kakaotalk bridge, see [Usage](#usage) below.
### Additional configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-appservice-kakaotalk/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_kakaotalk_configuration_extension_yaml` variable
### Set up Double Puppeting
If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
#### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature
## Usage
Start a chat with `@kakaotalkbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.

6
docs/configuring-playbook-bridge-beeper-linkedin.md
View File

@ -1,8 +1,8 @@
# Setting up Beeper Linkedin (optional)
The playbook can install and configure [beeper-linkedin](https://gitlab.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges
The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges
See the project's [documentation](https://gitlab.com/beeper/linkedin/-/blob/master/README.md) to learn what it does and why it might be useful to you.
See the project's [documentation](https://github.com/beeper/linkedin/blob/master/README.md) to learn what it does and why it might be useful to you.
```yaml
matrix_beeper_linkedin_enabled: true
@ -27,7 +27,7 @@ matrix_beeper_linkedin_configuration_extension_yaml: |
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
You may wish to look at `roles/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
## Set up Double Puppeting

2
docs/configuring-playbook-bridge-heisenbridge.md
View File

@ -8,7 +8,7 @@ See the project's [README](https://github.com/hifi/heisenbridge/blob/master/READ
## Configuration
Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/matrix-bridge-heisenbridge/defaults/main.yml).
Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/custom/matrix-bridge-heisenbridge/defaults/main.yml).
At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.DOMAIN/vars.yml`):

39
docs/configuring-playbook-bridge-hookshot.md
View File

@ -8,17 +8,36 @@ See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/l
Note: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however is soon to be archived by its author and to be replaced by hookshot.
## Setup Instructions
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
1. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) as required.
2. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below.
4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
5. Refer to [Hookshot's official instructions](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) to start using the bridge. **Important:** Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](urls-for-bridges-setup) below.
1. Enable the bridge by adding `matrix_hookshot_enabled: true` to your `vars.yml` file
2. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
3. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
4. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below.
5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
Finally, run the playbook (see [installing](installing.md)).
## Usage
Create a room and invite the Hookshot bot (`@hookshot:DOMAIN`) to it.
Make sure the bot is able to send state events (usually the Moderator power level in clients).
Send a `!hookshot help` message to see a list of help commands.
Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) for more details about using the brige's various features.
**Important:** Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](#urls-for-bridges-setup) below.
## More setup documentation
### URLs for bridges setup
@ -35,14 +54,14 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and `matrix_hookshot_metrics_proxying_enabled`. Requires `/metrics/*` endpoints to also be enabled via `matrix_nginx_proxy_proxy_matrix_metrics_enabled` (see the `matrix-nginx-proxy` role). Read more in the [Metrics section](#metrics) below. | Prometheus |
See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml).
See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/custom/matrix-bridge-hookshot/tasks/init.yml).
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
### Manage GitHub Private Key with matrix-aux role
The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml)).
- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml)).
- somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
- use the `matrix-aux` role to copy the file from an arbitrary path on your ansible client to the correct path on the server.
@ -55,7 +74,7 @@ matrix_aux_file_definitions:
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
```
For more info see the documentation in the [matrix-aux base configuration file](/roles/matrix-aux/defaults/main.yml).
For more info see the documentation in the [matrix-aux base configuration file](/roles/custom/matrix-aux/defaults/main.yml).
### Provisioning API

91
docs/configuring-playbook-bridge-mautrix-discord.md Normal file
View File

@ -0,0 +1,91 @@
# Setting up Mautrix Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridges supported by the playbook.
- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.
- For personal use with a discord account we recommend the `mautrix-discord` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
The playbook can install and configure [mautrix-discord](https://github.com/mautrix/discord) for you.
See the project's [documentation](https://docs.mau.fi/bridges/go/discord/index.html) to learn what it does and why it might be useful to you.
## Prerequisites
There are 2 ways to login to discord using this bridge, either by [scanning a QR code](#method-1-login-using-qr-code-recommended) using the Discord mobile app **or** by using a [Discord token](#method-2-login-using-discord-token-not-recommended).
If this is a dealbreaker for you, consider using one of the other Discord bridges supported by the playbook: [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) or [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md). These come with their own complexity and limitations, however, so we recommend that you proceed with this one if possible.
## Installing
To enable the bridge, add this to your `vars.yml` file:
```yaml
matrix_mautrix_discord_enabled: true
```
You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
After adjusting your `vars.yml` file, re-run the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
To make use of the bridge, see [Usage](#usage) below.
### Additional configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable
### Set up Double Puppeting
If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it.
#### Method 1: automatically, by enabling Shared Secret Auth
The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
#### Method 2: manually, by asking each user to provide a working access token
**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)).
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature
## Usage
### Logging in
#### Method 1: Login using QR code (recommended)
For using this bridge, you would need to authenticate by **scanning a QR code** with the Discord app on your phone.
You can delete the Discord app after the authentication process.
#### Method 2: Login using Discord token (not recommended)
To acquire the token, open Discord in a private browser window. Then open the developer settings (keyboard shortcut might be "ctrl+shift+i" or by pressing "F12"). Navigate to the "Network" tab then reload the page. In the URL filter or search bar type "/api" and find the response with the file name of "library". Under the request headers you should find a variable called "Authorization", this is the token to your Discord account. After copying the token, you can close the browser window.
### Bridging
1. Start a chat with `@discordbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
2. If you would like to login to Discord using a token, send `login-token` command, otherwise, send `login-qr` command.
3. You'll see a QR code which you need to scan with the Discord app on your phone. You can scan it with the camera app too, which will open Discord, which will then instruct you to scan it a 2nd time in the Discord app.
4. After confirming (in the Discord app) that you'd like to allow this login, the bot should respond with "Succcessfully authenticated as ..."
5. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to
6. Some Direct Messages from Discord should start syncing automatically
7. If you'd like to bridge guilds:
- send `guilds status` to see the list of guilds
- for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire`
8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function.

10
docs/configuring-playbook-bridge-mautrix-facebook.md
View File

@ -39,7 +39,7 @@ matrix_mautrix_facebook_configuration_extension_yaml: |
default: true
```
You may wish to look at `roles/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure.
You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure.
## Set up Double Puppeting
@ -58,13 +58,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Facebook", "initial_device_display_name": "Mautrix-Facebook"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

8
docs/configuring-playbook-bridge-mautrix-googlechat.md
View File

@ -29,13 +29,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-googlechat", "initial_device_display_name": "Mautrix-googlechat"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

8
docs/configuring-playbook-bridge-mautrix-hangouts.md
View File

@ -31,13 +31,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Hangouts", "initial_device_display_name": "Mautrix-Hangouts"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

2
docs/configuring-playbook-bridge-mautrix-instagram.md
View File

@ -31,7 +31,7 @@ matrix_mautrix_instagram_configuration_extension_yaml: |
'@YOUR_USERNAME:YOUR_DOMAIN': admin
```
You may wish to look at `roles/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
## Usage

10
docs/configuring-playbook-bridge-mautrix-signal.md
View File

@ -55,7 +55,7 @@ matrix_mautrix_signal_bridge_permissions: |
'@USER:YOUR_DOMAIN' : user
```
You may wish to look at `roles/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
## Set up Double Puppeting
@ -73,13 +73,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Signal", "initial_device_display_name": "Mautrix-Signal"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

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

@ -28,13 +28,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Telegram", "initial_device_display_name": "Mautrix-Telegram"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send `login-matrix` to the bot and follow instructions about how to send the access token to it
@ -65,3 +59,8 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
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
matrix_mautrix_telegram_filter_mode: whitelist
```

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

@ -44,13 +44,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. You can use the following command:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Whatsapp", "initial_device_display_name": "Mautrix-Whatsapp"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`

4
docs/configuring-playbook-bridge-mx-puppet-discord.md
View File

@ -1,6 +1,8 @@
# Setting up MX Puppet Discord (optional)
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridge supported by the playbook.
**Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md)and [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridges supported by the playbook.
- For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.
- For personal use with a discord account we recommend the [mautrix-discord](configuring-playbook-bridge-mautrix-discord.md) bridge, because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
The playbook can install and configure
[mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) for you.

2
docs/configuring-playbook-bridge-mx-puppet-groupme.md
View File

@ -1,7 +1,7 @@
# Setting up MX Puppet GroupMe (optional)
The playbook can install and configure
[mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) for you.
[mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) for you.
See the project page to learn what it does and why it might be useful to you.

65
docs/configuring-playbook-cactus-comments.md Normal file
View File

@ -0,0 +1,65 @@
# Setting up Cactus Comments (optional)
The playbook can install and configure [Cactus Comments](https://cactus.chat) for you.
Cactus Comments is a **federated comment system** built on Matrix. The role allows you to self-host the system.
It respects your privacy, and puts you in control.
See the project's [documentation](https://cactus.chat/docs/getting-started/introduction/) to learn what it
does and why it might be useful to you.
## Configuration
Add the following block to your `vars.yaml` and make sure to exchange the tokens to randomly generated values.
```yaml
#################
## Cactus Chat ##
#################
matrix_cactus_comments_enabled: true
# To allow guest comments without users needing to log in, you need to have guest registration enabled.
# To do this you need to uncomment one of the following lines (depending if you are using synapse or dentrite as a homeserver)
# If you don't know which one you use: The default is synapse ;)
# matrix_synapse_allow_guest_access: true
# matrix_dentrite_allow_guest_access
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
Upon starting Cactus Comments, a `bot.cactusbot` user account is created automatically.
To get started, send a `help` message to the `@bot.cactusbot:your-homeserver.com` bot to confirm it's working.
Then, register a site by typing: `register <sitename>`. You will then be invited into a moderation room.
Now you are good to go and can include the comment section on your website!
**Careful:** To really make use of self-hosting you need change a few things in comparison to the official docs!
Insert the following snippet into you page and make sure to replace `example.com` with your base domain!
```html
<script type="text/javascript" src="https://matrix.example.com/cactus-comments/cactus.js"></script>
<link rel="stylesheet" href="https://matrix.example.com/cactus-comments/style.css" type="text/css">
<div id="comment-section"></div>
<script>
initComments({
node: document.getElementById("comment-section"),
defaultHomeserverUrl: "https://matrix.example.com:8448",
serverName: "example.com",
siteName: "YourSiteName",
commentSectionId: "1"
})
</script>
```

8
docs/configuring-playbook-client-element.md
View File

@ -17,7 +17,7 @@ matrix_client_element_enabled: false
The playbook provides some customization variables you could use to change Element's settings.
Their defaults are defined in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/matrix-client-element/templates/config.json.j2`](../roles/matrix-client-element/templates/config.json.j2) template.
Their defaults are defined in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-element/templates/config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
@ -25,14 +25,14 @@ Alternatively, **if there is no pre-defined variable** for an Element setting yo
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Element's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/matrix-client-element/defaults/main.yml`](../roles/matrix-client-element/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
## Themes
To change the look of Element, you can define your own themes manually by using the `matrix_client_element__settingDefaults_custom_themes` setting.
To change the look of Element, you can define your own themes manually by using the `matrix_client_element_settingDefaults_custom_themes` setting.
Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_element_themes_enabled: true`).

58
docs/configuring-playbook-conduit.md Normal file
View File

@ -0,0 +1,58 @@
# Configuring Conduit (optional)
By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, but you can also use [Conduit](https://conduit.rs).
**NOTES**:
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Conduit). Proceed below only if you're OK with losing data or you're dealing with a server on a new domain name, which hasn't participated in the Matrix federation yet.
- **homeserver implementations other than Synapse may not be fully functional**. The playbook may also not assist you in an optimal way (like it does with Synapse). Make yourself familiar with the downsides before proceeding
## Installation
To use Conduit, you **generally** need the following additional `vars.yml` configuration:
```yaml
matrix_homeserver_implementation: conduit
```
However, since Conduit is difficult (see [famedly/conduit#276](https://gitlab.com/famedly/conduit/-/issues/276) and [famedly/conduit#354](https://gitlab.com/famedly/conduit/-/merge_requests/354)) when it comes to creating the first user account and does not support [registering users](registering-users.md) (via the command line or via the playbook) like Synapse and Dendrite do, we recommend the following flow:
1. Add `matrix_conduit_allow_registration: true` to your `vars.yml` the first time around, temporarily
2. Run the playbook (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` - see [Installing](installing.md))
3. Create your first user via Element or any other client which supports creating users
4. Get rid of `matrix_conduit_allow_registration: true` from your `vars.yml`
5. Run the playbook again (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-conduit,start` would be enough this time)
6. You can now use your server safely. Additional users can be created by messaging the internal Conduit bot
## Configuring bridges / appservices
Automatic appservice setup is currently unsupported when using conduit. After setting up the service as usual you may notice that it is unable to start.
You will have to manually register appservices using the the [register-appservice](https://gitlab.com/famedly/conduit/-/blob/next/APPSERVICES.md) command.
Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to conduit:
@conduit:your.server.name: register-appservice
```
as_token: <token>
de.sorunome.msc2409.push_ephemeral: true
hs_token: <token>
id: signal
namespaces:
aliases:
- exclusive: true
regex: ^#signal_.+:example\.org$
users:
- exclusive: true
regex: ^@signal_.+:example\.org$
- exclusive: true
regex: ^@signalbot:example\.org$
rate_limited: false
sender_localpart: _bot_signalbot
url: http://matrix-mautrix-signal:29328
```

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

@ -22,7 +22,7 @@ matrix_dimension_enabled: true
## Define admin users
These users can modify the integrations this Dimension supports.
These users can modify the integrations this Dimension supports.
Add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
@ -39,27 +39,7 @@ We recommend that you create a dedicated Matrix user for Dimension (`dimension`
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 one of two options:
*Through an interactive login*:
1. In a private browsing session (incognito window), open Element.
1. Log in with the `dimension` user and its password.
1. Set the display name and avatar, if required.
1. In the settings page choose "Help & About", scroll down to the bottom and expand the `Access Token` section.
1. Copy the access token to your configuration.
1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
*With CURL*
```
curl -X POST --header 'Content-Type: application/json' -d '{
"identifier": { "type": "m.id.user", "user": "YourDimensionUsername" },
"password": "YourDimensionPassword",
"type": "m.login.password"
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
```
*Change `YourDimensionUsername`, `YourDimensionPassword`, and `YOURDOMAIN` accordingly.*
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.**
@ -93,6 +73,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/matrix-dimension/defaults/main.yml) of the Dimension component.
To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.
You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml).

20
docs/configuring-playbook-email2matrix.md
View File

@ -1,5 +1,8 @@
# Setting up Email2Matrix (optional)
**Note**: email bridging can also happen via the [Postmoogle](configuring-playbook-bot-postmoogle.md) bot supported by the playbook.
Postmoogle is much more powerful and easier to use, so we recommend that you use it, instead of Email2Matrix.
The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you.
See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
@ -7,6 +10,10 @@ See the project's [documentation](https://github.com/devture/email2matrix/blob/m
## Preparation
### DNS configuration
It's not strictly necessary, but you may increase the chances that incoming emails reach your server by adding an `MX` record for `matrix.DOMAIN`, as described in the [Configuring DNS](configuring-dns.md) documentation page.
### Port availability
Ensure that port 25 is available on your Matrix server and open in your firewall.
@ -34,18 +41,7 @@ You'll need the room id when doing [Configuration](#configuration) below.
### Obtaining an access token for the sender user
In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it.
To do this, you can execute a command like this:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "email2matrix" }, "password": "MATRIX_PASSWORD_FOR_THE_USER", "type": "m.login.password", "device_id": "Email2Matrix", "initial_device_display_name": "Email2Matrix"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
Take note of the `access_token` value. You'll need the access token when doing [Configuration](#configuration) below.
In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
## Configuration

59
docs/configuring-playbook-etherpad.md
View File

@ -1,12 +1,20 @@
# Setting up Etherpad (optional)
[Etherpad](https://etherpad.org) is is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io)
[Etherpad](https://etherpad.org) is is an open source collaborative text editor that can be embedded in a Matrix chat room using the [Dimension integrations manager](https://dimension.t2bot.io) or used as standalone web app.
When enabled together with the Jitsi audio/video conferencing system (see [our docs on Jitsi](configuring-playbook-jitsi.md)), it will be made available as an option during the conferences.
## Prerequisites
For the self-hosted Etherpad instance to be available to your users, you must first enable and configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
Etherpad can be installed in 2 modes:
- (default) `standalone` mode (`matrix_etherpad_mode: standalone`) - Etherpad will be hosted on `etherpad.<your-domain>` (`matrix_server_fqn_etherpad`), so the DNS record for this domian must be created. See [Configuring your DNS server](configuring-dns.md) on how to set up the `etherpad` DNS record correctly
- `dimension` mode (`matrix_etherpad_mode: dimension`) - Etherpad will be hosted on `dimension.<your-domain>/etherpad` (`matrix_server_fqn_dimension`). This requires that you **first** configure the **Dimension integrations manager** as described in [the playbook documentation](configuring-playbook-dimension.md)
We recomend that you go with the default (`standalone`) mode, which makes Etherpad independent and allows it to be used with or without Dimension.
## Installing
@ -14,35 +22,40 @@ For the self-hosted Etherpad instance to be available to your users, you must fi
```yaml
matrix_etherpad_enabled: true
# Uncomment below if you'd like to install Etherpad on the Dimension domain (not recommended)
# matrix_etherpad_mode: dimension
# Uncomment below to enable the admin web UI
# matrix_etherpad_admin_username: admin
# matrix_etherpad_admin_password: some-password
```
## Set Dimension default to the self-hosted Etherpad
If enabled, the admin web-UI should then be available on `https://etherpad.<your-domain>/admin` (or `https://dimension.<your-domain>/etherpad/admin`, if `matrix_etherpad_mode: dimension`)
The Dimension administrator users can configure the default URL template. The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab. Replace `scalar.vector.im` with your own Dimension domain.
### Removing the integrated Etherpad chat
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
Example: `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false`
### Etherpad Admin access (optional)
Etherpad comes with a admin web-UI which is disabled by default. You can enable it by setting a username and password in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_etherpad_admin_username: admin
matrix_etherpad_admin_password: some-password
```
The admin web-UI should then be available on: `https://dimension.<your-domain>/etherpad/admin`
### Managing / Deleting old pads
## Managing / Deleting old pads
If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above.
Then from the plugin manager page (`https://dimension.<your-domain>/etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
Then from the plugin manager page (`https://etherpad.<your-domain>/admin/plugins` or `https://dimension.<your-domain>/etherpad/admin/plugins`), install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
## Known issues
## Set Dimension default to the self-hosted Etherpad (optional)
If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside Etherpad, the Dimension administrator users can configure the default URL template.
The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab.
### Removing the integrated Etherpad chat
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template. Examples:
- `https://etherpad.<your-domain>/p/$roomId_$padName?showChat=false` (for the default - `matrix_etherpad_mode: standalone`)
- `https://dimension.<your-domain>/etherpad/p/$roomId_$padName?showChat=false` (for `matrix_etherpad_mode: dimension`)
### Known issues
If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.
`$roomId_$padName` can end up being longer than 50 characters. You can avoid having this problem by altering the template so it only contains the three word random identifier `$padName`.

2
docs/configuring-playbook-external-postgres.md
View File

@ -20,7 +20,7 @@ matrix_synapse_database_database: "your-postgres-server-database-name"
# Rewire any other service (each `matrix-*` role) you may wish to use to use your external Postgres server.
# Each service expects to have its own dedicated database on the Postgres server
# and uses its own variable names (see `roles/matrix-*/defaults/main.yml) for configuring Postgres connectivity.
# and uses its own variable names (see `roles/custom/matrix-*/defaults/main.yml) for configuring Postgres connectivity.
```
The database (as specified in `matrix_synapse_database_database`) must exist and be accessible with the given credentials.

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

@ -14,7 +14,7 @@ Before installing Jitsi, make sure you've created the `jitsi.DOMAIN` DNS record.
You may also need to open the following ports to your server:
- `4443/tcp` - RTP media fallback over TCP
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/matrix-jitsi/defaults/main.yml)).
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`matrix_jitsi_jvb_stun_servers`](../roles/custom/matrix-jitsi/defaults/main.yml)).
## Installation
@ -87,7 +87,7 @@ For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/d
By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://github.com/jitsi/docker-jitsi-meet#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `DOCKER_HOST_ADDRESS` in enviornment variable to make it work.
The reason is the Jitsi VideoBridge git to LAN client the IP address of the docker image instead of the host. The [documentation](https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/#running-behind-nat-or-on-a-lan-environment) of Jitsi in docker suggest to add `JVB_ADVERTISE_IPS` in enviornment variable to make it work.
Here is how to do it in the playbook.
@ -95,7 +95,7 @@ Add these two lines to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configu
```yaml
matrix_jitsi_jvb_container_extra_arguments:
- '--env "DOCKER_HOST_ADDRESS=<Local IP adress of the host>"'
- '--env "JVB_ADVERTISE_IPS=<Local IP address of the host>"'
```
## (Optional) Fine tune Jitsi

7
docs/configuring-playbook-ldap-auth.md
View File

@ -28,5 +28,12 @@ If you wish for users to **authenticate only against configured password provide
matrix_synapse_password_config_localdb_enabled: false
```
## Using ma1sd Identity Server for authentication
If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).
## Handling user registration
If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md).

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

@ -33,7 +33,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/matrix-ma1sd/defaults/main.yml` file.
(in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.
## ma1sd-controlled Registration
@ -86,7 +86,7 @@ You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more d
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/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
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

33
docs/configuring-playbook-matrix-ldap-registration-proxy.md Normal file
View File

@ -0,0 +1,33 @@
# Setting up matrix-ldap-registration-proxy (optional)
The playbook can install and configure [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) for you.
This proxy handles Matrix registration requests and forwards them to LDAP.
**Please note:** This does support the full Matrix specification for registrations. It only provide a very coarse
implementation of a basic password registration.
## Quickstart
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_ldap_registration_proxy_enabled: true
# LDAP credentials
matrix_ldap_registration_proxy_ldap_uri: <URI>
matrix_ldap_registration_proxy_ldap_base_dn: <DN>
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:
```yaml
# Use the LDAP values specified for the synapse role to setup LDAP proxy
matrix_ldap_registration_proxy_ldap_uri: "{{ matrix_synapse_ext_password_provider_ldap_uri }}"
matrix_ldap_registration_proxy_ldap_base_dn: "{{ matrix_synapse_ext_password_provider_ldap_base }}"
matrix_ldap_registration_proxy_ldap_user: "{{ matrix_synapse_ext_password_provider_ldap_bind_dn }}"
matrix_ldap_registration_proxy_ldap_password: "{{ matrix_synapse_ext_password_provider_ldap_bind_password }}"
```

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

@ -64,7 +64,7 @@ Can be used to set the username for the bridge.
## Discovering additional configuration options
You may wish to look at `roles/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure.
You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure.
## Set up Double Puppeting
@ -97,7 +97,7 @@ If you have issues with a service, and are requesting support, the higher levels
## Usage
You then need to start a chat with `@SERVICENAMEbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
You then need to start a chat with `@SERVICENAMEbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
Send `login ` to the bridge bot to get started You can learn more here about authentication from the bridge's official documentation on Authentication https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html .

4
docs/configuring-playbook-nginx.md
View File

@ -42,7 +42,7 @@ Besides changing the preset (`matrix_nginx_proxy_ssl_preset`), you can also dire
- `matrix_nginx_proxy_ssl_prefer_server_ciphers`: for specifying if the server or the client choice when negotiating the cipher. It can set to `on` or `off`.
- `matrix_nginx_proxy_ssl_ciphers`: for specifying the SSL Cipher suites used by nginx.
For more information about these variables, check the `roles/matrix-nginx-proxy/defaults/main.yml` file.
For more information about these variables, check the `roles/custom/matrix-nginx-proxy/defaults/main.yml` file.
## Synapse + OpenID Connect for Single-Sign-On
@ -80,5 +80,5 @@ matrix_nginx_proxy_proxy_http_additional_server_configuration_blocks:
# These lines will be included in the nginx configuration.
# This is at the top level of the file, so you will need to define all of the `server { ... }` blocks.
- |
# For advanced use, have a look at the template files in `roles/matrix-nginx-proxy/templates/nginx/conf.d`
# For advanced use, have a look at the template files in `roles/custom/matrix-nginx-proxy/templates/nginx/conf.d`
```

5
docs/configuring-playbook-ntfy.md
View File

@ -23,7 +23,7 @@ matrix_ntfy_configuration_extension_yaml: |
log_level: DEBUG
```
For a more complete list of variables that you could override, see `roles/matrix-ntfy/defaults/main.yml`.
For a more complete list of variables that you could override, see `roles/custom/matrix-ntfy/defaults/main.yml`.
For a complete list of ntfy config options that you could put in `matrix_ntfy_configuration_extension_yaml`, see the [ntfy config documentation](https://ntfy.sh/docs/config/#config-options).
@ -71,7 +71,8 @@ Steps needed for specific matrix apps:
3. verify `Settings` -> `Notifications` -> `UnifiedPush: Notification targets` as described below in the "Troubleshooting" section.
* Element-android v1.4.26+:
- [not yet documented; should auto-detect and use it?]
1. choose `Settings` -> `Notifications` -> `Notification method` -> `ntfy`
2. verify `Settings` -> `Troubleshoot` -> `Troubleshoot notification settings`
If the matrix app asks, "Choose a distributor: FCM Fallback or ntfy", then choose "ntfy".

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

@ -1,11 +1,14 @@
# Using your own webserver, instead of this playbook's nginx proxy (optional, advanced)
By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
By default, this playbook installs its own nginx webserver (called `matrix-nginx-proxy`, in a Docker container) which listens on ports 80 and 443.
If that's alright, you can skip this.
If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
You should note, however, that the playbook's services work best when you keep using the integrated `matrix-nginx-proxy` webserver.
For example, disabling `matrix-nginx-proxy` when running a [Synapse worker setup for load-balancing](configuring-playbook-synapse.md#load-balancing-with-workers) (a more advanced, non-default configuration) is likely to cause various troubles (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090)). If you need a such more scalable setup, disabling `matrix-nginx-proxy` will be a bad idea. If yours will be a simple (default, non-worker-load-balancing) deployment, disabling `matrix-nginx-proxy` may be fine.
There are **2 ways you can go about it**, if you'd like to use your own webserver:
- [Method 1: Disabling the integrated nginx reverse-proxy webserver](#method-1-disabling-the-integrated-nginx-reverse-proxy-webserver)
@ -24,11 +27,23 @@ No matter which external webserver you decide to go with, you'll need to:
1) Make sure your web server user (something like `http`, `apache`, `www-data`, `nginx`) is part of the `matrix` group. You should run something like this: `usermod -a -G matrix nginx`. This allows your webserver user to access files owned by the `matrix` group. When using an external nginx webserver, this allows it to read configuration files from `/matrix/nginx-proxy/conf.d`. When using another server, it would make other files, such as `/matrix/static-files/.well-known`, accessible to it.
2) Edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable the integrated nginx server:
2) Edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`)
- to disable the integrated nginx server:
```yaml
matrix_nginx_proxy_enabled: false
```
```yaml
matrix_nginx_proxy_enabled: false
```
- if using an external server on another host, add the `<service>_http_host_bind_port` or `<service>_http_bind_port` variables for the services that will be exposed by the external server on the other host. The actual name of the variable is listed in the `roles/<service>/defaults/vars.yml` file for each service. Most variables follow the `<service>_http_host_bind_port` format.
These variables will make Docker expose the ports on all network interfaces instead of localhost only.
[Keep in mind that there are some security concerns if you simply proxy everything.](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints)
Here are the variables required for the default configuration (Synapse and Element)
```
matrix_synapse_container_client_api_host_bind_port: '0.0.0.0:8008'
matrix_synapse_container_federation_api_plain_host_bind_port: '0.0.0.0:8048'
matrix_client_element_container_http_host_bind_port: "0.0.0.0:8765"
```
3) **If you'll manage SSL certificates by yourself**, edit your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to disable SSL certificate retrieval:
@ -38,7 +53,6 @@ matrix_ssl_retrieval_method: none
**Note**: During [installation](installing.md), unless you've disabled SSL certificate management (`matrix_ssl_retrieval_method: none`), the playbook would need 80 to be available, in order to retrieve SSL certificates. **Please manually stop your other webserver while installing**. You can start it back up afterwards.
### Using your own external nginx webserver
Once you've followed the [Preparation](#preparation) guide above, it's time to set up your external nginx server.
@ -57,15 +71,6 @@ matrix_nginx_proxy_ssl_protocols: "TLSv1.2"
If you are experiencing issues, try updating to a newer version of Nginx. As a data point in May 2021 a user reported that Nginx 1.14.2 was not working for them. They were getting errors about socket leaks. Updating to Nginx 1.19 fixed their issue.
If you are not going to be running your webserver on the same docker network, or the same machine as matrix, these variables can be set to bind synapse to an exposed port. [Keep in mind that there are some security concerns if you simply proxy everything to it](https://github.com/matrix-org/synapse/blob/master/docs/reverse_proxy.md#synapse-administration-endpoints)
```yaml
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:8048" or "192.168.1.3:80"), or empty string to not expose.
matrix_synapse_container_client_api_host_bind_port: ''
matrix_synapse_container_federation_api_plain_host_bind_port: ''
```
### Using your own external Apache webserver
Once you've followed the [Preparation](#preparation) guide above, you can take a look at the [examples/apache](../examples/apache) directory for a sample configuration.
@ -79,7 +84,7 @@ After following the [Preparation](#preparation) guide above, you can take a loo
### Using another external webserver
Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/matrix-nginx-proxy/templates/nginx/conf.d/).
Feel free to look at the [examples/apache](../examples/apache) directory, or the [template files in the matrix-nginx-proxy role](../roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/).
## Method 2: Fronting the integrated nginx reverse-proxy webserver with another reverse-proxy

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

@ -90,11 +90,11 @@ matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_b
Using `matrix_nginx_proxy_proxy_matrix_metrics_additional_user_location_configuration_blocks` only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true` (see above).
Note : The playbook will hash the basic_auth password for you on setup. Thus, you need to give the plain-text version of the password as a variable.
Note : The playbook will hash the basic_auth password for you on setup. Thus, you need to give the plain-text version of the password as a variable.
### Collecting Synapse worker metrics to an external Prometheus server
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.DOMAIN/metrics/synapse/worker/TYPE-ID`, where `TYPE` corresponds to the type and `ID` to the instanceId of a worker as exemplified in `matrix_synapse_workers_enabled_list`.
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.DOMAIN/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:
@ -111,8 +111,8 @@ scrape_configs:
labels:
job: "master"
index: 1
- job_name: 'synapse-generic_worker-1'
metrics_path: /metrics/synapse/worker/generic_worker-18111
- job_name: 'matrix-synapse-synapse-worker-generic-worker-0'
metrics_path: /metrics/synapse/worker/generic-worker-0
scheme: https
basic_auth:
username: prometheus

137
docs/configuring-playbook-s3-goofys.md Normal file
View File

@ -0,0 +1,137 @@
# 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.
Another (and better performing) way to use S3 storage with Synapse is [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md).
Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
## Usage
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure Goofys in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_s3_media_store_enabled: true
matrix_s3_media_store_bucket_name: "your-bucket-name"
matrix_s3_media_store_aws_access_key: "access-key-goes-here"
matrix_s3_media_store_aws_secret_key: "secret-key-goes-here"
matrix_s3_media_store_region: "eu-central-1"
```
You can use any S3-compatible object store by **additionally** configuring these variables:
```yaml
matrix_s3_media_store_custom_endpoint_enabled: true
matrix_s3_media_store_custom_endpoint: "https://your-custom-endpoint"
```
If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
## Migrating from local filesystem storage to S3
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before migrating your local media store to an S3-backed one.
Follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:
- [Storing Matrix media files on Amazon S3 with Goofys (optional)](#storing-matrix-media-files-on-amazon-s3-with-goofys-optional)
- [Usage](#usage)
- [Migrating from local filesystem storage to S3](#migrating-from-local-filesystem-storage-to-s3)
- [Migrating to any S3-compatible storage (universal, but likely slow)](#migrating-to-any-s3-compatible-storage-universal-but-likely-slow)
- [Migrating to Backblaze B2](#migrating-to-backblaze-b2)
### Migrating to any S3-compatible storage (universal, but likely slow)
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. Proceed with the steps below without stopping Matrix services
2. Start by adding the base S3 configuration in your `vars.yml` file (seen above, may be different depending on the S3 provider of your choice)
3. In addition to the base configuration you see above, add this to your `vars.yml` file:
```yaml
matrix_s3_media_store_path: /matrix/s3-media-store
```
This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.
5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
```sh
sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
```
You may need to install `rsync` manually.
7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
9. Sync the files again by re-running the `rsync` command you see in step #6
10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
11. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
### Migrating to Backblaze B2
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. While all Matrix services are running, run the following command on the server:
(you need to adjust the 3 `--env` line below with your own data)
```sh
docker run -it --rm -w /work \
--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
--mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
--entrypoint=/bin/sh \
docker.io/tianon/backblaze-b2:3.6.0 \
-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET && b2 sync /work b2://$B2_BUCKET_NAME --skipNewer'
```
This is some initial file sync, which may take a very long time.
2. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
3. Run the command from step #1 again.
Doing this will sync any new files that may have been created locally in the meantime.
Now that Matrix services aren't running, we're sure to get Backblaze B2 and your local media store fully in sync.
4. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
5. Put the [Backblaze B2 settings seen above](#backblaze-b2) in your `vars.yml` file
6. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`

190
docs/configuring-playbook-s3.md
View File

@ -1,19 +1,48 @@
# Storing Matrix media files on Amazon S3 (optional)
# Storing Synapse media files on Amazon S3 or another compatible Object Storage (optional)
By default, this playbook configures your server to store Synapse's content repository (`media_store`) files on the local filesystem.
If that's alright, you can skip this.
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.
As an alternative to storing media files on the local filesystem, you can store them on [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object store.
Using a Goofys-backed media store works, but performance may not be ideal. If possible, try to use a region which is close to your Matrix server.
First, [choose an Object Storage provider](#choosing-an-object-storage-provider).
If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
Then, [create the S3 bucket](#bucket-creation-and-security-configuration).
Finally, [set up S3 storage for Synapse](#setting-up) (with [Goofys](configuring-playbook-s3-goofys.md) or [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md)).
## Choosing an Object Storage provider
You can create [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object store like [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html), [Wasabi](https://wasabi.com), [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces), etc.
Amazon S3 and Backblaze S3 are pay-as-you with no minimum charges for storing too little data.
All these providers have different prices, with Backblaze B2 appearing to be the cheapest.
Wasabi has a minimum charge of 1TB if you're storing less than 1TB, which becomes expensive if you need to store less data than that.
Digital Ocean Spaces has a minimum charge of 250GB ($5/month as of 2022-10), which is also expensive if you're storing less data than that.
Important aspects of choosing the right provider are:
- a provider by a company you like and trust (or dislike less than the others)
- a provider which has a data region close to your Matrix server (if it's farther away, high latency may cause slowdowns)
- a provider which is OK pricewise
- a provider with free or cheap egress (if you need to get the data out often, for some reason) - likely not too important for the common use-case
## Bucket creation and Security Configuration
Now that you've [chosen an Object Storage provider](#choosing-an-object-storage-provider), you need to create a storage bucket.
How you do this varies from provider to provider, with Amazon S3 being the most complicated due to its vast number of services and complicated security policies.
Below, we provider some guides for common providers. If you don't see yours, look at the others for inspiration or read some guides online about how to create a bucket. Feel free to contribute to this documentation with an update!
## Amazon S3
You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example security policy:
You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example IAM security policy:
```json
{
@ -34,154 +63,45 @@ You'll need an Amazon S3 bucket and some IAM user credentials (access key + secr
}
```
You then need to enable S3 support in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
It would be something like this:
```yaml
matrix_s3_media_store_enabled: true
matrix_s3_media_store_bucket_name: "your-bucket-name"
matrix_s3_media_store_aws_access_key: "access-key-goes-here"
matrix_s3_media_store_aws_secret_key: "secret-key-goes-here"
matrix_s3_media_store_region: "eu-central-1"
```
**NOTE**: This policy needs to be attached to an IAM user created from the **Security Credentials** menu. This is not a **Bucket Policy**.
## Using other S3-compatible object stores
## Backblaze B2
You can use any S3-compatible object store by **additionally** configuring these variables:
To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) you first need to sign up.
```yaml
matrix_s3_media_store_custom_endpoint_enabled: true
# Example: "https://storage.googleapis.com"
matrix_s3_media_store_custom_endpoint: "your-custom-endpoint"
```
You [can't easily change which region (US, Europe) your Backblaze account stores files in](https://old.reddit.com/r/backblaze/comments/hi1v90/make_the_choice_for_the_b2_data_center_region/), so make sure to carefully choose the region when signing up (hint: it's a hard to see dropdown below the username/password fields in the signup form).
### Backblaze B2
To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html):
After logging in to Backblaze:
- create a new **private** bucket through its user interface (you can call it something like `matrix-DOMAIN-media-store`)
- note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`)
- adjust its lifecycle rules to use the following **custom** rules:
- File Path: *empty value*
- Days Till Hide: *empty value*
- Days Till Delete: `1`
- note the **Endpoint** for your bucket (something like `s3.us-west-002.backblazeb2.com`).
- adjust its Lifecycle Rules to: Keep only the last version of the file
- go to [App Keys](https://secure.backblaze.com/app_keys.htm) and use the **Add a New Application Key** to create a new one
- restrict it to the previously created bucket (e.g. `matrix-DOMAIN-media-store`)
- give it *Read & Write* access
Copy the `keyID` and `applicationKey`.
The `keyID` value is your **Access Key** and `applicationKey` is your **Secret Key**.
You need the following *additional* playbook configuration (on top of what you see above):
For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) you will need:
```yaml
matrix_s3_media_store_bucket_name: "YOUR_BUCKET_NAME_GOES_HERE"
matrix_s3_media_store_aws_access_key: "YOUR_keyID_GOES_HERE"
matrix_s3_media_store_aws_secret_key: "YOUR_applicationKey_GOES_HERE"
matrix_s3_media_store_custom_endpoint_enabled: true
matrix_s3_media_store_custom_endpoint: "https://s3.us-west-002.backblazeb2.com" # this may be different for your bucket
```
- **Endpoint URL** - this is the **Endpoint** value you saw above, but prefixed with `https://`
If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
- **Region** - use the value you see in the Endpoint (e.g. `us-west-002`)
- **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.
## Migrating from local filesystem storage to S3
## Other providers
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before migrating your local media store to an S3-backed one.
For other S3-compatible providers, you may not need to configure security policies, etc. (just like for [Backblaze B2](#backblaze-b2)).
Follow one of the guides below for a migration path from a locally-stored media store to one stored on S3-compatible storage:
- [Migrating to any S3-compatible storage (universal, but likely slow)](#migrating-to-any-s3-compatible-storage-universal-but-likely-slow)
- [Migrating to Backblaze B2](#migrating-to-backblaze-b2)
### Migrating to any S3-compatible storage (universal, but likely slow)
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
1. Proceed with the steps below without stopping Matrix services
2. Start by adding the base S3 configuration in your `vars.yml` file (seen above, may be different depending on the S3 provider of your choice)
3. In addition to the base configuration you see above, add this to your `vars.yml` file:
```yaml
matrix_s3_media_store_path: /matrix/s3-media-store
```
This enables S3 support, but mounts the S3 storage bucket to `/matrix/s3-media-store` without hooking it to your homeserver yet. Your homeserver will still continue using your local filesystem for its media store.
5. Run the playbook to apply the changes: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
6. Do an **initial sync of your files** by running this **on the server** (it may take a very long time):
```sh
sudo -u matrix -- rsync --size-only --ignore-existing -avr /matrix/synapse/storage/media-store/. /matrix/s3-media-store/.
```
You may need to install `rsync` manually.
7. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
8. Start the S3 service by running this **on the server**: `systemctl start matrix-goofys`
9. Sync the files again by re-running the `rsync` command you see in step #6
10. Stop the S3 service by running this **on the server**: `systemctl stop matrix-goofys`
11. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
12. Remove the `matrix_s3_media_store_path` configuration from your `vars.yml` file (undoing step #3 above)
13. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
14. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
15. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
You most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner.
### Migrating to Backblaze B2
## Setting up
It's a good idea to [make a complete server backup](faq.md#how-do-i-backup-the-data-on-my-server) before doing this.
To set up Synapse to store files in S3, follow the instructions for the method of your choice:
1. While all Matrix services are running, run the following command on the server:
(you need to adjust the 3 `--env` line below with your own data)
```sh
docker run -it --rm -w /work \
--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
-v /matrix/synapse/storage/media-store/:/work \
--entrypoint=/bin/sh \
docker.io/tianon/backblaze-b2:2.1.0 \
-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET > /dev/null && b2 sync /work/ b2://$B2_BUCKET_NAME'
```
This is some initial file sync, which may take a very long time.
2. Stop all Matrix services (`ansible-playbook -i inventory/hosts setup.yml --tags=stop`)
3. Run the command from step #1 again.
Doing this will sync any new files that may have been created locally in the meantime.
Now that Matrix services aren't running, we're sure to get Backblaze B2 and your local media store fully in sync.
4. Get the old media store out of the way by running this command on the server:
```sh
mv /matrix/synapse/storage/media-store /matrix/synapse/storage/media-store-local-backup
```
5. Put the [Backblaze B2 settings seen above](#backblaze-b2) in your `vars.yml` file
6. Run the playbook: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start`
7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
- using [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md) (recommended)
- using [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md)

2
docs/configuring-playbook-ssl-certificates.md
View File

@ -99,7 +99,7 @@ The certificate files would be made available in `/matrix/ssl/config/live/<your-
For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal.
See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-synapse.conf`
See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-domain.conf`
Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers.

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

@ -41,14 +41,14 @@ matrix_aux_file_definitions:
group: "{{ matrix_user_groupname }}"
```
For a more complete example of available fields and values they can take, see `roles/matrix-sygnal/templates/sygnal.yaml.j2` (or the [upstream `sygnal.yaml.sample` configuration file](https://github.com/matrix-org/sygnal/blob/master/sygnal.yaml.sample)).
For a more complete example of available fields and values they can take, see `roles/custom/matrix-sygnal/templates/sygnal.yaml.j2` (or the [upstream `sygnal.yaml.sample` configuration file](https://github.com/matrix-org/sygnal/blob/master/sygnal.yaml.sample)).
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:
- makes use of the `matrix-aux` role (and its `matrix_aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See `roles/matrix-aux/defaults/main.yml` 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 `matrix-aux`.
- makes use of the `matrix-aux` role (and its `matrix_aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See `roles/custom/matrix-aux/defaults/main.yml` 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 `matrix-aux`.
- references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container)

12
docs/configuring-playbook-synapse-admin.md
View File

@ -62,3 +62,15 @@ matrix_synapse_admin_container_extra_arguments:
# The Synapse Admin container uses port 80 by default
- '--label "traefik.http.services.matrix-synapse-admin.loadbalancer.server.port=80"'
```
### Sample configuration for running behind Caddy v2
Below is a sample configuration for using this playbook with a [Caddy](https://caddyserver.com/v2) 2.0 reverse proxy (non-default configuration where `matrix-nginx-proxy` is disabled - `matrix_nginx_proxy_enabled: false`).
```caddy
# This is a basic configuration that will function the same as the default nginx proxy - exposing the synapse-admin panel to matrix.YOURSERVER.com/synapse-admin/
handle_path /synapse-admin* {
reverse_proxy localhost:8766 {
}
}
```

126
docs/configuring-playbook-synapse-s3-storage-provider.md Normal file
View File

@ -0,0 +1,126 @@
# 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.
**`synapse-s3-storage-provider` support is very new and still relatively untested. Using it may cause data loss.**
An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).
## How it works?
Summarized writings here are inspired by [this article](https://quentin.dufour.io/blog/2021-09-14/matrix-synapse-s3-storage/).
The way media storage providers in Synapse work has some caveats:
- Synapse still continues to use locally-stored files (for creating thumbnails, serving files, etc)
- the media storage provider is just an extra storage mechanism (in addition to the local filesystem)
- all files are stored locally at first, and then copied to the media storage provider (either synchronously or asynchronously)
- if a file is not available on the local filesystem, it's pulled from a media storage provider
You may be thinking **if all files are stored locally as well, what's the point**?
You can run some scripts to delete the local files once in a while (which we do automatically by default - see [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem)), thus freeing up local disk space. If these files are needed in the future (for serving them to users, etc.), Synapse will pull them from the media storage provider on demand.
While you will need some local disk space around, it's only to accommodate usage, etc., and won't grow as large as your S3 store.
## Installing
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure Goofys in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_synapse_ext_synapse_s3_storage_provider_enabled: true
matrix_synapse_ext_synapse_s3_storage_provider_config_bucket: your-bucket-name
matrix_synapse_ext_synapse_s3_storage_provider_config_region_name: some-region-name # e.g. eu-central-1
matrix_synapse_ext_synapse_s3_storage_provider_config_endpoint_url: https://.. # delete this whole line for Amazon S3
matrix_synapse_ext_synapse_s3_storage_provider_config_access_key_id: access-key-goes-here
matrix_synapse_ext_synapse_s3_storage_provider_config_secret_access_key: secret-key-goes-here
matrix_synapse_ext_synapse_s3_storage_provider_config_storage_class: STANDARD # or STANDARD_IA, etc.
# For additional advanced settings, take a look at `roles/custom/matrix-synapse/defaults/main.yml`
```
If you have existing files in Synapse's media repository (`/matrix/synapse/media-store/..`):
- new files will start being stored both locally and on the S3 store
- the existing files will remain on the local filesystem only until [migrating them to the S3 store](#migrating-your-existing-media-files-to-the-s3-store)
- at some point (and periodically in the future), you can delete local files which have been uploaded to the S3 store already
Regardless of whether you need to [Migrate your existing files to the S3 store](#migrating-your-existing-media-files-to-the-s3-store) or not, make sure you've familiarized yourself with [How it works?](#how-it-works) above and [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem) below.
## Migrating your existing media files to the S3 store
Migrating your existing data can happen in multiple ways:
- [using the `s3_media_upload` script from `synapse-s3-storage-provider`](#using-the-s3_media_upload-script-from-synapse-s3-storage-provider) (very slow when dealing with lots of data)
- [using another tool in combination with `s3_media_upload`](#using-another-tool-in-combination-with-s3_media_upload) (quicker when dealing with lots of data)
### Using the `s3_media_upload` script from `synapse-s3-storage-provider`
Instead of using `s3_media_upload` directly, which is very slow and painful for an initial data migration, we recommend [using another tool in combination with `s3_media_upload`](#using-another-tool-in-combination-with-s3_media_upload).
To copy your existing files, SSH into the server and run `/usr/local/bin/matrix-synapse-s3-storage-provider-shell`.
This launches a Synapse container, which has access to the local media store, Postgres database, S3 store and has some convenient environment variables configured for you to use (`MEDIA_PATH`, `BUCKET`, `ENDPOINT`, `UPDATE_DB_DAYS`, etc).
Then use the following commands (`$` values come from environment variables - they're **not placeholders** that you need to substitute):
- `s3_media_upload update-db $UPDATE_DB_DURATION` - create a local SQLite database (`cache.db`) with a list of media repository files (from the `synapse` Postgres database) eligible for operating on
- `$UPDATE_DB_DURATION` is influenced by the `matrix_synapse_ext_synapse_s3_storage_provider_update_db_day_count` variable (defaults to `0`)
- `$UPDATE_DB_DURATION` defaults to `0d` (0 days), which means **include files which haven't been accessed for more than 0 days** (that is, **all files will be included**).
- `s3_media_upload check-deleted $MEDIA_PATH` - check whether files in the local cache still exist in the local media repository directory
- `s3_media_upload upload $MEDIA_PATH $BUCKET --delete --storage-class $STORAGE_CLASS --endpoint-url $ENDPOINT` - uploads locally-stored files to S3 and deletes them from the local media repository directory
The `s3_media_upload upload` command may take a lot of time to complete.
Instead of running the above commands manually in the shell, you can also run the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` script which will run the same commands automatically. We demonstrate how to do it manually, because:
- it's what the upstream project demonstrates and it teaches you how to use the `s3_media_upload` tool
- allows you to check and verify the output of each command, to catch mistakes
- includes progress bars and detailed output for each command
- allows you to easily interrupt slow-running commands, etc. (the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` starts a container without interactive TTY support, so `Ctrl+C` may not work and you and require killing via `docker kill ..`)
### Using another tool in combination with `s3_media_upload`
To migrate your existing local data to S3, we recommend to:
- **first** use another tool ([`aws s3`](#copying-data-to-amazon-s3) or [`b2 sync`](#copying-data-to-backblaze-b2), etc.) to copy the local files to the S3 bucket
- **only then** [use the `s3_media_upload` tool to finish the migration](#using-the-s3_media_upload-script-from-synapse-s3-storage-provider) (this checks to ensure all files are uploaded and then deletes the local files)
#### Copying data to Amazon S3
Generally, you need to use the `aws s3` tool.
This documentation section could use an improvement. Ideally, we'd come up with a guide like the one used in [Copying data to Backblaze B2](#copying-data-to-backblaze-b2) - running `aws s3` in a container, etc.
#### Copying data to Backblaze B2
To copy to Backblaze B2, start a container like this:
```sh
docker run -it --rm \
-w /work \
--env='B2_KEY_ID=YOUR_KEY_GOES_HERE' \
--env='B2_KEY_SECRET=YOUR_SECRET_GOES_HERE' \
--env='B2_BUCKET_NAME=YOUR_BUCKET_NAME_GOES_HERE' \
--mount type=bind,src=/matrix/synapse/storage/media-store,dst=/work,ro \
--entrypoint=/bin/sh \
tianon/backblaze-b2:3.6.0 \
-c 'b2 authorize-account $B2_KEY_ID $B2_KEY_SECRET && b2 sync /work b2://$B2_BUCKET_NAME --skipNewer'
```
## Periodically cleaning up the local filesystem
As described in [How it works?](#how-it-works) above, when new media is uploaded to the Synapse homeserver, it's first stored locally and then also stored on the remote S3 storage.
By default, we periodically ensure that all local files are uploaded to S3 and are then removed from the local filesystem. This is done automatically using:
- the `/usr/local/bin/matrix-synapse-s3-storage-provider-migrate` script
- .. invoked via the `matrix-synapse-s3-storage-provider-migrate.service` service
- .. triggered by the `matrix-synapse-s3-storage-provider-migrate.timer` timer, every day at 05:00
So.. you don't need to perform any maintenance yourself.

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

@ -5,7 +5,7 @@ If that's enough for you, you can skip this document.
The playbook provides lots of customization variables you could use to change Synapse's settings.
Their defaults are defined in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml) and they ultimately end up in the generated `/matrix/synapse/config/homeserver.yaml` file (on the server). This file is generated from the [`roles/matrix-synapse/templates/synapse/homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.yaml.j2) template.
Their defaults are defined in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml) and they ultimately end up in the generated `/matrix/synapse/config/homeserver.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2`](../roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2) template.
**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
@ -13,9 +13,9 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Synapse's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).
- or, you can **extend and override the default configuration** ([`homeserver.yaml.j2`](../roles/custom/matrix-synapse/templates/synapse/homeserver.yaml.j2)) by making use of the `matrix_synapse_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/matrix-synapse/defaults/main.yml`](../roles/matrix-synapse/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml).
## Load balancing with workers
@ -42,7 +42,7 @@ matrix_postgres_process_extra_arguments: [
]
```
If you're using the default setup (the `matrix-nginx-proxy` webserver being enabled) or you're using your own `nginx` server (which imports the configuration files generated by the playbook), you're good to go. If you use some other webserver, you may need to tweak your reverse-proxy setup manually to forward traffic to the various workers.
**NOTE**: Disabling `matrix-nginx-proxy` (`matrix_nginx_proxy_enabled: false`) (that is, [using your own other webserver](configuring-playbook-own-webserver.md) when running a Synapse worker setup is likely to cause various troubles (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090)).
In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/matrix-org/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.

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

@ -3,8 +3,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
anonymized usage statistics from your homeserver. Only very [basic aggregate
data](#usage-statistics-being-submitted) (e.g. number of users) will be reported, but it helps track the
usage statistics from your homeserver. Enabling usage statistics helps track the
growth of the Matrix community, and helps to make Matrix a success.
@ -19,28 +18,9 @@ matrix_synapse_report_stats: true
## Usage statistics being submitted
If statistics reporting is enabled, the information that gets submitted to the matrix.org team [according to the source code](https://github.com/matrix-org/synapse/blob/master/synapse/app/homeserver.py) is:
When enabled, Synapse 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.
- your homeserver's domain name
- uptime of the homeserver program
- [Python](https://www.python.org/) version powering your homeserver
- total number of users on your home server (including bridged users)
- total number of native Matrix users on your home server
- total number of rooms on your homeserver
- total number of daily active users on your homeserver
- total number of daily active rooms on your homeserver
- total number of messages sent per day
- cache setting information
- CPU and memory statistics for the homeserver program
- database engine type and version
See [Synapse's documentation](https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics)
for the full list of statistics that are reported.

26
docs/configuring-playbook.md
View File

@ -18,6 +18,7 @@ You can then follow these steps inside the playbook directory:
1. edit the inventory hosts file (`inventory/hosts`) to your liking
1. (optional, advanced) to run Ansible against multiple servers with different `sudo` credentials, you can copy the sample inventory hosts yaml file for each of your hosts: (`cp examples/host.yml inventory/my_host1.yml` …) and use the [`ansible-all-hosts.sh`](../inventory/scripts/ansible-all-hosts.sh) script [in the installation step](installing.md).
For a basic Matrix installation, that's all you need.
For a more custom setup, see the [Other configuration options](#other-configuration-options) below.
@ -33,13 +34,18 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up the Jitsi video-conferencing platform](configuring-playbook-jitsi.md) (optional)
- [Setting up Etherpad](configuring-playbook-etherpad.md) (optional)
- [Setting up Dynamic DNS](configuring-playbook-dynamic-dns.md) (optional)
- [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](configuring-playbook-prometheus-grafana.md) (optional)
### Core service adjustments
- [Configuring Synapse](configuring-playbook-synapse.md) (optional)
- Homeserver configuration:
- [Configuring Synapse](configuring-playbook-synapse.md), if you're going with the default/recommended homeserver implementation (optional)
- [Configuring Conduit](configuring-playbook-conduit.md), if you've switched to the [Conduit](https://conduit.rs) homeserver implementation (optional)
- [Configuring Element](configuring-playbook-client-element.md) (optional)
@ -51,7 +57,7 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Serving your base domain using this playbook's nginx server](configuring-playbook-base-domain-serving.md) (optional)
- [Configure Nginx (optional, advanced)](configuring-playbook-nginx.md) (optional, advanced)
- [Configure Nginx](configuring-playbook-nginx.md) (optional, advanced)
- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced)
@ -85,6 +91,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up the LDAP password provider module](configuring-playbook-ldap-auth.md) (optional, advanced)
- [Setting up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md) (optional, advanced)
- [Setting up Synapse Simple Antispam](configuring-playbook-synapse-simple-antispam.md) (optional, advanced)
- [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced)
@ -92,6 +100,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
### Bridging other networks
- [Setting up Mautrix Discord bridging](configuring-playbook-bridge-mautrix-discord.md) (optional)
- [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional)
- [Setting up Mautrix Whatsapp bridging](configuring-playbook-bridge-mautrix-whatsapp.md) (optional)
@ -110,14 +120,16 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional)
- [Setting up Beeper LinkedIn bridging](configuring-playbook-bridge-beeper-linkedin.md) (optional)
- [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional)
- [Setting up Appservice Slack bridging](configuring-playbook-bridge-appservice-slack.md) (optional)
- [Setting up Appservice Webhooks bridging](configuring-playbook-bridge-appservice-webhooks.md) (optional)
- [Setting up Appservice Kakaotalk bridging](configuring-playbook-bridge-appservice-kakaotalk.md) (optional)
- [Setting up Beeper LinkedIn bridging](configuring-playbook-bridge-beeper-linkedin.md) (optional)
- [Setting up matrix-hookshot](configuring-playbook-bridge-hookshot.md) - a bridge between Matrix and multiple project management services, such as [GitHub](https://github.com), [GitLab](https://about.gitlab.com) and [JIRA](https://www.atlassian.com/software/jira). (optional)
- ~~[Setting up MX Puppet Skype bridging](configuring-playbook-bridge-mx-puppet-skype.md)~~ (optional) - this component has been broken for a long time, so it has been removed from the playbook. Consider [Setting up Go Skype Bridge bridging](configuring-playbook-bridge-go-skype-bridge.md)
@ -138,6 +150,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up Email2Matrix](configuring-playbook-email2matrix.md) (optional)
- [Setting up Postmoogle email bridging](configuring-playbook-bot-postmoogle.md) (optional)
- [Setting up Matrix SMS bridging](configuring-playbook-bridge-matrix-bridge-sms.md) (optional)
- [Setting up Heisenbridge bouncer-style IRC bridging](configuring-playbook-bridge-heisenbridge.md) (optional)
@ -149,6 +163,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) - a bot to create and manage registration tokens to invite users (optional)
- [Setting up maubot](configuring-playbook-bot-maubot.md) - a plugin-based Matrix bot system (optional)
- [Setting up honoroit](configuring-playbook-bot-honoroit.md) - a helpdesk bot (optional)
- [Setting up Go-NEB](configuring-playbook-bot-go-neb.md) - an extensible multifunctional bot (optional)
@ -170,3 +186,5 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up the Sygnal push gateway](configuring-playbook-sygnal.md) (optional)
- [Setting up the ntfy push notifications server](configuring-playbook-ntfy.md) (optional)
- [Setting up a Cactus Comments server](configuring-playbook-cactus-comments.md) - a federated comment system built on Matrix (optional)

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

@ -15,7 +15,7 @@ All services created by this playbook are meant to be installed on their own ser
As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), to use a Matrix user identifier like `@<username>:<your-domain>` while hosting services on a subdomain like `matrix.<your-domain>`, the Matrix network needs to be instructed of such delegation/redirection.
Server delegation can be configured using DNS SRV records or by setting up a `/.well-known/matrix/server` file on the base domain (`<your-domain.com>`).
Server delegation can be configured using DNS SRV records or by setting up a `/.well-known/matrix/server` file on the base domain (`<your-domain>`).
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.
@ -116,12 +116,12 @@ With this method, you **don't need** to add special HTTP headers for [CORS](http
**For nginx**, it would be something like this:
```nginx
# This is your HTTPS-enabled server for DOMAIN.
# This is your HTTPS-enabled server for example.com.
server {
server_name DOMAIN;
server_name example.com;
location /.well-known/matrix {
proxy_pass https://matrix.DOMAIN/.well-known/matrix;
proxy_pass https://matrix.example.com/.well-known/matrix;
proxy_set_header X-Forwarded-For $remote_addr;
}
@ -133,11 +133,11 @@ server {
```apache
<VirtualHost *:443>
ServerName DOMAIN
ServerName example.com
SSLProxyEngine on
ProxyPass /.well-known/matrix https://matrix.DOMAIN/.well-known/matrix nocanon
ProxyPassReverse /.well-known/matrix https://matrix.DOMAIN/.well-known/matrix nocanon
ProxyPass /.well-known/matrix https://matrix.example.com/.well-known/matrix nocanon
ProxyPassReverse /.well-known/matrix https://matrix.example.com/.well-known/matrix nocanon
# other configuration
</VirtualHost>
@ -146,30 +146,10 @@ server {
**For Caddy 2**, it would be something like this:
```caddy
DOMAIN.com {
@wellknown {
path /.well-known/matrix/*:x
}
handle @wellknown {
reverse_proxy https://matrix.DOMAIN.com {
header_up Host {http.reverse_proxy.upstream.hostport}
}
}
# Configration for the base domain goes here
# handle {
# header -Server
# encode zstd gzip
# reverse_proxy localhost:4020
# }
}
```
**For Caddy 1**, it would be something like this:
```caddy
proxy /.well-known/matrix/ https://matrix.DOMAIN {
header_upstream Host {http.reverse_proxy.upstream.hostport}
example.com {
reverse_proxy /.well-known/matrix/* https://matrix.example.com {
header_up Host {upstream_hostport}
}
}
```
@ -196,7 +176,7 @@ backend matrix-backend
```
# In the _redirects file in the website's root
/.well-known/matrix/* https://matrix.DOMAIN/.well-known/matrix/:splat 200!
/.well-known/matrix/* https://matrix.example.com/.well-known/matrix/:splat 200!
```
**For AWS CloudFront**
@ -206,13 +186,13 @@ backend matrix-backend
Make sure to:
- **replace `DOMAIN`** in the server configuration with your actual domain name
- **replace `example.com`** in the server configuration with your actual domain name
- and: to **do this for the HTTPS-enabled server block**, as that's where Matrix expects the file to be
## Confirming it works
No matter which method you've used to set up the well-known files, if you've done it correctly you should be able to see a JSON file at both of these URLs:
No matter which method you've used to set up the well-known files, if you've done it correctly you should be able to see a JSON file at these URLs:
- `https://<domain>/.well-known/matrix/server`
- `https://<domain>/.well-known/matrix/client`

14
docs/container-images.md
View File

@ -30,7 +30,9 @@ These services are not part of our default installation, but can be enabled by [
- [ma1uta/ma1sd](https://hub.docker.com/r/ma1uta/ma1sd/) - the [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server (optional)
- [matrixdotorg/dendrite-monolith](https://hub.docker.com/r/matrixdotorg/dendrite-monolith/) - the official [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver (optional)
- [matrixconduit/matrix-conduit](https://hub.docker.com/r/matrixconduit/matrix-conduit) - the [Conduit](https://conduit.rs) Matrix homeserver (optional)
- [matrixdotorg/dendrite-monolith](https://hub.docker.com/r/matrixdotorg/dendrite-monolith/) - the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver (optional)
- [ewoutp/goofys](https://hub.docker.com/r/ewoutp/goofys/) - the [Goofys](https://github.com/kahing/goofys) Amazon [S3](https://aws.amazon.com/s3/) file-system-mounting program (optional)
@ -76,7 +78,7 @@ These services are not part of our default installation, but can be enabled by [
- [sorunome/mx-puppet-discord](https://hub.docker.com/r/sorunome/mx-puppet-discord) - the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge to [Discord](https://discordapp.com) (optional)
- [xangelix/mx-puppet-groupme](https://hub.docker.com/r/xangelix/mx-puppet-groupme) - the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge to [GroupMe](https://groupme.com/) (optional)
- [xangelix/mx-puppet-groupme](https://hub.docker.com/r/xangelix/mx-puppet-groupme) - the [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) bridge to [GroupMe](https://groupme.com/) (optional)
- [icewind1991/mx-puppet-steam](https://hub.docker.com/r/icewind1991/mx-puppet-steam) - the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge to [Steam](https://steampowered.com) (optional)
@ -92,8 +94,14 @@ These services are not part of our default installation, but can be enabled by [
- [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) - the [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) bot for one-off & recurring reminders and alarms (optional)
- [moanos/matrix-registration-bot/](https://hub.docker.com/r/moanos/matrix-registration-bot/) - the [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) bot (manage registration tokens for invitations to the server) (optional)
- [dock.mau.dev/maubot/maubot](https://mau.dev/maubot/maubot/container_registry) - the [maubot](https://github.com/maubot/maubot) bot (a plugin-based Matrix bot system) (optional)
- [etke.cc/honoroit](https://gitlab.com/etke.cc/honoroit/container_registry) - the [honoroit](https://gitlab.com/etke.cc/honoroit) helpdesk bot (optional)
- [etke.cc/postmoogle](https://gitlab.com/etke.cc/postmoogle/container_registry) - the [Postmoogle](https://gitlab.com/etke.cc/postmoogle) email bridge bot (optional)
- [matrixdotorg/go-neb](https://hub.docker.com/r/matrixdotorg/go-neb) - the [Go-NEB](https://github.com/matrix-org/go-neb) bot (optional)
- [matrixdotorg/mjolnir](https://hub.docker.com/r/matrixdotorg/mjolnir) - the [mjolnir](https://github.com/matrix-org/mjolnir) moderation bot (optional)
@ -109,3 +117,5 @@ These services are not part of our default installation, but can be enabled by [
- [matrixdotorg/sygnal](https://hub.docker.com/r/matrixdotorg/sygnal/) - [Sygnal](https://github.com/matrix-org/sygnal) is a reference Push Gateway for Matrix
- [binwiederhier/ntfy](https://hub.docker.com/r/binwiederhier/ntfy/) - [ntfy](https://ntfy.sh/) is a self-hosted, UnifiedPush-compatible push notifications server
- [cactuscomments/cactus-appservice](https://hub.docker.com/r/cactuscomments/cactus-appservice/) - [Cactus Comments](https://cactus.chat) a federated comment system built on Matrix

13
docs/importing-postgres.md
View File

@ -12,8 +12,8 @@ If your database name differs, be sure to change `matrix_synapse_database_databa
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.
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 roomes, ...)
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, ...)
Before doing the actual import, **you need to upload your Postgres dump file to the server** (any path is okay).
@ -24,11 +24,14 @@ To import, run this command (make sure to replace `<server-path-to-postgres-dump
```sh
ansible-playbook -i inventory/hosts setup.yml \
--extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql>' \
--extra-vars='server_path_postgres_dump=<server-path-to-postgres-dump.sql> postgres_default_import_database=matrix' \
--tags=import-postgres
```
**Note**: `<server-path-to-postgres-dump.sql>` must be a file path to a Postgres dump file on the server (not on your local machine!).
**Notes**:
- `<server-path-to-postgres-dump.sql>` must be a file path to a Postgres dump file on the server (not on your local machine!)
- `postgres_default_import_database` defaults to `matrix`, which is useful for importing multiple databases (for dumps made with `pg_dumpall`). If you're importing a single database (e.g. `synapse`), consider changing `postgres_default_import_database` accordingly
## Troubleshooting
@ -90,7 +93,7 @@ If not, you probably get this error. `synapse` is the correct table owner, but t
"ERROR: role synapse does not exist"
```
Once the database is clear and the ownership of the tables has been fixed in the SQL file, the import task should succeed.
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)
```

87
docs/installing.md
View File

@ -1,25 +1,67 @@
# Installing
## 1. Installing the Matrix services
If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure.
Run this command to install the Matrix services:
**Before installing** and each time you update the playbook in the future, you will need to update the Ansible roles in this playbook by running `make roles`. `make roles` is a shortcut (a `roles` target defined in [`Makefile`](Makefile) and executed by the [`make`](https://www.gnu.org/software/make/) utility) which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles. If you don't have `make`, you can also manually run the `roles` commands seen in the `Makefile`.
```bash
## Playbook tags introduction
The Ansible playbook's tasks are tagged, so that certain parts of the Ansible playbook can be run without running all other tasks.
The general command syntax is: `ansible-playbook -i inventory/hosts setup.yml --tags=COMMA_SEPARATED_TAGS_GO_HERE`
Here are some playbook tags that you should be familiar with:
- `setup-all` - runs all setup tasks for all components, but does not start/restart services
- `setup-SERVICE` (e.g. `setup-bot-postmoogle`) - runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (`roles/*/main.yml`). Running per-component setup tasks is **not recommended**, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, setting up the [mautrix-telegram bridge](configuring-playbook-bridge-mautrix-telegram.md), in addition to the `setup-mautrix-telegram` tag, requires database changes (the `setup-postgres` tag) as well as reverse-proxy changes (the `setup-nginx-proxy` tag).
- `start` - starts all systemd services and makes them start automatically in the future
- `stop` - stops all systemd services
- `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created
`setup-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc.
## 1. Installing Matrix
If you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the all Ansible commands
If you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to all Ansible commands
There 2 ways to start the installation process - depending on whether you're [Installing a brand new server (without importing data)](#installing-a-brand-new-server-without-importing-data) or [Installing a server into which you'll import old data](#installing-a-server-into-which-youll-import-old-data).
### Installing a brand new server (without importing data)
If this is **a brand new** Matrix server and you **won't be importing old data into it**, run all these tags:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
```
This will do a full installation and start all Matrix services.
Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-the-future) and [Finalize the installation](#3-finalize-the-installation)
### 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.
To do the installation **without** starting services, run only the `setup-all` tag:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
```
The above command **doesn't start any services just yet** (another step does this later - below). Feel free to **re-run this setup command any time** you think something is off with the server configuration.
When this command completes, services won't be running yet.
**Notes**:
- if you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the above (and all other) Ansible commands.
- if you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to the above (and all other) Ansible commands.
## 2. Things you might want to do after installing
**Before starting the services**, you may want to do additional things like:
You can now:
- [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)
@ -27,21 +69,26 @@ The above command **doesn't start any services just yet** (another step does thi
- [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
.. and then proceed to starting all services:
## 3. Starting the services
When you're ready to start the Matrix services (and set them up to auto-start in the future), run this command:
```bash
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=start
```
## 4. Finalize the installation
Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-the-future) and [Finalize the installation](#3-finalize-the-installation)
## 2. Maintaining your setup in the future
Feel free to **re-run the setup command any time** you think something is off with the server configuration. Ansible will take your configuration and update your server to match.
## 3. Finalize the installation
Now that services are running, you need to **finalize the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md).
## 5. Things to do next
## 4. Things to do next
After you have started the services and **finalized the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md), you can:

9
docs/maintenance-synapse.md
View File

@ -16,14 +16,7 @@ Table of contents:
You can use the **[Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md)** to delete old messages on a per-room basis. **This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.
To make use of this API, **you'll need an admin access token** first. You can find your access token in the setting of some clients (like Element).
Alternatively, you can log in and obtain a new access token like this:
```
curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Synapse-Purge-History-API"}' \
https://matrix.DOMAIN/_matrix/client/r0/login
```
To make use of this API, **you'll need an admin access token** first. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
Synapse's Admin API is not exposed to the internet by default. To expose it you will need to add `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true` to your `vars.yml` file.

4
docs/maintenance-upgrading-services.md
View File

@ -10,8 +10,8 @@ To upgrade services:
- take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of
- re-run the [playbook setup](installing.md): `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`
- download the upstream Ansible roles used by the playbook by running `make roles`
- restart the services: `ansible-playbook -i inventory/hosts setup.yml --tags=start`
- re-run the [playbook setup](installing.md) and restart all serivces: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start`
**Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).

49
docs/obtaining-access-tokens.md Normal file
View File

@ -0,0 +1,49 @@
# Obtaining an Access Token
When setting up some optional features like bots and bridges you will need to provide an access token for some user. This document provides documentation on how to obtain such an access token.
**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
## Prerequisites
The user for whom you want to obtain an access token needs to already exist. You can use this playbook to [register a new user](registering-users.md), if you have not already.
Below, we describe 2 ways to generate an access token for a user - using [Element](#obtain-an-access-token-via-element) or [curl](#obtain-an-access-token-via-curl). For both ways you need the user's password.
## Obtain an access token via Element
1. In a private browsing session (incognito window), open Element.
1. Log in with the user's credentials.
1. In the settings page, choose "Help & About", scroll down to the bottom and expand the `Access Token` section (see screenshot below).
1. Copy the access token to your configuration.
1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
![Obtaining an access token with Element](assets/obtain_admin_access_token_element.png)
## Obtain an access token via curl
You can use the following command to get an access token for your user directly from the [Matrix Client-Server API](https://www.matrix.org/docs/guides/client-server-api#login):
```
curl -XPOST -d '{
"identifier": { "type": "m.id.user", "user": "USERNAME" },
"password": "PASSWORD",
"type": "m.login.password",
"device_id": "YOURDEVICEID"
}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
```
Change `USERNAME`, `PASSWORD`, and `YOURDOMAIN` accordingly.
`YOURDEVICEID` is optional and can be used to more easily identify the session later. When omitted (mind the commas in the JSON payload if you'll be omitting it), a random device ID will be generated.
Your response will look like this (prettified):
```
{
"user_id":"@USERNAME:YOURDOMAIN",
"access_token":">>>YOUR_ACCESS_TOKEN_IS_HERE<<<",
"home_server":"YOURDOMAIN",
"device_id":"YOURDEVICEID"
}
```

4
docs/prerequisites.md
View File

@ -22,11 +22,13 @@ If your distro runs within an [LXC container](https://linuxcontainers.org/), you
- [`git`](https://git-scm.com/) is the recommended way to download the playbook to your computer. `git` may also be required on the server if you will be [self-building](self-building.md) components.
- [`make`](https://www.gnu.org/software/make/) for running `make roles`, etc. (see [`Makefile`](../Makefile)), although you can also run these commands manually (without `make`)
- An HTTPS-capable web server at the base domain name (`<your-domain>`) which is capable of serving static files. Unless you decide to [Serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md) or alternatively, to use DNS SRV records for [Server Delegation](howto-server-delegation.md).
- Properly configured DNS records for `<your-domain>` (details in [Configuring DNS](configuring-dns.md)).
- Some TCP/UDP ports open. This playbook configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports:
- Some TCP/UDP ports open. This playbook (actually [Docker itself](https://docs.docker.com/network/iptables/)) configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports:
- `80/tcp`: HTTP webserver
- `443/tcp`: HTTPS webserver

1
docs/self-building.md
View File

@ -37,6 +37,7 @@ List of roles where self-building the Docker image is currently possible:
- `matrix-bot-mjolnir`
- `matrix-bot-honoroit`
- `matrix-bot-matrix-reminder-bot`
- `matrix-bot-maubot`
- `matrix-email2matrix`
Adding self-building support to other roles is welcome. Feel free to contribute!

2
docs/updating-users-passwords.md
View File

@ -34,7 +34,7 @@ where `<password-hash>` is the hash returned by the docker command above.
Use the Synapse User Admin API as described here: https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#reset-password
This requires an access token from a server admin account. *This method will also log the user out of all of their clients while the other options do not.*
This requires an [access token](obtaining-access-tokens.md) from a server admin account. *This method will also log the user out of all of their clients while the other options do not.*
If you didn't make your account a server admin when you created it, you can use the `/usr/local/bin/matrix-change-user-admin-status` script as described in [registering-users.md](registering-users.md).

45
examples/caddy2/Caddyfile
View File

@ -1,3 +1,15 @@
(cors) {
@cors_preflight method OPTIONS
handle @cors_preflight {
header Access-Control-Allow-Origin "{args.0}"
header Access-Control-Allow-Methods "HEAD, GET, POST, PUT, PATCH, DELETE"
header Access-Control-Allow-Headers "Content-Type, Authorization"
header Access-Control-Max-Age "3600"
}
}
matrix.DOMAIN.tld {
# creates letsencrypt certificate
@ -81,6 +93,13 @@ matrix.DOMAIN.tld {
header Access-Control-Allow-Origin *
file_server
}
# If you have other well-knowns already handled by your base domain, you can replace the above block by this one, along with the replacement suggested in the base domain
#handle @wellknown {
# # .well-known is handled by base domain
# reverse_proxy https://DOMAIN.tld {
# header_up Host {http.reverse_proxy.upstream.hostport}
#}
handle {
encode zstd gzip
@ -114,6 +133,8 @@ element.DOMAIN.tld {
# creates letsencrypt certificate
# tls your@email.com
import cors https://*.DOMAIN.tld
header {
# Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
@ -123,6 +144,8 @@ element.DOMAIN.tld {
X-Content-Type-Options "nosniff"
# Disallow the site to be rendered within a frame (clickjacking protection)
X-Frame-Options "DENY"
# If using integrations that add frames to Element, such as Dimension and its integrations running on the same domain, it can be a good idea to limit sources allowed to be rendered
# Content-Security-Policy frame-src https://*.DOMAIN.tld
# X-Robots-Tag
X-Robots-Tag "noindex, noarchive, nofollow"
}
@ -144,6 +167,8 @@ element.DOMAIN.tld {
# # creates letsencrypt certificate
# # tls your@email.com
#
# import cors https://*.DOMAIN.tld
#
# header {
# # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
# Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
@ -151,8 +176,8 @@ element.DOMAIN.tld {
# X-XSS-Protection "1; mode=block"
# # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
# X-Content-Type-Options "nosniff"
# # Disallow the site to be rendered within a frame (clickjacking protection)
# X-Frame-Options "DENY"
# # Only allow same base domain to render this website in a frame; Can be removed if the client (Element for example) is hosted on another domain (clickjacking protection)
# Content-Security-Policy frame-ancestors https://*.DOMAIN.tld
# # X-Robots-Tag
# X-Robots-Tag "noindex, noarchive, nofollow"
# }
@ -176,6 +201,8 @@ element.DOMAIN.tld {
# creates letsencrypt certificate
# tls your@email.com
#
# import cors https://*.DOMAIN.tld
#
# header {
# # Enable HTTP Strict Transport Security (HSTS) to force clients to always connect via HTTPS
# Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
@ -185,9 +212,9 @@ element.DOMAIN.tld {
#
# # Prevent some browsers from MIME-sniffing a response away from the declared Content-Type
# X-Content-Type-Options "nosniff"
#
# # Disallow the site to be rendered within a frame (clickjacking protection)
# X-Frame-Options "SAMEORIGIN"
# # Only allow same base domain to render this website in a frame; Can be removed if the client (Element for example) is hosted on another domain
# Content-Security-Policy frame-ancestors https://*.DOMAIN.tld
#
# # Disable some features
# Feature-Policy "accelerometer 'none';ambient-light-sensor 'none'; autoplay 'none';camera 'none';encrypted-media 'none';focus-without-user-activation 'none'; geolocation 'none';gyroscope #'none';magnetometer 'none';microphone 'none';midi 'none';payment 'none';picture-in-picture 'none'; speaker 'none';sync-xhr 'none';usb 'none';vr 'none'"
@ -225,6 +252,14 @@ element.DOMAIN.tld {
# header_up Host {http.reverse_proxy.upstream.hostport}
# }
# }
# # If you have other well-knowns already handled by your base domain, you can replace the above block by this one, along with the replacement suggested in the matrix subdomain
# # handle /.well-known/* {
# # encode zstd gzip
# # header Cache-Control max-age=14400
# # header Content-Type application/json
# # header Access-Control-Allow-Origin *
# #}
#
# # Configration for the base domain goes here
# # handle {
# # header -Server

11
examples/host.yml Normal file
View File

@ -0,0 +1,11 @@
---
# This is a host file for usage with the `ansible-all-hosts.sh` script,
# which runs Ansible against a bunch of hosts, each with its own `sudo` password.
matrix_servers:
hosts:
matrix.<your domain>:
ansible_host: <your server's external ip address>
ansible_ssh_user: <your ssh user>
become: true
become_user: root

4
examples/vars.yml
View File

@ -12,7 +12,9 @@
matrix_domain: YOUR_BARE_DOMAIN_NAME_HERE
# The Matrix homeserver software to install.
# See `roles/matrix-base/defaults/main.yml` for valid options.
# See:
# - `roles/custom/matrix-base/defaults/main.yml` for valid options
# - the `docs/configuring-playbook-IMPLEMENTATION_NAME.md` documentation page, if one is available for your implementation choice
matrix_homeserver_implementation: synapse
# A secret used as a base, for generating various other secrets.

417
group_vars/matrix_servers
View File

@ -9,6 +9,46 @@
# You can also override ANY variable (seen here or in any given role),
# by re-defining it in your own configuration file (`inventory/host_vars/matrix.<your-domain>`).
########################################################################
# #
# com.devture.ansible.role.timesync #
# #
########################################################################
# To completely disable installing systemd-timesyncd/ntpd, use `devture_timesync_installation_enabled: false`.
########################################################################
# #
# /com.devture.ansible.role.timesync #
# #
########################################################################
######################################################################
#
# com.devture.ansible.role.playbook_state_preserver
#
######################################################################
# To completely disable this feature, use `devture_playbook_state_preserver_enabled: false`.
devture_playbook_state_preserver_uid: "{{ matrix_user_uid }}"
devture_playbook_state_preserver_gid: "{{ matrix_user_gid }}"
devture_playbook_state_preserver_vars_preservation_dst: "{{ matrix_base_data_path }}/vars.yml"
devture_playbook_state_preserver_commit_hash_preservation_dst: "{{ matrix_base_data_path }}/git_hash.yml"
######################################################################
#
# /com.devture.ansible.role.playbook_state_preserver
#
######################################################################
######################################################################
#
# matrix-base
@ -22,16 +62,18 @@ matrix_identity_server_url: "{{ ('https://' + matrix_server_fqn_matrix) if matri
matrix_homeserver_container_url: |-
{{
'http://matrix-nginx-proxy:12080' if matrix_nginx_proxy_enabled else {
'synapse': ('http://matrix-synapse:'+ matrix_synapse_container_client_api_port | string),
'dendrite': ('http://matrix-dendrite:' + matrix_dendrite_http_bind_port | string),
'synapse': ('http://matrix-synapse:'+ matrix_synapse_container_client_api_port|string),
'dendrite': ('http://matrix-dendrite:' + matrix_dendrite_http_bind_port|string),
'conduit': ('http://matrix-conduit:' + matrix_conduit_port_number|string),
}[matrix_homeserver_implementation]
}}
matrix_homeserver_container_federation_url: |-
{{
'http://matrix-nginx-proxy:12088' if matrix_nginx_proxy_enabled else {
'synapse': ('http://matrix-synapse:'+ matrix_synapse_container_federation_api_plain_port | string),
'dendrite': ('http://matrix-dendrite:' + matrix_dendrite_http_bind_port | string),
'synapse': ('http://matrix-synapse:'+ matrix_synapse_container_federation_api_plain_port|string),
'dendrite': ('http://matrix-dendrite:' + matrix_dendrite_http_bind_port|string),
'conduit': ('http://matrix-conduit:' + matrix_conduit_port_number|string),
}[matrix_homeserver_implementation]
}}
@ -137,7 +179,7 @@ matrix_appservice_webhooks_systemd_required_services_list: |
# We don't enable bridges by default.
matrix_appservice_slack_enabled: false
matrix_appservice_slack_container_image_self_build: "{{ matrix_architecture != 'amd64' }}"
matrix_appservice_slack_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
# Normally, matrix-nginx-proxy is enabled and nginx can reach matrix-appservice-slack over the container network.
# If matrix-nginx-proxy is not enabled, or you otherwise have a need for it, you can expose
@ -213,6 +255,43 @@ matrix_appservice_irc_database_password: "{{ '%s' | format(matrix_homeserver_gen
#
######################################################################
######################################################################
#
# matrix-bridge-appservice-kakaotalk
#
######################################################################
# We don't enable bridges by default.
matrix_appservice_kakaotalk_enabled: false
matrix_appservice_kakaotalk_systemd_required_services_list: |
{{
['docker.service']
+
['matrix-appservice-kakaotalk-node.service']
+
['matrix-' + matrix_homeserver_implementation + '.service']
+
(['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
+
(['matrix-postgres.service'] if matrix_postgres_enabled else [])
}}
matrix_appservice_kakaotalk_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'as.kakao.hs') | to_uuid }}"
matrix_appservice_kakaotalk_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'as.kakao.hs') | to_uuid }}"
matrix_appservice_kakaotalk_login_shared_secret: "{{ matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret if matrix_synapse_ext_password_provider_shared_secret_auth_enabled else '' }}"
matrix_appservice_kakaotalk_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
matrix_appservice_kakaotalk_database_password: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'as.kakao.db') | to_uuid }}"
######################################################################
#
# /matrix-bridge-appservice-kakaotalk
#
######################################################################
######################################################################
#
@ -261,7 +340,7 @@ matrix_beeper_linkedin_database_password: "{{ '%s' | format(matrix_homeserver_ge
# We don't enable bridges by default.
matrix_go_skype_bridge_enabled: false
matrix_go_skype_bridge_container_image_self_build: true
matrix_go_skype_bridge_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
matrix_go_skype_bridge_systemd_required_services_list: |
{{
@ -626,7 +705,7 @@ matrix_mautrix_whatsapp_database_password: "{{ '%s' | format(matrix_homeserver_g
######################################################################
#
# matrix-bridge-mautrix-wsproxy
# matrix-bridge-mautrix-discord
#
######################################################################
@ -660,7 +739,45 @@ matrix_mautrix_wsproxy_login_shared_secret: "{{ matrix_synapse_ext_password_prov
#
######################################################################
######################################################################
#
# matrix-bridge-mautrix-wsproxy
#
######################################################################
matrix_mautrix_discord_enabled: false
matrix_mautrix_discord_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
matrix_mautrix_discord_systemd_required_services_list: |
{{
['docker.service']
+
['matrix-' + matrix_homeserver_implementation + '.service']
+
(['matrix-postgres.service'] if matrix_postgres_enabled else [])
+
(['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
}}
matrix_mautrix_discord_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'maudisc.as.tok') | to_uuid }}"
matrix_mautrix_discord_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'maudisc.hs.tok') | to_uuid }}"
matrix_mautrix_discord_login_shared_secret: "{{ matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret if matrix_synapse_ext_password_provider_shared_secret_auth_enabled else '' }}"
# Postgres is the default, except if not using `matrix_postgres` (internal postgres)
matrix_mautrix_discord_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
matrix_mautrix_discord_database_password: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'maudiscord.db') | to_uuid }}"
# Enabling bridge.restricted_rooms for this bridge does not work well with Conduit, so we disable it by default.
# This will be fixed in the upcoming `0.5.0` release of conduit.
matrix_mautrix_discord_bridge_restricted_rooms: "{{ false if matrix_homeserver_implementation == 'conduit' else true }}"
######################################################################
#
# /matrix-bridge-mautrix-discord
#
######################################################################
######################################################################
#
@ -726,7 +843,7 @@ matrix_heisenbridge_systemd_wanted_services_list: |
# We don't enable bridges by default.
matrix_hookshot_enabled: false
matrix_hookshot_container_image_self_build: "{{ matrix_architecture not in ['amd64'] }}"
matrix_hookshot_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
matrix_hookshot_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'hookshot.as.tok') | to_uuid }}"
@ -1058,6 +1175,48 @@ matrix_bot_matrix_registration_bot_systemd_required_services_list: |
#
######################################################################
######################################################################
#
# matrix-bot-maubot
#
######################################################################
# We don't enable bots by default.
matrix_bot_maubot_enabled: false
matrix_bot_maubot_container_image_self_build: "{{ matrix_architecture not in ['amd64'] }}"
matrix_bot_maubot_systemd_required_services_list: |
{{
['docker.service']
+
['matrix-' + matrix_homeserver_implementation + '.service']
+
(['matrix-postgres.service'] if matrix_postgres_enabled else [])
+
(['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
}}
matrix_bot_maubot_registration_shared_secret: |-
{{
{
'synapse': matrix_synapse_registration_shared_secret,
'dendrite': matrix_dendrite_registration_shared_secret,
}[matrix_homeserver_implementation]
}}
matrix_bot_maubot_management_interface_http_bind_port: "{{ '' if matrix_nginx_proxy_enabled else ('127.0.0.1:' + matrix_bot_maubot_management_interface_port | string) }}"
# Postgres is the default, except if not using `matrix_postgres` (internal postgres)
matrix_bot_maubot_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
matrix_bot_maubot_database_password: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'mxpup.dsc.db') | to_uuid }}"
######################################################################
#
# /matrix-bot-maubot
#
######################################################################
######################################################################
#
@ -1082,7 +1241,7 @@ matrix_bot_honoroit_systemd_required_services_list: |
# Postgres is the default, except if not using `matrix_postgres` (internal postgres)
matrix_bot_honoroit_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
matrix_bot_honoroit_database_password: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'honoroit.bot.db') | to_uuid }}"
matrix_bot_honoroit_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}"
matrix_bot_honoroit_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
######################################################################
#
@ -1113,7 +1272,7 @@ matrix_bot_buscarron_systemd_required_services_list: |
# Postgres is the default, except if not using `matrix_postgres` (internal postgres)
matrix_bot_buscarron_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
matrix_bot_buscarron_database_password: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'buscarron.bot.db') | to_uuid }}"
matrix_bot_buscarron_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}"
matrix_bot_buscarron_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
######################################################################
#
@ -1121,6 +1280,39 @@ matrix_bot_buscarron_container_image_self_build: "{{ matrix_architecture not in
#
######################################################################
######################################################################
#
# matrix-bot-postmoogle
#
######################################################################
# We don't enable bots by default.
matrix_bot_postmoogle_enabled: false
matrix_bot_postmoogle_ssl_path: "{{ matrix_ssl_config_dir_path }}"
matrix_bot_postmoogle_tls_cert: "/ssl/live/{{ matrix_bot_postmoogle_domain }}/fullchain.pem"
matrix_bot_postmoogle_tls_key: "/ssl/live/{{ matrix_bot_postmoogle_domain }}/privkey.pem"
matrix_bot_postmoogle_systemd_required_services_list: |
{{
['docker.service']
+
(['matrix-postgres.service'] if matrix_postgres_enabled else [])
+
(['matrix-synapse.service'] if matrix_synapse_enabled else [])
}}
# Postgres is the default, except if not using `matrix_postgres` (internal postgres)
matrix_bot_postmoogle_database_engine: "{{ 'postgres' if matrix_postgres_enabled else 'sqlite' }}"
matrix_bot_postmoogle_database_password: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'postmoogle.db') | to_uuid }}"
matrix_bot_postmoogle_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
######################################################################
#
# /matrix-bot-postmoogle
#
######################################################################
######################################################################
#
@ -1218,6 +1410,35 @@ matrix_backup_borg_systemd_required_services_list: |
# /matrix-backup-borg
#
######################################################################
######################################################################
#
# matrix-cactus-comments
#
######################################################################
matrix_cactus_comments_enabled: false
# Derive secret values from homeserver secret
matrix_cactus_comments_as_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'cactus.as.token') | to_uuid }}"
matrix_cactus_comments_hs_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'cactus.hs.token') | to_uuid }}"
matrix_cactus_comments_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}"
matrix_cactus_comments_systemd_required_services_list: |
{{
(['docker.service'])
+
(['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
+
(['matrix-' + matrix_homeserver_implementation + '.service'])
}}
matrix_cactus_comments_client_nginx_path: "{{ '/cactus-comments/' if matrix_nginx_proxy_enabled else matrix_cactus_comments_client_path + '/' }}"
######################################################################
#
# /matrix-cactus-comments
#
######################################################################
######################################################################
#
@ -1339,6 +1560,8 @@ matrix_etherpad_enabled: false
matrix_etherpad_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:9001' }}"
matrix_etherpad_base_url: "{{ 'https://'+ matrix_server_fqn_dimension + matrix_etherpad_public_endpoint if matrix_etherpad_mode == 'dimension' else 'https://' + matrix_server_fqn_etherpad + '/' }}"
matrix_etherpad_systemd_required_services_list: |
{{
['docker.service']
@ -1427,6 +1650,20 @@ matrix_jitsi_etherpad_base: "{{ matrix_etherpad_base_url if matrix_etherpad_enab
# /matrix-jitsi
#
######################################################################
######################################################################
#
# matrix-ldap-registration-proxy
#
######################################################################
# This is only for users with a specific LDAP setup
matrix_ldap_registration_proxy_enabled: false
######################################################################
#
# /matrix-ldap-registration-proxy
#
######################################################################
######################################################################
#
@ -1535,6 +1772,7 @@ matrix_nginx_proxy_proxy_matrix_client_api_client_max_body_size_mb: |-
{
'synapse': matrix_synapse_max_upload_size_mb,
'dendrite': (matrix_dendrite_max_file_size_bytes / 1024 / 1024) | round,
'conduit': (matrix_conduit_max_request_size / 1024 / 1024) | round,
}[matrix_homeserver_implementation]|int
}}
@ -1548,6 +1786,7 @@ matrix_nginx_proxy_proxy_hydrogen_enabled: "{{ matrix_client_hydrogen_enabled }}
matrix_nginx_proxy_proxy_cinny_enabled: "{{ matrix_client_cinny_enabled }}"
matrix_nginx_proxy_proxy_buscarron_enabled: "{{ matrix_bot_buscarron_enabled }}"
matrix_nginx_proxy_proxy_dimension_enabled: "{{ matrix_dimension_enabled }}"
matrix_nginx_proxy_proxy_etherpad_enabled: "{{ matrix_etherpad_enabled and matrix_etherpad_mode == 'standalone' }}"
matrix_nginx_proxy_proxy_bot_go_neb_enabled: "{{ matrix_bot_go_neb_enabled }}"
matrix_nginx_proxy_proxy_jitsi_enabled: "{{ matrix_jitsi_enabled }}"
matrix_nginx_proxy_proxy_grafana_enabled: "{{ matrix_grafana_enabled }}"
@ -1570,6 +1809,7 @@ matrix_nginx_proxy_proxy_matrix_federation_api_enabled: |-
{
'synapse': (matrix_synapse_federation_port_enabled and not matrix_synapse_tls_federation_listener_enabled),
'dendrite': matrix_dendrite_federation_enabled,
'conduit': matrix_conduit_allow_federation,
}[matrix_homeserver_implementation]|bool
}}
@ -1588,6 +1828,12 @@ matrix_nginx_proxy_proxy_dendrite_client_api_addr_sans_container: "127.0.0.1:{{
matrix_nginx_proxy_proxy_dendrite_federation_api_addr_with_container: "matrix-dendrite:{{ matrix_dendrite_http_bind_port | string }}"
matrix_nginx_proxy_proxy_dendrite_federation_api_addr_sans_container: "127.0.0.1:{{ matrix_dendrite_http_bind_port | string }}"
matrix_nginx_proxy_proxy_conduit_enabled: "{{ matrix_conduit_enabled }}"
matrix_nginx_proxy_proxy_conduit_client_api_addr_with_container: "matrix-conduit:{{ matrix_conduit_port_number|string }}"
matrix_nginx_proxy_proxy_conduit_client_api_addr_sans_container: "127.0.0.1:{{ matrix_conduit_port_number|string }}"
matrix_nginx_proxy_proxy_conduit_federation_api_addr_with_container: "matrix-conduit:{{ matrix_conduit_port_number|string }}"
matrix_nginx_proxy_proxy_conduit_federation_api_addr_sans_container: "127.0.0.1:{{ matrix_conduit_port_number|string }}"
# When matrix-nginx-proxy is disabled, the actual port number that the vhost uses may begin to matter.
matrix_nginx_proxy_proxy_matrix_federation_port: "{{ matrix_federation_public_port }}"
@ -1610,14 +1856,20 @@ matrix_nginx_proxy_synapse_workers_enabled: "{{ matrix_synapse_workers_enabled }
matrix_nginx_proxy_synapse_workers_list: "{{ matrix_synapse_workers_enabled_list }}"
matrix_nginx_proxy_synapse_generic_worker_client_server_locations: "{{ matrix_synapse_workers_generic_worker_client_server_endpoints }}"
matrix_nginx_proxy_synapse_generic_worker_federation_locations: "{{ matrix_synapse_workers_generic_worker_federation_endpoints }}"
matrix_nginx_proxy_synapse_stream_writer_typing_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_typing_stream_worker_client_server_endpoints }}"
matrix_nginx_proxy_synapse_stream_writer_to_device_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_to_device_stream_worker_client_server_endpoints }}"
matrix_nginx_proxy_synapse_stream_writer_account_data_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_account_data_stream_worker_client_server_endpoints }}"
matrix_nginx_proxy_synapse_stream_writer_receipts_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_receipts_stream_worker_client_server_endpoints }}"
matrix_nginx_proxy_synapse_stream_writer_presence_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_presence_stream_worker_client_server_endpoints }}"
matrix_nginx_proxy_synapse_media_repository_locations: "{{matrix_synapse_workers_media_repository_endpoints|default([]) }}"
matrix_nginx_proxy_synapse_user_dir_locations: "{{ matrix_synapse_workers_user_dir_endpoints|default([]) }}"
matrix_nginx_proxy_synapse_frontend_proxy_locations: "{{ matrix_synapse_workers_frontend_proxy_endpoints|default([]) }}"
matrix_nginx_proxy_synapse_user_dir_locations: "{{ matrix_synapse_workers_user_dir_worker_client_server_endpoints|default([]) }}"
matrix_nginx_proxy_systemd_wanted_services_list: |
{{
['matrix-' + matrix_homeserver_implementation + '.service']
+
(matrix_synapse_webserving_workers_systemd_services_list if matrix_homeserver_implementation == 'synapse' and matrix_synapse_workers_enabled else [])
+
(['matrix-corporal.service'] if matrix_corporal_enabled else [])
+
(['matrix-ma1sd.service'] if matrix_ma1sd_enabled else [])
@ -1642,7 +1894,7 @@ matrix_nginx_proxy_systemd_wanted_services_list: |
+
(['matrix-bot-go-neb.service'] if matrix_bot_go_neb_enabled else [])
+
(['matrix-etherpad.service'] if matrix_etherpad_enabled and matrix_dimension_enabled else [])
(['matrix-etherpad.service'] if matrix_etherpad_enabled else [])
+
(['matrix-hookshot.service'] if matrix_hookshot_enabled else [])
}}
@ -1663,6 +1915,8 @@ matrix_ssl_domains_to_obtain_certificates_for: |
+
([matrix_server_fqn_dimension] if matrix_dimension_enabled else [])
+
([matrix_server_fqn_etherpad] if (matrix_etherpad_enabled and matrix_etherpad_mode == 'standalone') else [])
+
([matrix_server_fqn_bot_go_neb] if matrix_bot_go_neb_enabled else [])
+
([matrix_server_fqn_jitsi] if matrix_jitsi_enabled else [])
@ -1675,6 +1929,8 @@ matrix_ssl_domains_to_obtain_certificates_for: |
+
([matrix_server_fqn_ntfy] if matrix_ntfy_enabled else [])
+
([matrix_bot_postmoogle_domain] if matrix_bot_postmoogle_enabled else [])
+
([matrix_domain] if matrix_nginx_proxy_base_domain_serving_enabled else [])
+
matrix_ssl_additional_domains_to_obtain_certificates_for
@ -1721,10 +1977,6 @@ matrix_postgres_additional_databases: |
}] if (matrix_synapse_enabled and matrix_synapse_database_database != matrix_postgres_db_name and matrix_synapse_database_host == 'matrix-postgres') else [])
+
([{
'name': matrix_dendrite_appservice_database,
'username': matrix_dendrite_database_user,
'password': matrix_dendrite_database_password,
},{
'name': matrix_dendrite_federationapi_database,
'username': matrix_dendrite_database_user,
'password': matrix_dendrite_database_password,
@ -1776,6 +2028,18 @@ matrix_postgres_additional_databases: |
'password': matrix_bot_honoroit_database_password,
}] if (matrix_bot_honoroit_enabled and matrix_bot_honoroit_database_engine == 'postgres' and matrix_bot_honoroit_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_bot_postmoogle_database_name,
'username': matrix_bot_postmoogle_database_username,
'password': matrix_bot_postmoogle_database_password,
}] if (matrix_bot_postmoogle_enabled and matrix_bot_postmoogle_database_engine == 'postgres' and matrix_bot_postmoogle_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_bot_maubot_database_name,
'username': matrix_bot_maubot_database_username,
'password': matrix_bot_maubot_database_password,
}] if (matrix_bot_maubot_enabled and matrix_bot_maubot_database_engine == 'postgres' and matrix_bot_maubot_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_bot_buscarron_database_name,
'username': matrix_bot_buscarron_database_username,
@ -1806,6 +2070,12 @@ matrix_postgres_additional_databases: |
'password': matrix_appservice_irc_database_password,
}] if (matrix_appservice_irc_enabled and matrix_appservice_irc_database_engine == 'postgres' and matrix_appservice_irc_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_appservice_kakaotalk_database_name,
'username': matrix_appservice_kakaotalk_database_username,
'password': matrix_appservice_kakaotalk_database_password,
}] if (matrix_appservice_kakaotalk_enabled and matrix_appservice_kakaotalk_database_engine == 'postgres' and matrix_appservice_kakaotalk_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_beeper_linkedin_database_name,
'username': matrix_beeper_linkedin_database_username,
@ -1872,6 +2142,12 @@ matrix_postgres_additional_databases: |
'password': matrix_mautrix_whatsapp_database_password,
}] if (matrix_mautrix_whatsapp_enabled and matrix_mautrix_whatsapp_database_engine == 'postgres' and matrix_mautrix_whatsapp_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_mautrix_discord_database_name,
'username': matrix_mautrix_discord_database_username,
'password': matrix_mautrix_discord_database_password,
}] if (matrix_mautrix_discord_enabled and matrix_mautrix_discord_database_engine == 'postgres' and matrix_mautrix_discord_database_hostname == 'matrix-postgres') else [])
+
([{
'name': matrix_mx_puppet_slack_database_name,
'username': matrix_mx_puppet_slack_database_username,
@ -1928,18 +2204,9 @@ matrix_postgres_additional_databases: |
}}
matrix_postgres_import_roles_to_ignore: |
matrix_postgres_systemd_services_to_stop_for_maintenance_list: |
{{
[matrix_postgres_connection_username]
+
matrix_postgres_additional_databases|map(attribute='username') | list
}}
matrix_postgres_import_databases_to_ignore: |
{{
[matrix_postgres_db_name]
+
matrix_postgres_additional_databases|map(attribute='name') | list
['matrix-' + matrix_homeserver_implementation + '.service']
}}
######################################################################
@ -2008,7 +2275,7 @@ matrix_redis_enabled: "{{ matrix_synapse_workers_enabled }}"
# If you wish to connect to your Matrix server by other means, you may wish to disable this.
matrix_client_element_enabled: true
matrix_client_element_container_image_self_build: "{{ matrix_architecture != 'amd64' }}"
matrix_client_element_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
# Normally, matrix-nginx-proxy is enabled and nginx can reach Element over the container network.
# If matrix-nginx-proxy is not enabled, or you otherwise have a need for it, you can expose
@ -2076,7 +2343,7 @@ matrix_client_hydrogen_self_check_validate_certificates: "{{ false if matrix_ssl
matrix_client_cinny_enabled: false
matrix_client_cinny_container_image_self_build: "{{ matrix_architecture != 'amd64' }}"
matrix_client_cinny_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
# Normally, matrix-nginx-proxy is enabled and nginx can reach Cinny over the container network.
# If matrix-nginx-proxy is not enabled, or you otherwise have a need for it, you can expose
@ -2103,9 +2370,7 @@ matrix_synapse_enabled: "{{ matrix_homeserver_implementation == 'synapse' }}"
matrix_synapse_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
# When ma1sd is enabled, we can use it to validate email addresses and phone numbers.
# Synapse can validate email addresses by itself as well, but it's probably not what we want by default when we have an identity server.
matrix_synapse_account_threepid_delegates_email: "{{ 'http://matrix-ma1sd:' + matrix_ma1sd_container_port | string if matrix_ma1sd_enabled else '' }}"
# When ma1sd is enabled, we can use it to validate phone numbers. It's something that the homeserver cannot do by itself.
matrix_synapse_account_threepid_delegates_msisdn: "{{ 'http://matrix-ma1sd:' + matrix_ma1sd_container_port | string if matrix_ma1sd_enabled else '' }}"
# Normally, matrix-nginx-proxy is enabled and nginx can reach Synapse over the container network.
@ -2182,7 +2447,7 @@ matrix_synapse_systemd_required_services_list: |
+
(['matrix-postgres.service'] if matrix_postgres_enabled else [])
+
(['matrix-goofys'] if matrix_s3_media_store_enabled else [])
(['matrix-goofys.service'] if matrix_s3_media_store_enabled else [])
}}
matrix_synapse_systemd_wanted_services_list: |
@ -2197,6 +2462,9 @@ matrix_synapse_redis_enabled: "{{ matrix_redis_enabled }}"
matrix_synapse_redis_host: "{{ 'matrix-redis' if matrix_redis_enabled else '' }}"
matrix_synapse_redis_password: "{{ matrix_redis_connection_password if matrix_redis_enabled else '' }}"
matrix_synapse_container_runtime_injected_arguments: "{{ matrix_homeserver_container_runtime_injected_arguments }}"
matrix_synapse_app_service_runtime_injected_config_files: "{{ matrix_homeserver_app_service_runtime_injected_config_files }}"
######################################################################
#
# /matrix-synapse
@ -2306,13 +2574,24 @@ matrix_grafana_enabled: false
# Grafana's HTTP port to the local host.
matrix_grafana_container_http_host_bind_port: "{{ '' if matrix_nginx_proxy_enabled else '127.0.0.1:3000' }}"
matrix_grafana_dashboard_download_urls_all: |
matrix_grafana_dashboard_download_urls: |
{{
matrix_grafana_dashboard_download_urls
(matrix_synapse_grafana_dashboard_urls if matrix_homeserver_implementation == 'synapse' and matrix_synapse_metrics_enabled else [])
+
(matrix_prometheus_node_exporter_dashboard_urls if matrix_prometheus_node_exporter_enabled else [])
+
(matrix_prometheus_postgres_exporter_dashboard_urls if matrix_prometheus_postgres_exporter_enabled else [])
}}
matrix_grafana_default_home_dashboard_path: |-
{{
{
'synapse': ('/etc/grafana/dashboards/synapse.json' if matrix_synapse_metrics_enabled else '/etc/grafana/dashboards/node-exporter-full.json'),
'dendrite': '/etc/grafana/dashboards/node-exporter-full.json',
'conduit': '/etc/grafana/dashboards/node-exporter-full.json',
}[matrix_homeserver_implementation]
}}
matrix_grafana_systemd_wanted_services_list: |
{{
[]
@ -2346,6 +2625,7 @@ matrix_registration_shared_secret: |-
{
'synapse': matrix_synapse_registration_shared_secret,
'dendrite': matrix_dendrite_registration_shared_secret,
'conduit': '',
}[matrix_homeserver_implementation]
}}
@ -2453,7 +2733,7 @@ matrix_dendrite_systemd_required_services_list: |
+
(['matrix-postgres.service'] if matrix_postgres_enabled else [])
+
(['matrix-goofys'] if matrix_s3_media_store_enabled else [])
(['matrix-goofys.service'] if matrix_s3_media_store_enabled else [])
}}
matrix_dendrite_systemd_wanted_services_list: |
@ -2461,8 +2741,71 @@ matrix_dendrite_systemd_wanted_services_list: |
(['matrix-coturn.service'] if matrix_coturn_enabled else [])
}}
matrix_dendrite_container_runtime_injected_arguments: "{{ matrix_homeserver_container_runtime_injected_arguments }}"
matrix_dendrite_app_service_runtime_injected_config_files: "{{ matrix_homeserver_app_service_runtime_injected_config_files }}"
######################################################################
#
# /matrix-dendrite
#
######################################################################
######################################################################
#
# matrix-conduit
#
######################################################################
matrix_conduit_enabled: "{{ matrix_homeserver_implementation == 'conduit' }}"
matrix_conduit_systemd_required_services_list: |
{{
(['docker.service'])
}}
######################################################################
#
# /matrix-conduit
#
######################################################################
######################################################################
#
# matrix-user-creator
#
######################################################################
matrix_user_creator_users_auto: |
{{
[{
'username': matrix_bot_matrix_reminder_bot_matrix_user_id_localpart,
'initial_password': matrix_bot_matrix_reminder_bot_matrix_user_password,
'initial_type': 'bot',
}] if matrix_bot_matrix_reminder_bot_enabled else []
+
[{
'username': matrix_bot_honoroit_login,
'initial_password': matrix_bot_honoroit_password,
'initial_type': 'bot',
}] if matrix_bot_honoroit_enabled else []
+
[{
'username': matrix_bot_postmoogle_login,
'initial_password': matrix_bot_postmoogle_password,
'initial_type': 'bot',
}] if matrix_bot_postmoogle_enabled else []
+
[{
'username': matrix_bot_buscarron_login,
'initial_password': matrix_bot_buscarron_password,
'initial_type': 'bot',
}] if matrix_bot_buscarron_enabled else []
}}
######################################################################
#
# /matrix-user-creator
#
######################################################################

32
inventory/scripts/ansible-all-hosts.sh Executable file
View File

@ -0,0 +1,32 @@
#!/usr/bin/env bash
#
# Run the playbook on multiple hosts with different credentials with this script
# It defaults to ansible tags "setup-all,start". You can pass alternative tags
# to this script as arguments, e.g.
#
# ./inventory/scripts/ansible-all-hosts.sh self-check
#
# set playbook root path
root=$(dirname "$(readlink -f "$0")")/../..
# set default tags or get from first argument if any
tags="${1:-setup-all,start}"
# init password array
declare -A pws
# capture passwords for all hosts
for host in "$root"/inventory/*.yml; do
read -rp "sudo password for $(basename "$host"): " -s pw
pws[$host]="$pw"
echo
done
# run ansible on all captured passwords/hosts
for host in "${!pws[@]}"; do
ansible-playbook "$root"/setup.yml \
--inventory-file "$host" \
--extra-vars "ansible_become_pass=${pws[$host]}" \
--tags="$tags"
done

8
inventory/scripts/jitsi-generate-passwords.sh
View File

@ -18,7 +18,7 @@ JIBRI_XMPP_PASSWORD=$(generatePassword)
echo "# Paste these variables into your inventory/host_vars/matrix.DOMAIN/vars.yml file:"
echo ""
echo "matrix_jitsi_jicofo_auth_password: "$JICOFO_AUTH_PASSWORD
echo "matrix_jitsi_jvb_auth_password: "$JVB_AUTH_PASSWORD
echo "matrix_jitsi_jibri_recorder_password: "$JIBRI_RECORDER_PASSWORD
echo "matrix_jitsi_jibri_xmpp_password: "$JIBRI_XMPP_PASSWORD
echo "matrix_jitsi_jicofo_auth_password: $JICOFO_AUTH_PASSWORD"
echo "matrix_jitsi_jvb_auth_password: $JVB_AUTH_PASSWORD"
echo "matrix_jitsi_jibri_recorder_password: $JIBRI_RECORDER_PASSWORD"
echo "matrix_jitsi_jibri_xmpp_password: $JIBRI_XMPP_PASSWORD"

16
requirements.yml Normal file
View File

@ -0,0 +1,16 @@
---
- src: git+https://github.com/devture/com.devture.ansible.role.playbook_help.git
version: c1f40e82b4d6b072b6f0e885239322bdaaaf554f
- src: git+https://github.com/devture/com.devture.ansible.role.systemd_docker_base.git
version: 327d2e17f5189ac2480d6012f58cf64a2b46efba
- src: git+https://github.com/devture/com.devture.ansible.role.timesync.git
version: 461ace97fcf0e36c76747b36fcad8587d9b072f5
- src: git+https://github.com/devture/com.devture.ansible.role.playbook_state_preserver.git
version: ff2fd42e1c1a9e28e3312bbd725395f9c2fc7f16
- src: git+https://github.com/devture/com.devture.ansible.role.playbook_runtime_messages.git
version: f1c78d4e85e875129790c58335d0e44385683f6b

9
roles/matrix-aux/defaults/main.yml → roles/custom/matrix-aux/defaults/main.yml
View File

@ -50,6 +50,9 @@ matrix_aux_file_default_mode: '0640'
# then you likely need to add `/matrix/some/path` to `matrix_aux_directory_definitions` as well.
# You don't need to do this for directories that the playbook already creates for you.
#
# Use a `content` key for text content and `src` with a location to a file for binary content.
# The `content` key does not support binary content (see https://github.com/ansible/ansible/issues/11594).
#
# Example:
#
# matrix_aux_file_definitions:
@ -69,4 +72,10 @@ matrix_aux_file_default_mode: '0640'
# mode: '0600'
# owner: 'some-user'
# group: 'some-group'
#
# - dest: /matrix/aux/binary-file.dat
# src: "/path/to/binary.dat"
# mode: '0600'
# owner: 'some-user'
# group: 'some-group'
matrix_aux_file_definitions: []

0
roles/matrix-aux/tasks/main.yml → roles/custom/matrix-aux/tasks/main.yml
View File

3
roles/matrix-aux/tasks/setup.yml → roles/custom/matrix-aux/tasks/setup.yml
View File

@ -11,8 +11,9 @@
- name: Ensure AUX files are created
ansible.builtin.copy:
src: "{{ item.src if 'src' in item else omit }}"
content: "{{ item.content if 'content' in item else omit }}"
dest: "{{ item.dest }}"
content: "{{ item.content }}"
owner: "{{ item.owner | default(matrix_user_username) }}"
group: "{{ item.group | default(matrix_user_groupname) }}"
mode: "{{ item.mode | default(matrix_aux_file_default_mode) }}"

5
roles/matrix-backup-borg/defaults/main.yml → roles/custom/matrix-backup-borg/defaults/main.yml
View File

@ -26,8 +26,11 @@ matrix_backup_borg_systemd_required_services_list: ['docker.service']
# List of systemd services that matrix-backup-borg.service wants
matrix_backup_borg_systemd_wanted_services_list: []
# systemd calendar configuration for backup job
# systemd calendar configuration for the backup job
# the actual job may run with a delay (see matrix_backup_borg_schedule_randomized_delay_sec)
matrix_backup_borg_schedule: "*-*-* 04:00:00"
# the delay with which the systemd timer may run in relation to the `matrix_backup_borg_schedule` schedule
matrix_backup_borg_schedule_randomized_delay_sec: 2h
# what directories should be added to backup
matrix_backup_borg_location_source_directories: []

0
roles/matrix-backup-borg/tasks/init.yml → roles/custom/matrix-backup-borg/tasks/init.yml
View File

0
roles/matrix-backup-borg/tasks/main.yml → roles/custom/matrix-backup-borg/tasks/main.yml
View File

25
roles/matrix-backup-borg/tasks/setup_install.yml → roles/custom/matrix-backup-borg/tasks/setup_install.yml
View File

@ -1,8 +1,16 @@
---
- block:
- when: matrix_backup_borg_postgresql_enabled | bool and matrix_backup_borg_version == ''
block:
- name: Fail with matrix_backup_borg_version advice if Postgres not enabled
ansible.builtin.fail:
msg: >-
You are not running a built-in Postgres server (`matrix_postgres_enabled: false`), so auto-detecting its version and setting `matrix_backup_borg_version` automatically based on that cannot happen.
Consider setting `matrix_backup_borg_version` to your Postgres version manually.
when: not matrix_postgres_enabled
- ansible.builtin.import_role:
name: matrix-postgres
name: custom/matrix-postgres
tasks_from: detect_existing_postgres_version
- name: Fail if detected Postgres version is unsupported
@ -13,7 +21,6 @@
- name: Set the correct borg backup version to use
ansible.builtin.set_fact:
matrix_backup_borg_version: "{{ matrix_postgres_detected_version }}"
when: matrix_backup_borg_postgresql_enabled | bool and matrix_backup_borg_version == ''
- name: Ensure borg paths exist
ansible.builtin.file:
@ -52,15 +59,15 @@
mode: 0600
- name: Ensure borg image is pulled
docker_image:
community.docker.docker_image:
name: "{{ matrix_backup_borg_docker_image }}"
source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
force_source: "{{ matrix_backup_borg_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_backup_borg_docker_image_force_pull }}"
when: "not matrix_backup_borg_container_image_self_build | bool"
register: result
retries: "{{ matrix_container_retries_count }}"
delay: "{{ matrix_container_retries_delay }}"
retries: "{{ devture_playbook_help_container_retries_count }}"
delay: "{{ devture_playbook_help_container_retries_delay }}"
until: result is not failed
- name: Ensure borg repository is present on self-build
@ -75,7 +82,7 @@
when: "matrix_backup_borg_container_image_self_build | bool"
- name: Ensure borg image is built
docker_image:
community.docker.docker_image:
name: "{{ matrix_backup_borg_docker_image }}"
source: build
force_source: "{{ matrix_backup_borg_git_pull_results.changed if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
@ -89,14 +96,14 @@
- name: Ensure matrix-backup-borg.service installed
ansible.builtin.template:
src: "{{ role_path }}/templates/systemd/matrix-backup-borg.service.j2"
dest: "{{ matrix_systemd_path }}/matrix-backup-borg.service"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.service"
mode: 0644
register: matrix_backup_borg_systemd_service_result
- name: Ensure matrix-backup-borg.timer installed
ansible.builtin.template:
src: "{{ role_path }}/templates/systemd/matrix-backup-borg.timer.j2"
dest: "{{ matrix_systemd_path }}/matrix-backup-borg.timer"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.timer"
mode: 0644
register: matrix_backup_borg_systemd_timer_result

8
roles/matrix-backup-borg/tasks/setup_uninstall.yml → roles/custom/matrix-backup-borg/tasks/setup_uninstall.yml
View File

@ -1,7 +1,7 @@
---
- name: Check existence of matrix-backup-borg service
ansible.builtin.stat:
path: "{{ matrix_systemd_path }}/matrix-backup-borg.service"
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.service"
register: matrix_backup_borg_service_stat
- name: Ensure matrix-backup-borg is stopped
@ -15,13 +15,13 @@
- name: Ensure matrix-backup-borg.service doesn't exist
ansible.builtin.file:
path: "{{ matrix_systemd_path }}/matrix-backup-borg.service"
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.service"
state: absent
when: "matrix_backup_borg_service_stat.stat.exists | bool"
- name: Ensure matrix-backup-borg.timer doesn't exist
ansible.builtin.file:
path: "{{ matrix_systemd_path }}/matrix-backup-borg.timer"
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.timer"
state: absent
when: "matrix_backup_borg_service_stat.stat.exists | bool"
@ -36,6 +36,6 @@
state: absent
- name: Ensure borg Docker image doesn't exist
docker_image:
community.docker.docker_image:
name: "{{ matrix_backup_borg_docker_image }}"
state: absent

0
roles/matrix-backup-borg/tasks/validate_config.yml → roles/custom/matrix-backup-borg/tasks/validate_config.yml
View File

0
roles/matrix-backup-borg/templates/config.yaml.j2 → roles/custom/matrix-backup-borg/templates/config.yaml.j2
View File

0
roles/matrix-backup-borg/templates/passwd.j2 → roles/custom/matrix-backup-borg/templates/passwd.j2
View File

0
roles/matrix-backup-borg/templates/sshkey.j2 → roles/custom/matrix-backup-borg/templates/sshkey.j2
View File

14
roles/matrix-backup-borg/templates/systemd/matrix-backup-borg.service.j2 → roles/custom/matrix-backup-borg/templates/systemd/matrix-backup-borg.service.j2
View File

@ -12,10 +12,10 @@ DefaultDependencies=no
[Service]
Type=oneshot
Environment="HOME={{ matrix_systemd_unit_home_path }}"
ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-backup-borg 2>/dev/null || true'
ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-backup-borg 2>/dev/null || true'
ExecStartPre=-{{ matrix_host_command_docker }} run --rm --name matrix-backup-borg \
Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} kill matrix-backup-borg 2>/dev/null || true'
ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-backup-borg 2>/dev/null || true'
ExecStartPre=-{{ devture_systemd_docker_base_host_command_docker }} run --rm --name matrix-backup-borg \
--log-driver=none \
--cap-drop=ALL \
--read-only \
@ -33,7 +33,7 @@ ExecStartPre=-{{ matrix_host_command_docker }} run --rm --name matrix-backup-bor
{{ matrix_backup_borg_docker_image }} \
sh -c "borgmatic --init --encryption {{ matrix_backup_borg_encryption }}"
ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-backup-borg \
ExecStart={{ devture_systemd_docker_base_host_command_docker }} run --rm --name matrix-backup-borg \
--log-driver=none \
--cap-drop=ALL \
--read-only \
@ -50,8 +50,8 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-backup-borg \
{% endfor %}
{{ matrix_backup_borg_docker_image }}
ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-backup-borg 2>/dev/null || true'
ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-backup-borg 2>/dev/null || true'
ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} kill matrix-backup-borg 2>/dev/null || true'
ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-backup-borg 2>/dev/null || true'
SyslogIdentifier=matrix-backup-borg
[Install]

2
roles/matrix-backup-borg/templates/systemd/matrix-backup-borg.timer.j2 → roles/custom/matrix-backup-borg/templates/systemd/matrix-backup-borg.timer.j2
View File

@ -4,7 +4,7 @@ Description=Matrix Borg Backup timer
[Timer]
Unit=matrix-backup-borg.service
OnCalendar={{ matrix_backup_borg_schedule }}
RandomizedDelaySec=2h
RandomizedDelaySec={{ matrix_backup_borg_schedule_randomized_delay_sec }}
[Install]
WantedBy=timers.target

31
roles/matrix-base/defaults/main.yml → roles/custom/matrix-base/defaults/main.yml
View File

@ -28,7 +28,7 @@ matrix_homeserver_admin_contacts: []
matrix_homeserver_support_url: ''
# This will contain the homeserver implementation that is in use.
# Valid values: synapse, dendrite
# Valid values: synapse, dendrite, conduit
#
# By default, we use Synapse, because it's the only full-featured Matrix server at the moment.
#
@ -62,6 +62,9 @@ matrix_server_fqn_buscarron: "buscarron.{{ matrix_domain }}"
# This is where you access the Dimension.
matrix_server_fqn_dimension: "dimension.{{ matrix_domain }}"
# This is where you access the etherpad (if enabled via matrix_etherpad_enabled; disabled by default).
matrix_server_fqn_etherpad: "etherpad.{{ matrix_domain }}"
# For use with Go-NEB! (github callback url for example)
matrix_server_fqn_bot_go_neb: "goneb.{{ matrix_domain }}"
@ -95,14 +98,6 @@ matrix_debian_arch: "{{ 'armhf' if matrix_architecture == 'arm32' else matrix_ar
matrix_container_global_registry_prefix: "docker.io/"
# Each docker pull will retry on failed attempt 10 times with delay of 10 seconds between each attempt.
matrix_container_retries_count: 10
matrix_container_retries_delay: 10
# Each get_url will retry on failed attempt 10 times with delay of 10 seconds between each attempt.
matrix_geturl_retries_count: 10
matrix_geturl_retries_delay: 10
matrix_user_username: "matrix"
matrix_user_groupname: "matrix"
@ -116,12 +111,6 @@ matrix_base_data_path: "/matrix"
matrix_base_data_path_mode: "750"
matrix_static_files_base_path: "{{ matrix_base_data_path }}/static-files"
matrix_systemd_path: "/etc/systemd/system"
# Specifies the path to use for the `HOME` environment variable for systemd unit files.
# Docker 20.10 complains with `WARNING: Error loading config file: .dockercfg: $HOME is not defined`
# if `$HOME` is not defined, so we define something to make it happy.
matrix_systemd_unit_home_path: /root
# This is now unused. We keep it so that cleanup tasks can use it.
# To be removed in the future.
@ -129,16 +118,10 @@ matrix_cron_path: "/etc/cron.d"
matrix_local_bin_path: "/usr/local/bin"
matrix_host_command_docker: "/usr/bin/env docker"
matrix_host_command_sleep: "/usr/bin/env sleep"
matrix_host_command_chown: "/usr/bin/env chown"
matrix_host_command_fusermount: "/usr/bin/env fusermount"
matrix_host_command_openssl: "/usr/bin/env openssl"
matrix_host_command_systemctl: "/usr/bin/env systemctl"
matrix_host_command_sh: "/usr/bin/env sh"
matrix_ntpd_package: "{{ 'systemd-timesyncd' if (ansible_os_family == 'RedHat' and ansible_distribution_major_version | int > 7) or (ansible_distribution == 'Ubuntu' and ansible_distribution_major_version | int > 18) else ( 'systemd' if ansible_os_family == 'Suse' else 'ntp' ) }}"
matrix_ntpd_service: "{{ 'systemd-timesyncd' if (ansible_os_family == 'RedHat' and ansible_distribution_major_version | int > 7) or (ansible_distribution == 'Ubuntu' and ansible_distribution_major_version | int > 18) or ansible_distribution == 'Archlinux' or ansible_os_family == 'Suse' else ('ntpd' if ansible_os_family == 'RedHat' else 'ntp') }}"
matrix_homeserver_url: "https://{{ matrix_server_fqn_matrix }}"
@ -258,12 +241,6 @@ matrix_well_known_matrix_support_configuration: "{{ matrix_well_known_matrix_sup
# The Docker network that all services would be put into
matrix_docker_network: "matrix"
# Controls whether we'll preserve the vars.yml file on the Matrix server.
# If you have a differently organized inventory, you may wish to disable this feature,
# or to repoint `matrix_vars_yml_snapshotting_src` to the file you'd like to preserve.
matrix_vars_yml_snapshotting_enabled: true
matrix_vars_yml_snapshotting_src: "{{ inventory_dir }}/host_vars/{{ inventory_hostname }}/vars.yml"
# Controls whether a `/.well-known/matrix/server` file is generated and used at all.
#
# If you wish to rely on DNS SRV records only, you can disable this.

0
roles/matrix-base/files/yum.repos.d/docker-ce-centos.repo → roles/custom/matrix-base/files/yum.repos.d/docker-ce-centos.repo
View File

0
roles/matrix-base/files/yum.repos.d/docker-ce-fedora.repo → roles/custom/matrix-base/files/yum.repos.d/docker-ce-fedora.repo
View File

0
roles/matrix-base/tasks/clean_up_old_files.yml → roles/custom/matrix-base/tasks/clean_up_old_files.yml
View File

12
roles/custom/matrix-base/tasks/ensure_fuse_installed.yml Normal file
View File

@ -0,0 +1,12 @@
---
# This is for both RedHat 7 and 8
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/ensure_fuse_installed_redhat.yml"
when: ansible_os_family == 'RedHat'
# This is for both Debian and Raspbian
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/ensure_fuse_installed_debian.yml"
when: ansible_os_family == 'Debian'
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/ensure_fuse_installed_archlinux.yml"
when: ansible_os_family == 'Archlinux'

6
roles/custom/matrix-base/tasks/ensure_fuse_installed_archlinux.yml Normal file
View File

@ -0,0 +1,6 @@
---
- name: Ensure fuse installed (Archlinux)
community.general.pacman:
name: fuse3
state: present

6
roles/custom/matrix-base/tasks/ensure_fuse_installed_debian.yml Normal file
View File

@ -0,0 +1,6 @@
---
- name: Ensure fuse installed (Debian/Raspbian)
ansible.builtin.apt:
name: fuse
state: present

6
roles/custom/matrix-base/tasks/ensure_fuse_installed_redhat.yml Normal file
View File

@ -0,0 +1,6 @@
---
- name: Ensure fuse installed (RedHat)
ansible.builtin.yum:
name: fuse
state: present

6
roles/custom/matrix-base/tasks/ensure_openssl_installed.yml Normal file
View File

@ -0,0 +1,6 @@
---
- name: Ensure openssl installed
ansible.builtin.package:
name: openssl
state: present

0
roles/matrix-base/tasks/main.yml → roles/custom/matrix-base/tasks/main.yml
View File

2
roles/matrix-base/tasks/sanity_check.yml → roles/custom/matrix-base/tasks/sanity_check.yml
View File

@ -3,7 +3,7 @@
- name: Fail if invalid homeserver implementation
ansible.builtin.fail:
msg: "You need to set a valid homeserver implementation in `matrix_homeserver_implementation`"
when: "matrix_homeserver_implementation not in ['synapse', 'dendrite']"
when: "matrix_homeserver_implementation not in ['synapse', 'dendrite', 'conduit']"
# We generally support Ansible 2.7.1 and above.
- name: Fail if running on Ansible < 2.7.1

Some files were not shown because too many files have changed in this diff Show More