finallycoffee/matrix-docker-ansible-deploy
finallycoffee/matrix-docker-ansible-deploy
5
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'master' into synapse-s3-sse-c

Browse Source
This commit is contained in:
Cody Wyatt Neiman 2023-01-03 14:31:02 -05:00
commit 4c60b1dabf
No known key found for this signature in database
GPG Key ID: 94475C8B94E4698D
563 changed files with 8377 additions and 9102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.config/ansible-lint.yml
View File

@ -13,4 +13,4 @@ skip_list:
# before finally dumping it to a file.
- template-instead-of-copy
offline: false
offline: true

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

@ -21,4 +21,6 @@ jobs:
- name: Check out
uses: actions/checkout@v3
- name: Run ansible-lint
uses: ansible-community/ansible-lint-action@main
uses: ansible-community/ansible-lint-action@v6.10.2
with:
path: roles/custom

132
CHANGELOG.md
View File

@ -1,3 +1,135 @@
# 2022-11-30
## matrix-postgres-backup has been replaced by the com.devture.ansible.role.postgres_backup external role
Just like we've [replaced Postgres with an external role](#matrix-postgres-has-been-replaced-by-the-comdevtureansiblerolepostgres-external-role) on 2022-11-28, we're now replacing `matrix-postgres-backup` with an external role - [com.devture.ansible.role.postgres_backup](https://github.com/devture/com.devture.ansible.role.postgres_backup).
You'll need to rename your `matrix_postgres_backup`-prefixed variables such that they use a `devture_postgres_backup` prefix.
# 2022-11-28
## matrix-postgres has been replaced by the com.devture.ansible.role.postgres external role
**TLDR**: the tasks that install the integrated Postgres server now live in an external role - [com.devture.ansible.role.postgres](https://github.com/devture/com.devture.ansible.role.postgres). You'll need to run `make roles` to install it, and to also rename your `matrix_postgres`-prefixed variables to use a `devture_postgres` prefix (e.g. `matrix_postgres_connection_password` -> `devture_postgres_connection_password`). All your data will still be there! Some scripts have moved (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`).
The `matrix-postgres` role that has been part of the playbook for a long time has been replaced with the [com.devture.ansible.role.postgres](https://github.com/devture/com.devture.ansible.role.postgres) role. This was done as part of our work to [use external roles for some things](#the-playbook-now-uses-external-roles-for-some-things) for better code re-use and maintainability.
The new role is an upgraded version of the old `matrix-postgres` role with these notable differences:
- it uses different names for its variables (`matrix_postgres` -> `devture_postgres`)
- when [Vacuuming PostgreSQL](docs/maintenance-postgres.md#vacuuming-postgresql), it will vacuum all your databases, not just the Synapse one
You'll need to run `make roles` to install the new role. You would also need to rename your `matrix_postgres`-prefixed variables to use a `devture_postgres` prefix.
Note: the systemd service still remains the same - `matrix-postgres.service`. Your data will still be in `/matrix/postgres`, etc.
Postgres-related scripts will be moved to `/matrix/postgres/bin` (`/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`, etc). Also see [The playbook no longer installs scripts in /usr/local/bin](#the-playbook-no-longer-installs-scripts-in-usrlocalbin).
## The playbook no longer installs scripts to /usr/local/bin
The locations of various scripts installed by the playbook have changed.
The playbook no longer contaminates your `/usr/local/bin` directory.
All scripts installed by the playbook now live in `bin/` directories under `/matrix`. Some examples are below:
- `/usr/local/bin/matrix-remove-all` -> `/matrix/bin/remove-all`
- `/usr/local/bin/matrix-postgres-cli` -> `/matrix/postgres/bin/cli`
- `/usr/local/bin/matrix-ssl-lets-encrypt-certificates-renew` -> `/matrix/ssl/bin/lets-encrypt-certificates-renew`
- `/usr/local/bin/matrix-synapse-register-user` -> `/matrix/synapse/bin/register-user`
# 2022-11-25
## 2x-5x performance improvements in playbook runtime
**TLDR**: the playbook is 2x faster for running `--tags=setup-all` (and various other tags). It also has new `--tags=install-*` tags (like `--tags=install-all`), which skip uninstallation tasks and bring an additional 2.5x speedup. In total, the playbook can maintain your server 5 times faster.
Our [etke.cc managed Matrix hosting service](https://etke.cc) runs maintenance against hundreds of servers, so the playbook being fast means a lot.
The [etke.cc Ansible playbook](https://gitlab.com/etke.cc/ansible) (which is an extension of this one) is growing to support more and more services (besides just Matrix), so the Matrix playbook being leaner prevents runtimes from becoming too slow and improves the customer experience.
Even when running `ansible-playbook` manually (as most of us here do), it's beneficial not to waste time and CPU resources.
Recently, a few large optimizations have been done to this playbook and its external roles (see [The playbook now uses external roles for some things](#the-playbook-now-uses-external-roles-for-some-things) and don't forget to run `make roles`):
1. Replacing Ansible `import_tasks` calls with `include_tasks`, which decreased runtime in half. Using `import_tasks` is slower and causes Ansible to go through and skip way too many tasks (tasks which could have been skipped altogether by not having Ansible include them in the first place). On an experimental VM, **deployment time was decreased from ~530 seconds to ~250 seconds**.
2. Introducing new `install-*` tags (`install-all` and `install-COMPONENT`, e.g. `install-synapse`, `install-bot-postmoogle`), which only run Ansible tasks pertaining to installation, while skipping uninstallation tasks. In most cases, people are maintaining the same setup or they're *adding* new components. Removing components is rare. Running thousands of uninstallation tasks each time is wasteful. On an experimental VM, **deployment time was decreased from ~250 seconds (`--tags=setup-all`) to ~100 seconds (`--tags=install-all`)**.
You can still use `--tags=setup-all`. In fact, that's the best way to ensure your server is reconciled with the `vars.yml` configuration.
If you know you haven't uninstalled any services since the last time you ran the playbook, you could run `--tags=install-all` instead and benefit from quicker runtimes.
It should be noted that a service may become "eligible for uninstallation" even if your `vars.yml` file remains the same. In rare cases, we toggle services from being auto-installed to being optional, like we did on the 17th of March 2022 when we made [ma1sd not get installed by default](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md#compatibility-break-ma1sd-identity-server-no-longer-installed-by-default). In such rare cases, you'd also need to run `--tags=setup-all`.
# 2022-11-22
# Automatic `matrix_architecture` determination
From now on, the playbook automatically determines your server's architecture and sets the `matrix_architecture` variable accordingly.
You no longer need to set this variable manually in your `vars.yml` file.
# Docker and the Docker SDK for Python are now installed via external roles
We're continuing our effort to make [the playbook use external roles for some things](#the-playbook-now-uses-external-roles-for-some-things), so as to avoid doing everything ourselves and to facilitate code re-use.
Docker will now be installed on the server via the [geerlingguy.docker](https://github.com/geerlingguy/ansible-role-docker) Ansible role.
If you'd like to manage the Docker installation yourself, you can disable the playbook's installation of Docker by setting `matrix_playbook_docker_installation_enabled: false`.
The Docker SDK for Python (named `docker-python`, `python-docker`, etc. on the different platforms) is now also installed by another role ([com.devture.ansible.role.docker_sdk_for_python](https://github.com/devture/com.devture.ansible.role.docker_sdk_for_python)). To disable this role and install the necessary tools yourself, use `devture_docker_sdk_for_python_installation_enabled: false`.
If you're hitting issues with Docker installation or Docker SDK for Python installation, consider reporting bugs or contributing to these other projects.
These additional roles are downloaded into the playbook directory (to `roles/galaxy`) via an `ansible-galaxy ..` command. `make roles` is an easy shortcut for invoking the `ansible-galaxy` command to download these roles.
# 2022-11-20
## (Backward Compatibility Break) Changing how reverse-proxying to Synapse works - now via a `matrix-synapse-reverse-proxy-companion` service
**TLDR**: There's now a `matrix-synapse-reverse-proxy-companion` nginx service, which helps with reverse-proxying to Synapse and its various worker processes (if workers are enabled), so that `matrix-nginx-proxy` can be relieved of this role. `matrix-nginx-proxy` still remains as the public SSL-terminating reverse-proxy in the playbook. `matrix-synapse-reverse-proxy-companion` is just one more reverse-proxy thrown into the mix for convenience. People with a more custom reverse-proxying configuration may be affected - see [Webserver configuration](#webserver-configuration) below.
### Background
Previously, `matrix-nginx-proxy` forwarded requests to Synapse directly. When Synapse is running in worker mode, the reverse-proxying configuration is more complicated (different requests need to go to different Synapse worker processes). `matrix-nginx-proxy` had configuration for sending each URL endpoint to the correct Synapse worker responsible for handling it. However, sometimes people like to disable `matrix-nginx-proxy` (for whatever reason) as detailed in [Using your own webserver, instead of this playbook's nginx proxy](docs/configuring-playbook-own-webserver.md).
Because `matrix-nginx-proxy` was so central to request forwarding, when it was disabled and Synapse was running with workers enabled, there was nothing which could forward requests to the correct place anymore.. which caused [problems such as this one affecting Dimension](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2090).
### Solution
From now on, `matrix-nginx-proxy` is relieved of its function of reverse-proxying to Synapse and its various worker processes.
This role is now handled by the new `matrix-synapse-reverse-proxy-companion` nginx service and works even if `matrix-nginx-proxy` is disabled.
The purpose of the new `matrix-synapse-reverse-proxy-companion` service is to:
- serve as a companion to Synapse and know how to reverse-proxy to Synapse correctly (no matter if workers are enabled or not)
- provide a unified container address for reaching Synapse (no matter if workers are enabled or not)
- `matrix-synapse-reverse-proxy-companion:8008` for Synapse Client-Server API traffic
- `matrix-synapse-reverse-proxy-companion:8048` for Synapse Server-Server (Federation) API traffic
- simplify `matrix-nginx-proxy` configuration - it now only needs to send requests to `matrix-synapse-reverse-proxy-companion` or `matrix-dendrite`, etc., without having to worry about workers
- allow reverse-proxying to Synapse, even if `matrix-nginx-proxy` is disabled
`matrix-nginx-proxy` still remains as the public SSL-terminating reverse-proxy in the playbook. All traffic goes through it before reaching any of the services.
It's just that now the Synapse traffic is routed through `matrix-synapse-reverse-proxy-companion` like this:
(`matrix-nginx-proxy` -> `matrix-synapse-reverse-proxy-companion` -> (`matrix-synapse` or some Synapse worker)).
Various services (like Dimension, etc.) still talk to Synapse via `matrix-nginx-proxy` (e.g. `http://matrix-nginx-proxy:12080`) preferentially. They only talk to Synapse via the reverse-proxy companion (e.g. `http://matrix-synapse-reverse-proxy-companion:8008`) if `matrix-nginx-proxy` is disabled. Services should not be talking to Synapse (e.g. `https://matrix-synapse:8008` directly anymore), because when workers are enabled, that's the Synapse `master` process and may not be serving all URL endpoints needed by the service.
### Webserver configuration
- if you're using `matrix-nginx-proxy` (`matrix_nginx_proxy_enabled: true`, which is the default for the playbook), you don't need to do anything
- if you're using your own `nginx` webserver running on the server, you shouldn't be affected. The `/matrix/nginx/conf.d` configuration and exposed ports that you're relying on will automatically be updated in a way that should work
- if you're using another local webserver (e.g. Apache, etc.) and haven't changed any ports (`matrix_*_host_bind_port` definitions), you shouldn't be affected. You're likely sending Matrix traffic to `127.0.0.1:8008` and `127.0.0.1:8048`. These ports (`8008` and `8048`) will still be exposed on `127.0.0.1` by default - just not by the `matrix-synapse` container from now on, but by the `matrix-synapse-reverse-proxy-companion` container instead
- if you've been exposing `matrix-synapse` ports (`matrix_synapse_container_client_api_host_bind_port`, etc.) manually, you should consider exposing `matrix-synapse-reverse-proxy-companion` ports instead
- if you're running Traefik and reverse-proxying directly to the `matrix-synapse` container, you should start reverse-proxying to the `matrix-synapse-reverse-proxy-companion` container instead. See [our updated Traefik example configuration](docs/configuring-playbook-own-webserver.md#sample-configuration-for-running-behind-traefik-20). Note: we now recommend calling the federation entry point `federation` (instead of `synapse`) and reverse-proxying the federation traffic via `matrix-nginx-proxy`, instead of sending it directly to Synapse (or `matrix-synapse-reverse-proxy-companion`). This makes the configuration simpler.
# 2022-11-05
## (Backward Compatibility Break) A new default standalone mode for Etherpad

2
Makefile
View File

@ -8,4 +8,4 @@ roles: ## Pull roles
ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force
lint: ## Runs ansible-lint against all roles in the playbook
ansible-lint
ansible-lint roles/custom

263
README.md
View File

@ -15,139 +15,146 @@ We run all services in [Docker](https://www.docker.com/) containers (see [the co
## Supported services
Using this playbook, you can get the following services configured on your server:
Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
- (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/) (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.
- (optional, default) a [coturn](https://github.com/coturn/coturn) STUN/TURN server for WebRTC audio/video calls
- (optional, default) free [Let's Encrypt](https://letsencrypt.org/) SSL certificate, which secures the connection to the Synapse server and the Element web UI
- (optional, default) an [Element](https://app.element.io/) ([formerly Riot](https://element.io/previously-riot)) web UI, which is configured to connect to your own Synapse server by default
- (optional) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
- (optional, default) an [Exim](https://www.exim.org/) mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server)
- (optional, default) an [nginx](http://nginx.org/) web server, listening on ports 80 and 443 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md)
- (optional, advanced) the [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) REST authentication password provider module
- (optional, advanced) the [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) password provider module
- (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/)
- (optional) the [mautrix-facebook](https://github.com/mautrix/facebook) bridge for bridging your Matrix server to [Facebook](https://facebook.com/)
- (optional) the [mautrix-twitter](https://github.com/mautrix/twitter) bridge for bridging your Matrix server to [Twitter](https://twitter.com/)
- (optional) the [mautrix-hangouts](https://github.com/mautrix/hangouts) bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts)
- (optional) the [mautrix-googlechat](https://github.com/mautrix/googlechat) bridge for bridging your Matrix server to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat)
- (optional) the [mautrix-instagram](https://github.com/mautrix/instagram) bridge for bridging your Matrix server to [Instagram](https://instagram.com/)
- (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://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)
- (optional) the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge for bridging your Matrix server to [Discord](https://discordapp.com/)
- (optional) the [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) bridge for bridging your Matrix server to [Slack](https://slack.com/)
- (optional) the [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.)
- (optional) the [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) bridge for bridging Matrix to generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular
- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
- (optional) the [Heisenbridge](https://github.com/hifi/heisenbridge) for bridging your Matrix server to IRC bouncer-style - see [docs/configuring-playbook-bridge-heisenbridge.md](docs/configuring-playbook-bridge-heisenbridge.md) for setup documentation
- (optional) the [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-go-skype-bridge.md](docs/configuring-playbook-bridge-go-skype-bridge.md) for setup documentation
- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
- (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
- (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/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
- (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
- (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
- (optional) [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), a web UI tool for administrating users and rooms on your Matrix server - see [docs/configuring-playbook-synapse-admin.md](docs/configuring-playbook-synapse-admin.md) for setup documentation
- (optional) [matrix-registration](https://github.com/ZerataX/matrix-registration), a simple python application to have a token based matrix registration - see [docs/configuring-playbook-matrix-registration.md](docs/configuring-playbook-matrix-registration.md) for setup documentation
- (optional) the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI - see [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) for setup documentation
- (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation
- (optional) the [ntfy](https://ntfy.sh) push notifications server - see [docs/configuring-playbook-ntfy.md](docs/configuring-playbook-ntfy.md) for setup documentation
- (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation
- (optional) the [Cinny](https://github.com/ajbura/cinny) web client - see [docs/configuring-playbook-client-cinny.md](docs/configuring-playbook-client-cinny.md) for setup documentation
- (optional) the [Borg](https://borgbackup.org) backup - see [docs/configuring-playbook-backup-borg.md](docs/configuring-playbook-backup-borg.md) for setup documentation
- (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.
**Note**: the list below is exhaustive. It includes optional or even some advanced components that you will most likely not need.
Sticking with the defaults (which install a subset of the above components) is the best choice, especially for a new installation.
You can always re-run the playbook later to add or remove components.
### Homeserver
The homeserver is the backbone of your matrix system. Choose one from the following list.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [Synapse](https://github.com/matrix-org/synapse) | ✓ | Storing your data and managing your presence in the [Matrix](http://matrix.org/) network | [Link](docs/configuring-playbook-synapse.md) |
| [Conduit](https://conduit.rs) | x | 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 | [Link](docs/configuring-playbook-conduit.md) |
| [Dendrite](https://github.com/matrix-org/dendrite) | x | 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. | [Link](docs/configuring-playbook-dendrite.md) |
### Clients
Web clients for matrix that you can host on your own domains.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
[Element](https://app.element.io/) | ✓ | Web UI, which is configured to connect to your own Synapse server by default | [Link](docs/configuring-playbook-client-element.md) |
| [Hydrogen](https://github.com/vector-im/hydrogen-web) | x | Web client | [Link](docs/configuring-playbook-client-hydrogen.md) |
| [Cinny](https://github.com/ajbura/cinny) | x | Web client | [Link](docs/configuring-playbook-client-cinny.md) |
### Server Components
Services that run on the server to make the various parts of your installation work.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [PostgreSQL](https://www.postgresql.org/)| ✓ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
| [Coturn](https://github.com/coturn/coturn) | ✓ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
| [nginx](http://nginx.org/) | ✓ | Web server, listening on ports 80 and 443 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md) | [Link](docs/configuring-playbook-nginx.md) |
| [Let's Encrypt](https://letsencrypt.org/) | ✓ | Free SSL certificate, which secures the connection to the Synapse server and the Element web UI | [Link](docs/configuring-playbook-ssl-certificates.md) |
| [ma1sd](https://github.com/ma1uta/ma1sd) | x | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
| [Exim](https://www.exim.org/) | ✓ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | - |
| [Dimension](https://github.com/turt2live/matrix-dimension) | x | An open source integrations manager for matrix clients | [Link](docs/configuring-playbook-dimension.md) |
| [Sygnal](https://github.com/matrix-org/sygnal) | x | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
| [ntfy](https://ntfy.sh) | x | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
### Authentication
Extend and modify how users are authenticated on your homeserver.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) (advanced) | x | REST authentication password provider module | [Link](docs/configuring-playbook-rest-auth.md) |
|[matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) (advanced) | x | Password provider module | [Link](docs/configuring-playbook-shared-secret-auth.md) |
| [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) (advanced) | x | LDAP Auth password provider module | [Link](configuring-playbook-ldap-auth.md) |
| [matrix-ldap-registration-proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy) (advanced) | x | A proxy that handles Matrix registration requests and forwards them to LDAP. | [Link](docs/configuring-playbook-matrix-ldap-registration-proxy.md) |
| [matrix-registration](https://github.com/ZerataX/matrix-registration) | x | A simple python application to have a token based matrix registration | [Link](docs/configuring-playbook-matrix-registration.md) |
### File Storage
Use alternative file storage to the default `media_store` folder.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [Goofys](https://github.com/kahing/goofys) | x | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3-goofys.md) |
| [synapse-s3-storage-provider](https://github.com/matrix-org/synapse-s3-storage-provider) | x | [Amazon S3](https://aws.amazon.com/s3/) (or other S3-compatible object store) storage for Synapse's content repository (`media_store`) files | [Link](docs/configuring-playbook-s3.md) |
### Bridges
Bridges can be used to connect your matrix installation with third-party communication networks.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
[mautrix-discord](https://github.com/mautrix/discord) | x | Bridge for bridging your Matrix server to [Discord](https://discord.com/) | [Link](docs/configuring-playbook-bridge-mautrix-discord.md) |
| [mautrix-telegram](https://github.com/mautrix/telegram) | x | Bridge for bridging your Matrix server to [Telegram](https://telegram.org/) | [Link](docs/configuring-playbook-bridge-mautrix-telegram.md) |
| [mautrix-whatsapp](https://github.com/mautrix/whatsapp) | x | Bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/) | [Link](docs/configuring-playbook-bridge-mautrix-whatsapp.md) |
| [mautrix-facebook](https://github.com/mautrix/facebook) | x | Bridge for bridging your Matrix server to [Facebook](https://facebook.com/) | [Link](docs/configuring-playbook-bridge-mautrix-facebook.md) |
| [mautrix-twitter](https://github.com/mautrix/twitter) | x | Bridge for bridging your Matrix server to [Twitter](https://twitter.com/) | [Link](docs/configuring-playbook-bridge-mautrix-twitter.md) |
| [mautrix-hangouts](https://github.com/mautrix/hangouts) | x | Bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts) | [Link](docs/configuring-playbook-bridge-mautrix-hangouts.md) |
| [mautrix-googlechat](https://github.com/mautrix/googlechat) | x | Bridge for bridging your Matrix server to [Google Chat](https://en.wikipedia.org/wiki/Google_Chat) | [Link](docs/configuring-playbook-bridge-mautrix-googlechat.md) |
| [mautrix-instagram](https://github.com/mautrix/instagram) | x | Bridge for bridging your Matrix server to [Instagram](https://instagram.com/) | [Link](docs/configuring-playbook-bridge-mautrix-instagram.md) |
| [mautrix-signal](https://github.com/mautrix/signal) | x | Bridge for bridging your Matrix server to [Signal](https://www.signal.org/) | [Link](docs/configuring-playbook-bridge-mautrix-signal.md) |
| [beeper-linkedin](https://github.com/beeper/linkedin) | x | Bridge for bridging your Matrix server to [LinkedIn](https://www.linkedin.com/) | [Link](docs/configuring-playbook-bridge-beeper-linkedin.md) |
| [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) | x | Bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-appservice-irc.md) |
| [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) | x | Bridge for bridging your Matrix server to [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-appservice-discord.md) |
| [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) | x | Bridge for bridging your Matrix server to [Slack](https://slack.com/) | [Link](docs/configuring-playbook-bridge-appservice-slack.md) |
| [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) | x | Bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.) | [Link](docs/configuring-playbook-bridge-appservice-webhooks.md) |
| [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) | x | Bridge for bridging Matrix to generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | [Link](docs/configuring-playbook-bridge-hookshot.md) |
| [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | x | Bridge for bridging your Matrix server to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) |
| [Heisenbridge](https://github.com/hifi/heisenbridge) | x | Bridge for bridging your Matrix server to IRC bouncer-style | [Link](docs/configuring-playbook-bridge-heisenbridge.md) |
| [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) | x | Bridge for bridging your Matrix server to [Skype](https://www.skype.com) | [Link](docs/configuring-playbook-bridge-go-skype-bridge.md) |
| [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) | x | Bridge for bridging your Matrix server to [Slack](https://slack.com) | [Link](docs/configuring-playbook-bridge-mx-puppet-slack.md) |
| [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) | x | Bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-instagram.md) |
| [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) | x | Bridge for Twitter-DMs ([Twitter](https://twitter.com/)) | [Link](docs/configuring-playbook-bridge-mx-puppet-twitter.md) |
| [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) | x | Bridge for [Discord](https://discordapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-discord.md) |
| [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | x | Bridge for [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) |
| [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) | x | Bridge for [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) |
| [Email2Matrix](https://github.com/devture/email2matrix) | x | Bridge for relaying email messages to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
### Bots
Bots provide various additional functionality to your installation.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) | x | Bot for scheduling one-off & recurring reminders and alarms | [Link](docs/configuring-playbook-bot-matrix-reminder-bot.md) |
| [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) | x | Bot for invitations by creating and managing registration tokens | [Link](docs/configuring-playbook-bot-matrix-registration-bot.md) |
| [maubot](https://github.com/maubot/maubot) | x | A plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) |
| [honoroit](https://gitlab.com/etke.cc/honoroit) | x | A helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) |
| [Postmoogle](https://gitlab.com/etke.cc/postmoogle) | x | Email to matrix bot | [Link](docs/configuring-playbook-bot-postmoogle.md) |
| [Go-NEB](https://github.com/matrix-org/go-neb) | x | A multi functional bot written in Go | [Link](docs/configuring-playbook-bot-go-neb.md) |
| [Mjolnir](https://github.com/matrix-org/mjolnir) | x | A moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) |
| [Buscarron](https://gitlab.com/etke.cc/buscarron) | x | Web forms (HTTP POST) to matrix | [Link](docs/configuring-playbook-bot-buscarron.md) |
### Administration
Services that help you in administrating and monitoring your matrix installation.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) | x | A web UI tool for administrating users and rooms on your Matrix server | [Link](docs/configuring-playbook-synapse-admin.md) |
| Metrics and Graphs | x | Consists of the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI | [Link](docs/configuring-playbook-prometheus-grafana.md) |
| [Borg](https://borgbackup.org) | x | Backups | [Link](docs/configuring-playbook-backup-borg.md) |
### Misc
Various services that don't fit any other category.
| Name | Default? | Description | Documentation |
| ---- | -------- | ----------- | ------------- |
| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | x | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
| [Matrix Corporal](https://github.com/devture/matrix-corporal) (advanced) | x | Reconciliator and gateway for a managed Matrix server | [Link](docs/configuring-playbook-matrix-corporal.md) |
| [Etherpad](https://etherpad.org) | x | An open source collaborative text editor | [Link](docs/configuring-playbook-etherpad.md) |
| [Jitsi](https://jitsi.org/) | x | An open source video-conferencing platform | [Link](docs/configuring-playbook-jitsi.md) |
| [Cactus Comments](https://cactus.chat) | x | A federated comment system built on matrix | [Link](docs/configuring-playbook-cactus-comments.md) |
## Installation
To configure and install Matrix on your own server, follow the [README in the docs/ directory](docs/README.md).

20
docs/alternative-architectures.md
View File

@ -1,26 +1,18 @@
# Alternative architectures
As stated in the [Prerequisites](prerequisites.md), currently only `x86_64` is fully supported. However, it is possible to set the target architecture, and some tools can be built on the host or other measures can be used.
As stated in the [Prerequisites](prerequisites.md), currently only `amd64` (`x86_64`) is fully supported.
To that end add the following variable to your `vars.yml` file (see [Configuring playbook](configuring-playbook.md)):
The playbook automatically determines the target server's architecture (the `matrix_architecture` variable) to be one of the following:
```yaml
matrix_architecture: <your-matrix-server-architecture>
```
Currently supported architectures are the following:
- `amd64` (the default)
- `arm64`
- `amd64` (`x86_64`)
- `arm32`
- `arm64`
so for the Raspberry Pi, the following should be in your `vars.yml` file:
Some tools and container images can be built on the host or other measures can be used to install on that architecture.
```yaml
matrix_architecture: "arm32"
```
## Implementation details
For `amd64`, prebuilt container images (see the [container images we use](container-images.md)) are used for all components (except [Hydrogen](configuring-playbook-client-hydrogen.md), which goes through self-building).
For other architectures, components which have a prebuilt image make use of it. If the component is not available for the specific architecture, [self-building](self-building.md) will be used. Not all components support self-building though, so your mileage may vary.
For other architecture (`arm64`, `arm32`), components which have a prebuilt image make use of it. If the component is not available for the specific architecture, [self-building](self-building.md) will be used. Not all components support self-building though, so your mileage may vary.

21
docs/ansible.md
View File

@ -9,19 +9,14 @@ If your local computer cannot run Ansible, you can also run Ansible on some serv
## Supported Ansible versions
Ansible 2.7.1 or newer is required ([last discussion about Ansible versions](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/743)).
Note: Ubuntu 20.04 ships with Ansible 2.9.6 which is a buggy version (see this [bug](https://bugs.launchpad.net/ubuntu/+source/ansible/+bug/1880359)), which can't be used in combination with a host running new systemd (more details in [#517](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/517), [#669](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/669)). If this problem affects you, you can: avoid running Ubuntu 20.04 on your host; run Ansible from another machine targeting your host; or try to upgrade to a newer Ansible version (see below).
## Checking your Ansible version
In most cases, you won't need to worry about the Ansible version.
The playbook will try to detect it and tell you if you're on an unsupported version.
To manually check which version of Ansible you're on, run: `ansible --version`.
If you're on an old version of Ansible, you should [upgrade Ansible to a newer version](#upgrading-ansible) or [use Ansible via Docker](#using-ansible-via-docker).
For the **best experience**, we recommend getting the **latest version of Ansible available**.
We're not sure what's the minimum version of Ansible that can run this playbook successfully.
The lowest version that we've confirmed (on 2022-11-26) to be working fine is: `ansible-core` (`2.11.7`) combined with `ansible` (`4.10.0`).
If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
## Upgrading Ansible
@ -53,7 +48,7 @@ You can either [run Ansible in a container on the Matrix server itself](#running
To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation.
Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
- you **either** need to install Docker manually first. Follow [the upstream instructions](https://docs.docker.com/engine/install/) for your distribution and consider setting `matrix_docker_installation_enabled: false` in your `vars.yml` file, to prevent the playbook from installing Docker
- you **either** need to install Docker manually first. Follow [the upstream instructions](https://docs.docker.com/engine/install/) for your distribution and consider setting `matrix_playbook_docker_installation_enabled: false` in your `vars.yml` file, to prevent the playbook from installing Docker
- **or** you need to run the playbook in another way (e.g. [Running Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server)) at least the first time around
Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/..`, etc.), as described in [configuring the playbook](configuring-playbook.md).
@ -70,7 +65,7 @@ docker run -it --rm \
-w /work \
-v `pwd`:/work \
--entrypoint=/bin/sh \
docker.io/devture/ansible:2.13.6-r0
docker.io/devture/ansible:2.13.6-r0-1
```
Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container.

35
docs/configuring-captcha.md
View File

@ -2,9 +2,11 @@
# Overview
Captcha can be enabled for this home server. This file explains how to do that.
The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google.
The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.
## Getting keys
## ReCaptcha
### Getting keys
Requires a site/secret key pair from:
@ -12,12 +14,39 @@ Requires a site/secret key pair from:
Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option
## Setting ReCaptcha Keys
### Setting ReCaptcha keys
Once registered as above, set the following values:
```yaml
# for Synapse
matrix_synapse_enable_registration_captcha: true
matrix_synapse_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_synapse_recaptcha_private_key: 'YOUR_SECRET_KEY'
# for Dendrite
matrix_dendrite_client_api_enable_registration_captcha: true
matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
```
## hCaptcha
### Getting keys
Requires a site/secret key pair from:
<https://dashboard.hcaptcha.com/sites/new>
### Setting hCaptcha keys
```yaml
matrix_dendrite_client_api_enable_registration_captcha: true
matrix_dendrite_client_api_recaptcha_public_key: 'YOUR_SITE_KEY'
matrix_dendrite_client_api_recaptcha_private_key: 'YOUR_SECRET_KEY'
matrix_dendrite_client_api_recaptcha_siteverify_api: 'https://hcaptcha.com/siteverify'
matrix_dendrite_client_api_recaptcha_api_js_url: 'https://js.hcaptcha.com/1/api.js'
matrix_dendrite_client_api_recaptcha_form_field: 'h-captcha-response'
matrix_dendrite_client_api_recaptcha_sitekey_class: 'h-captcha'
```

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

@ -40,7 +40,7 @@ Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to
```yaml
matrix_backup_borg_enabled: true
matrix_backup_borg_location_repositories:
- USER@HOST:REPO
- ssh://USER@HOST/./REPO
matrix_backup_borg_storage_encryption_passphrase: "PASSPHRASE"
matrix_backup_borg_ssh_key_private: |
-----BEGIN OPENSSH PRIVATE KEY-----

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

@ -54,7 +54,7 @@ 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/custom/matrix-bridge-hookshot/tasks/init.yml).
See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/custom/matrix-bridge-hookshot/tasks/inject_into_nginx_proxy.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/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
@ -93,4 +93,4 @@ To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This
### Collision with matrix-appservice-webhooks
If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_user_id_prefix: '_webhooks_'`).
If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_userIdPrefix: '_webhooks_'`).

32
docs/configuring-playbook-dendrite.md Normal file
View File

@ -0,0 +1,32 @@
# Configuring Dendrite (optional)
By default, this playbook configures the [Synapse](https://github.com/matrix-org/synapse) Matrix server, but you can also use [Dendrite](https://github.com/matrix-org/dendrite).
**NOTES**:
- **You can't switch an existing Matrix server's implementation** (e.g. Synapse -> Dendrite). 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
The playbook provided settings for Dendrite are defined in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml) and they ultimately end up in the generated `/matrix/dendrite/config/dendrite.yaml` file (on the server). This file is generated from the [`roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.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.
Alternatively, **if there is no pre-defined variable** for a Dendrite setting you wish to change:
- 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 Dendrite's various settings that rarely get used.
- or, you can **extend and override the default configuration** ([`dendrite.yaml.j2`](../roles/custom/matrix-dendrite/templates/dendrite/dendrite.yaml.j2)) by making use of the `matrix_dendrite_configuration_extension_yaml` variable. You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
## Installation
To use Dendrite, you **generally** need the following additional `vars.yml` configuration:
```yaml
matrix_homeserver_implementation: dendrite
```

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

@ -70,7 +70,7 @@ matrix_email2matrix_matrix_mappings:
SkipMarkdown: true
```
You can also set `MatrixHomeserverUrl` to `http://matrix-synapse:8008`, instead of the public `https://matrix.DOMAIN`.
You can also set `MatrixHomeserverUrl` to `http://matrix-synapse-reverse-proxy-companion:8008`, instead of the public `https://matrix.DOMAIN`.
However, that's more likely to break in the future if you switch to another server implementation than Synapse.
Re-run the playbook (`--tags=setup-email2matrix,start`) and try sending an email to `my-mailbox@matrix.DOMAIN`.

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

@ -41,6 +41,13 @@ If you want to manage and remove old unused pads from Etherpad, you will first n
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.
## How to use Etherpad widgets without an Integration Manager (like Dimension)
This is how it works in Element, it might work quite similar with other clients:
To integrate a standalone etherpad in a room, create your pad by visiting `https://etherpad.DOMAIN`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section.
## 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.

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

@ -10,7 +10,7 @@ If you'd like to use an external PostgreSQL server that you manage, you can edit
If you'd like to use an external Postgres server, use a custom `vars.yml` configuration like this:
```yaml
matrix_postgres_enabled: false
devture_postgres_enabled: false
# Rewire Synapse to use your external Postgres server
matrix_synapse_database_host: "your-postgres-server-hostname"

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

@ -46,6 +46,9 @@ matrix_synapse_federation_port_enabled: false
# This removes the `8448` virtual host from the matrix-nginx-proxy reverse-proxy server.
matrix_nginx_proxy_proxy_matrix_federation_api_enabled: false
# This stops the federation port on the synapse-reverse-proxy-companion side (normally `matrix-synapse-reverse-proxy-companion:8048` on the container network).
matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
```
## Changing the federation port from 8448 to a different port to use a CDN that only accepts 443/80 ports

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

@ -127,6 +127,80 @@ Read how it works [here](https://github.com/jitsi/jitsi-videobridge/blob/master/
You may want to **limit the maximum video resolution**, to save up resources on both server and clients.
## (Optional) Specify a Max number of participants on a Jitsi conference
The playbook allows a user to set a max number of participants allowed to join a Jitsi conference. By default there is no limit.
In order to set the max number of participants add the following variable to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
```
matrix_prosody_jitsi_max_participants: <INTEGER OF MAX PARTICPANTS>
```
## (Optional) Additional JVBs
By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)) is deployed on the same host as the Matrix server. To allow more video-conferences to happen at the same time, you may need to provision additional JVB services on other hosts.
There is an ansible playbook that can be run with the following tag:
` ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
```
[jitsi_jvb_servers]
<your jvb hosts> ansible_host=<ip address of the jvb host>
```
Each JVB will require a server id to be set so that it can be uniquely identified and this allows Jitsi to keep track of which conferences are on which JVB.
The server id is set with the variable `matrix_jitsi_jvb_server_id` which ends up as the JVB_WS_SERVER_ID environment variables in the JVB docker container.
This variable can be set via the host file, a parameter to the ansible command or in the `vars.yaml` for the host which will have the additional JVB. For example:
``` yaml
matrix_jitsi_jvb_server_id: 'jvb-2'
```
``` INI
[jitsi_jvb_servers]
jvb-2.example.com ansible_host=192.168.0.2 matrix_jitsi_jvb_server_id=jvb-2
jvb-3.example.com ansible_host=192.168.0.3 matrix_jitsi_jvb_server_id=jvb-2
```
Note that the server id `jvb-1` is reserved for the JVB instance running on the Matrix host and therefore should not be used as the id of an additional jvb host.
The additional JVB will also need to expose the colibri web socket port and this can be done with the following variable:
```yaml
matrix_jitsi_jvb_container_colibri_ws_host_bind_port: 9090
```
The JVB will also need to know where the prosody xmpp server is located, similar to the server id this can be set in the vars for the JVB by using the variable
`matrix_jitsi_xmpp_server`. The Jitsi prosody container is deployed on the matrix server by default so the value can be set to the matrix domain. For example:
```yaml
matrix_jitsi_xmpp_server: "{{ matrix_domain }}"
```
However, it can also be set the ip address of the matrix server. This can be useful if you wish to use a private ip. For example:
```yaml
matrix_jitsi_xmpp_server: "192.168.0.1"
```
The nginx configuration will also need to be updated in order to deal with the additional JVB servers. This is achieved via its own configuration variable
`matrix_nginx_proxy_proxy_jitsi_additional_jvbs`, which contains a dictionary of server ids to ip addresses.
For example,
``` yaml
matrix_nginx_proxy_proxy_jitsi_additional_jvbs:
jvb-2: 192.168.0.2
jvb-3: 192.168.0.3
```
Applied together this will allow you to provision extra JVB instances which will register themselves with the prosody service and be available for jicofo
to route conferences too.
## Apply changes

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

@ -4,6 +4,8 @@ The playbook can install and configure [matrix-registration](https://github.com/
**WARNING**: this is a poorly maintained and buggy project. It's better to avoid using it.
**WARNING**: this is not related to [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md)
> matrix-registration is a simple python application to have a token based matrix registration.
Use matrix-registration to **create unique registration links**, which people can use to register on your Matrix server. It allows you to **keep your server's registration closed (private)**, but still allow certain people (these having a special link) to register a user account.

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

@ -6,9 +6,6 @@ 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)
@ -19,7 +16,12 @@ There are **2 ways you can go about it**, if you'd like to use your own webserve
## Method 1: Disabling the integrated nginx reverse-proxy webserver
This method is about completely disabling the integrated nginx reverse-proxy webserver and replicating its behavior using another webserver.
For an alternative, make sure to check Method #2 as well.
If that other webserver is `nginx`, you'd be able to include configuration files generated by the playbook into your `nginx` webserver.
If you'd like to use another webserver (not `nginx`), you'd need to do things manually. We have examples for other webservers below.
For an alternative (which keeps `matrix-nginx-proxy` around and connects your other reverse-proxy with it), make sure to check Method #2.
### Preparation
@ -40,8 +42,8 @@ No matter which external webserver you decide to go with, you'll need to:
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_synapse_reverse_proxy_companion_container_client_api_host_bind_port: '0.0.0.0:8008'
matrix_synapse_reverse_proxy_companion_container_federation_api_host_bind_port: '0.0.0.0:8048'
matrix_client_element_container_http_host_bind_port: "0.0.0.0:8765"
```
@ -172,31 +174,26 @@ matrix_nginx_proxy_container_extra_arguments:
# The Nginx proxy container will receive traffic from these subdomains
- '--label "traefik.http.routers.matrix-nginx-proxy.rule=Host(`{{ matrix_server_fqn_matrix }}`,`{{ matrix_server_fqn_element }}`,`{{ matrix_server_fqn_dimension }}`,`{{ matrix_server_fqn_jitsi }}`)"'
# (The 'web-secure' entrypoint must bind to port 443 in Traefik config)
- '--label "traefik.http.routers.matrix-nginx-proxy.entrypoints=web-secure"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-nginx-proxy.tls.certResolver=default"'
# Traefik requires that we declare which service this router is using
- '--label "traefik.http.routers.matrix-nginx-proxy.service=matrix-nginx-proxy"'
# The Nginx proxy container uses port 8080 internally
- '--label "traefik.http.services.matrix-nginx-proxy.loadbalancer.server.port=8080"'
matrix_synapse_container_extra_arguments:
# May be unnecessary depending on Traefik config, but can't hurt
- '--label "traefik.enable=true"'
# The Synapse container will receive traffic from this subdomain
- '--label "traefik.http.routers.matrix-synapse.rule=Host(`{{ matrix_server_fqn_matrix }}`)"'
# (The 'synapse' entrypoint must bind to port 8448 in Traefik config)
- '--label "traefik.http.routers.matrix-synapse.entrypoints=synapse"'
# Federation
- '--label "traefik.http.routers.matrix-nginx-proxy-federation.rule=Host(`{{ matrix_server_fqn_matrix }}`)"'
# (The 'federation' entrypoint must bind to port 8448 in Traefik config)
- '--label "traefik.http.routers.matrix-nginx-proxy-federation.entrypoints=federation"'
# (The 'default' certificate resolver must be defined in Traefik config)
- '--label "traefik.http.routers.matrix-synapse.tls.certResolver=default"'
# The Synapse container uses port 8048 internally
- '--label "traefik.http.services.matrix-synapse.loadbalancer.server.port=8048"'
- '--label "traefik.http.routers.matrix-nginx-proxy-federation.tls.certResolver=default"'
# Traefik requires that we declare which service this router is using
- '--label "traefik.http.routers.matrix-nginx-proxy-federation.service=matrix-nginx-proxy-federation"'
# The Nginx proxy container uses port `matrix_nginx_proxy_proxy_matrix_federation_port (8448) internally
- '--label "traefik.http.services.matrix-nginx-proxy-federation.loadbalancer.server.port={{ matrix_nginx_proxy_proxy_matrix_federation_port }}"'
- '--label "traefik.http.services.matrix-nginx-proxy-federation.loadbalancer.server.scheme={{ "https" if matrix_nginx_proxy_https_enabled else "http" }}"'
```
This method uses labels attached to the Nginx and Synapse containers to provide the Traefik Docker provider with the information it needs to proxy `matrix.DOMAIN`, `element.DOMAIN`, `dimension.DOMAIN` and `jitsi.DOMAIN`. Some [static configuration](https://docs.traefik.io/v2.0/reference/static-configuration/file/) is required in Traefik; namely, having endpoints on ports 443 and 8448 and having a certificate resolver.
@ -240,7 +237,7 @@ services:
- "--providers.docker.network=traefik"
- "--providers.docker.exposedbydefault=false"
- "--entrypoints.web-secure.address=:443"
- "--entrypoints.synapse.address=:8448"
- "--entrypoints.federation.address=:8448"
- "--certificatesresolvers.default.acme.tlschallenge=true"
- "--certificatesresolvers.default.acme.email=YOUR EMAIL"
- "--certificatesresolvers.default.acme.storage=/letsencrypt/acme.json"

17
docs/configuring-playbook-postgres-backup.md
View File

@ -1,6 +1,6 @@
# Setting up postgres backup (optional)
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you.
The playbook can install and configure [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) for you via the [com.devture.ansible.role.postgres_backup](https://github.com/devture/com.devture.ansible.role.postgres_backup) Ansible role.
For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [borg backup](configuring-playbook-backup-borg.md) instead.
@ -10,7 +10,7 @@ For a more complete backup solution (one that includes not only Postgres, but al
Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:
```yaml
matrix_postgres_backup_enabled: true
devture_postgres_backup_enabled: true
```
Refer to the table below for additional configuration variables and their default values.
@ -18,12 +18,13 @@ Refer to the table below for additional configuration variables and their defaul
| Name | Default value | Description |
| :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
|`matrix_postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|`matrix_postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
|`matrix_postgres_backup_keep_days`|`7`|Number of daily backups to keep|
|`matrix_postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
|`matrix_postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
|`matrix_postgres_backup_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Storagepath for the database backups|
|`devture_postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|`devture_postgres_backup_schedule`| `'@daily'` |Cron-schedule specifying the interval between postgres backups.|
|`devture_postgres_backup_keep_days`|`7`|Number of daily backups to keep|
|`devture_postgres_backup_keep_weeks`|`4`|Number of weekly backups to keep|
|`devture_postgres_backup_keep_months`|`12`|Number of monthly backups to keep|
|`devture_postgres_base_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Base path for postgres-backup. Also see `devture_postgres_data_path` |
|`devture_postgres_data_path` | `"{{ devture_postgres_base_path }}/data"` | Storage path for postgres-backup database backups |
## Installing

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

@ -15,6 +15,9 @@ matrix_prometheus_node_exporter_enabled: true
# You can remove this, if unnecessary.
matrix_prometheus_postgres_exporter_enabled: true
# You can remove this, if unnecessary.
matrix_prometheus_nginxlog_exporter_enabled: true
matrix_grafana_enabled: true
matrix_grafana_anonymous_access: false
@ -39,6 +42,7 @@ Name | Description
`matrix_prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
`matrix_prometheus_node_exporter_enabled`|[Node Exporter](https://prometheus.io/docs/guides/node-exporter/) is an addon of sorts to Prometheus that collects generic system information such as CPU, memory, filesystem, and even system temperatures
`matrix_prometheus_postgres_exporter_enabled`|[Postgres Exporter](configuring-playbook-prometheus-postgres.md) is an addon of sorts to expose Postgres database metrics to Prometheus.
`matrix_prometheus_nginxlog_exporter_enabled`|[NGINX Log Exporter](configuring-playbook-prometheus-nginxlog.md) is an addon of sorts to expose NGINX logs to Prometheus.
`matrix_grafana_enabled`|[Grafana](https://grafana.com/) is the visual component. It shows (on the `stats.<your-domain>` subdomain) the dashboards with the graphs that we're interested in
`matrix_grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
`matrix_grafana_default_admin_user`<br>`matrix_grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
@ -73,6 +77,7 @@ Name | Description
`matrix_prometheus_node_exporter_enabled`|Set this to `true` to enable the node (general system stats) exporter (locally, on the container network)
`matrix_prometheus_node_exporter_metrics_proxying_enabled`|Set this to `true` to expose the node (general system stats) metrics on `https://matrix.DOMAIN/metrics/node-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
`matrix_prometheus_postgres_exporter_enabled`|Set this to `true` to enable the [Postgres exporter](configuring-playbook-prometheus-postgres.md) (locally, on the container network)
`matrix_prometheus_nginxlog_exporter_enabled`|Set this to `true` to enable the [NGINX Log exporter](configuring-playbook-prometheus-nginxlog.md) (locally, on the container network)
`matrix_prometheus_postgres_exporter_metrics_proxying_enabled`|Set this to `true` to expose the [Postgres exporter](configuring-playbook-prometheus-postgres.md) metrics on `https://matrix.DOMAIN/metrics/postgres-exporter` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)
`matrix_bridge_hookshot_metrics_enabled`|Set this to `true` to make [Hookshot](configuring-playbook-bridge-hookshot.md) expose metrics (locally, on the container network)
`matrix_bridge_hookshot_metrics_proxying_enabled`|Set this to `true` to expose the [Hookshot](configuring-playbook-bridge-hookshot.md) metrics on `https://matrix.DOMAIN/metrics/hookshot` (only takes effect if `matrix_nginx_proxy_proxy_matrix_metrics_enabled: true`)

59
docs/configuring-playbook-prometheus-nginxlog.md Normal file
View File

@ -0,0 +1,59 @@
# Enabling metrics and graphs for NginX logs (optional)
It can be useful to have some (visual) insight into NignX logs.
This adds [prometheus-nginxlog-exporter](https://github.com/martin-helmich/prometheus-nginxlog-exporter/) to your matrix deployment.
It will provide a prometheus 'metrics' endpoint exposing data from both the `matrix-nginx-proxy` and `matrix-synapse-reverse-proxy-companion` logs and automatically aggregates the data with prometheus.
Optionally it visualizes the data, if [`matrix-grafana`](configuring-playbook-prometheus-grafana.md) is enabled, by means of a dedicated Grafana dashboard named `NGINX PROXY`
You can enable this role by adding the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_prometheus_nginxlog_exporter_enabled: true
# required depency
matrix_prometheus_enabled: true
# optional for visualization
matrix_grafana_enabled: true
```
x | Prerequisites | Variable | Description
|:--:|:--:|:--:|:--|
**REQUIRED** | `matrix-prometheus`| `matrix_prometheus_enabled`|[Prometheus](https://prometheus.io) is a time series database. It holds all the data we're going to talk about.
_Optional_ | [`matrix-grafana`](configuring-playbook-prometheus-grafana.md) | [`matrix_grafana_enabled`](configuring-playbook-prometheus-grafana.md)|[Grafana](https://grafana.com) is the visual component. It shows (on the `stats.<your-domain>` subdomain) graphs that we're interested in. When enabled the `NGINX PROXY` dashboard is automatically added.
## Docker Image Compatibility
At the moment of writing only images for `amd64` and `arm64` architectures are available
The playbook currently does not support building an image.
You can however use a custom-build image by setting
```yaml
matrix_prometheus_nginxlog_exporter_docker_image_arch_check_enabled: false
matrix_prometheus_nginxlog_exporter_docker_image: path/to/docker/image:tag
```
## Security and privacy
Metrics and resulting graphs can contain a lot of information. NginX logs contain information like IP address, URLs, UserAgents and more. This information can reveal usage patterns and could be considered Personally Identifiable Information (PII). Think about this before enabling (anonymous) access.
Please make sure you change the default Grafana password.
## Save metrics on an external Prometheus server
The playbook will automatically integrate the metrics into the Prometheus server provided with this playbook. You can choose to save data on an external Prometheus instance.
The metrics of this role will be exposed on `https://matrix.DOMAIN/metrics/nginxlog` when setting
```yaml
matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled: true
# required dependency
matrix_nginx_proxy_proxy_matrix_metrics_enabled: true
```
The playbook can provide a single endpoint (`https://matrix.DOMAIN/metrics/*`), under which various services may expose their metrics (e.g. `/metrics/node-exporter`, `/metrics/postgres-exporter`, `/metrics/nginxlog`, etc). To enable this `/metrics/*` feature, use `matrix_nginx_proxy_proxy_matrix_metrics_enabled`. To protect access using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), see `matrix_nginx_proxy_proxy_matrix_metrics_basic_auth_enabled`.
The following variables may be of interest:
Name | Description
-----|----------
`matrix_nginx_proxy_proxy_matrix_metrics_enabled`|Set this to `true` to enable metrics exposure for various services on `https://matrix.DOMAIN/metrics/*`. Refer to the individual `matrix_SERVICE_metrics_proxying_enabled` variables below for exposing metrics for each individual service.

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

@ -28,13 +28,13 @@ While you will need some local disk space around, it's only to accommodate usage
## 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`):
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` 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_endpoint_url: https://s3.REGION_NAME.amazonaws.com # adjust this
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.
@ -62,7 +62,7 @@ Migrating your existing data can happen in multiple ways:
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`.
To copy your existing files, SSH into the server and run `/matrix/synapse/ext/s3-storage-provider/bin/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).
@ -76,12 +76,12 @@ Then use the following commands (`$` values come from environment variables - th
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:
Instead of running the above commands manually in the shell, you can also run the `/matrix/synapse/ext/s3-storage-provider/bin/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 ..`)
- allows you to easily interrupt slow-running commands, etc. (the `/matrix/synapse/ext/s3-storage-provider/bin/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`
@ -119,7 +119,7 @@ As described in [How it works?](#how-it-works) above, when new media is uploaded
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
- the `/matrix/synapse/ext/s3-storage-provider/bin/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

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

@ -37,7 +37,7 @@ If you'd like more customization power, you can start with one of the presets an
If you increase worker counts too much, you may need to increase the maximum number of Postgres connections too (example):
```yaml
matrix_postgres_process_extra_arguments: [
devture_postgres_process_extra_arguments: [
"-c 'max_connections=200'"
]
```
@ -56,21 +56,27 @@ Certain Synapse administration tasks (managing users and rooms, etc.) can be per
If you'd like to use OpenID Connect authentication with Synapse, you'll need some additional reverse-proxy configuration (see [our nginx reverse-proxy doc page](configuring-playbook-nginx.md#synapse-openid-connect-for-single-sign-on)).
This example configuration is for [keycloak](https://www.keycloak.org/), an opensource Identity Provider maintained by Red Hat.
For more detailed documentation on available options and how to setup keycloak, see the [Synapse documentation on OpenID Connect with keycloak](https://github.com/matrix-org/synapse/blob/develop/docs/openid.md#keycloak).
In case you encounter errors regarding the parsing of the variables, you can try to add `{% raw %}` and `{% endraw %}` blocks around them. For example ;
```
matrix_synapse_configuration_extension_yaml: |
oidc_providers:
- idp_id: keycloak
idp_name: "Keycloak"
issuer: "https://url.ix/auth/realms/x"
idp_name: "My KeyCloak server"
issuer: "https://url.ix/auth/realms/{realm_name}"
client_id: "matrix"
client_secret: "{{ vault_synapse_keycloak }}"
scopes: ["openid", "profile"]
authorization_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/auth"
token_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/token"
userinfo_endpoint: "https://url.ix/auth/realms/x/protocol/openid-connect/userinfo"
user_mapping_provider:
config:
display_name_template: "{% raw %}{{ user.given_name }}{% endraw %} {% raw %}{{ user.family_name }}{% endraw %}"
localpart_template: "{% raw %}{{ user.preferred_username }}{% endraw %}"
display_name_template: "{% raw %}{{ user.name }}{% endraw %}"
email_template: "{% raw %}{{ user.email }}{% endraw %}"
allow_existing_users: true # Optional
backchannel_logout_enabled: true # Optional
```

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

@ -12,15 +12,17 @@ growth of the Matrix community, and helps to make Matrix a success.
If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
```yaml
matrix_synapse_report_stats: true
matrix_synapse_report_stats: true # for synapse
matrix_dendrite_report_stats: true # for dendrite
```
## Usage statistics being submitted
When enabled, Synapse will regularly upload a few dozen statistics about your server.
When enabled, your homeserver will regularly upload a few dozen statistics about your server.
This data includes your homeserver's domain, the total number of users, the number of active
users, the total number of rooms, and the number of messages sent per day on your homeserver.
See [Synapse's documentation](https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics)
See [Synapse's documentation](https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md#available-statistics) or [Dendrite's documentation](https://github.com/matrix-org/dendrite/blob/main/docs/FAQ.md#what-is-being-reported-when-enabling-phone-home-statistics)
for the full list of statistics that are reported.

2
docs/configuring-playbook.md
View File

@ -47,6 +47,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Configuring Conduit](configuring-playbook-conduit.md), if you've switched to the [Conduit](https://conduit.rs) homeserver implementation (optional)
- [Configuring Dendrite](configuring-playbook-dendrite.md), if you've switched to the [Dendrite](https://matrix-org.github.io/dendrite) homeserver implementation (optional)
- [Configuring Element](configuring-playbook-client-element.md) (optional)
- [Storing Matrix media files on Amazon S3](configuring-playbook-s3.md) (optional)

2
docs/faq.md
View File

@ -317,7 +317,7 @@ If you've installed [Jitsi](configuring-playbook-jitsi.md) (not installed by def
Yes, we can stop installing Docker ourselves. Just use this in your `vars.yml` file:
```yaml
matrix_docker_installation_enabled: true
matrix_playbook_docker_installation_enabled: false
```
### I run another webserver on the same server where I wish to install Matrix. What now?

4
docs/importing-postgres.md
View File

@ -97,9 +97,9 @@ Once the database is clear and the ownership of the tables has been fixed in the
Check, if `--dbname` is set to `synapse` (not `matrix`) and replace paths (or even better, copy this line from your terminal)
```
/usr/bin/env docker run --rm --name matrix-postgres-import --log-driver=none --user=998:1001 --cap-drop=ALL --network=matrix --env-file=/matrix/postgres/env-postgres-psql --mount type=bind,src=/migration/synapse_dump.sql,dst=/synapse_dump.sql,ro --entrypoint=/bin/sh docker.io/postgres:14.1-alpine -c "cat /synapse_dump.sql | grep -vE '^(CREATE|ALTER) ROLE (matrix)(;| WITH)' | grep -vE '^CREATE DATABASE (matrix)\s' | psql -v ON_ERROR_STOP=1 -h matrix-postgres --dbname=synapse"
/usr/bin/env docker run --rm --name matrix-postgres-import --log-driver=none --user=998:1001 --cap-drop=ALL --network=matrix --env-file=/matrix/postgres/env-postgres-psql --mount type=bind,src=/migration/synapse_dump.sql,dst=/synapse_dump.sql,ro --entrypoint=/bin/sh docker.io/postgres:15.0-alpine -c "cat /synapse_dump.sql | grep -vE '^(CREATE|ALTER) ROLE (matrix)(;| WITH)' | grep -vE '^CREATE DATABASE (matrix)\s' | psql -v ON_ERROR_STOP=1 -h matrix-postgres --dbname=synapse"
```
### Hints
To open psql terminal run `/usr/local/bin/matrix-postgres-cli`
To open psql terminal run `/matrix/postgres/bin/cli`

14
docs/installing.md
View File

@ -13,17 +13,21 @@ The general command syntax is: `ansible-playbook -i inventory/hosts setup.yml --
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-all` - runs all setup tasks (installation and uninstallation) for all components, but does not start/restart services
- `install-all` - like `setup-all`, but skips uninstallation tasks. Useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove components, you'd need to run `setup-all` though, or these components will still remain installed
- `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).
- `install-SERVICE` (e.g. `install-bot-postmoogle`) - like `setup-SERVICE`, but skips uninstallation tasks. See `install-all` above for additional information.
- `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.
`setup-*` tags and `install-*` 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
@ -40,7 +44,7 @@ There 2 ways to start the installation process - depending on whether you're [In
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
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start
```
This will do a full installation and start all Matrix services.
@ -56,7 +60,7 @@ Starting its services or messing with its database now will affect your data imp
To do the installation **without** starting services, run only the `setup-all` tag:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
ansible-playbook -i inventory/hosts setup.yml --tags=install-all
```
When this command completes, services won't be running yet.
@ -82,6 +86,8 @@ Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-t
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.
Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [Playbook tags introduction](#playbook-tags-introduction)
## 3. Finalize the installation

12
docs/maintenance-postgres.md
View File

@ -16,7 +16,7 @@ Table of contents:
## Getting a database terminal
You can use the `/usr/local/bin/matrix-postgres-cli` tool to get interactive terminal access ([psql](https://www.postgresql.org/docs/11/app-psql.html)) to the PostgreSQL server.
You can use the `/matrix/postgres/bin/cli` tool to get interactive terminal access ([psql](https://www.postgresql.org/docs/11/app-psql.html)) to the PostgreSQL server.
If you are using an [external Postgres server](configuring-playbook-external-postgres.md), the above tool will not be available.
@ -80,6 +80,8 @@ This playbook can upgrade your existing Postgres setup with the following comman
ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres
**Warning: If you're using Borg Backup keep in mind that there is no official Postgres 15 support yet.**
**The old Postgres data directory is backed up** automatically, by renaming it to `/matrix/postgres/data-auto-upgrade-backup`.
To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="postgres_auto_upgrade_backup_data_path=/another/disk/matrix-postgres-before-upgrade"`
@ -97,7 +99,7 @@ Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
## Tuning PostgreSQL
PostgreSQL can be tuned to make it run faster. This is done by passing extra arguments to Postgres with the `matrix_postgres_process_extra_arguments` variable. You should use a website like https://pgtune.leopard.in.ua/ or information from https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server to determine what Postgres settings you should change.
PostgreSQL can be tuned to make it run faster. This is done by passing extra arguments to Postgres with the `devture_postgres_process_extra_arguments` variable. You should use a website like https://pgtune.leopard.in.ua/ or information from https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server to determine what Postgres settings you should change.
**Note**: the configuration generator at https://pgtune.leopard.in.ua/ adds spaces around the `=` sign, which is invalid. You'll need to remove it manually (`max_connections = 300` -> `max_connections=300`)
@ -107,7 +109,7 @@ These are not recommended values and they may not work well for you. This is jus
Here is an example config for a small 2 core server with 4GB of RAM and SSD storage:
```
matrix_postgres_process_extra_arguments: [
devture_postgres_process_extra_arguments: [
"-c shared_buffers=128MB",
"-c effective_cache_size=2304MB",
"-c effective_io_concurrency=100",
@ -118,7 +120,7 @@ matrix_postgres_process_extra_arguments: [
Here is an example config for a 4 core server with 8GB of RAM on a Virtual Private Server (VPS); the paramters have been configured using https://pgtune.leopard.in.ua with the following setup: PostgreSQL version 12, OS Type: Linux, DB Type: Mixed type of application, Data Storage: SSD storage:
```
matrix_postgres_process_extra_arguments: [
devture_postgres_process_extra_arguments: [
"-c max_connections=100",
"-c shared_buffers=2GB",
"-c effective_cache_size=6GB",
@ -140,7 +142,7 @@ matrix_postgres_process_extra_arguments: [
Here is an example config for a large 6 core server with 24GB of RAM:
```
matrix_postgres_process_extra_arguments: [
devture_postgres_process_extra_arguments: [
"-c max_connections=40",
"-c shared_buffers=1536MB",
"-c checkpoint_completion_target=0.7",

29
docs/registering-users.md
View File

@ -9,7 +9,7 @@ Table of contents:
- [Managing users via a Web UI](#managing-users-via-a-web-ui)
- [Letting certain users register on your private server](#letting-certain-users-register-on-your-private-server)
- [Enabling public user registration](#enabling-public-user-registration)
- [Adding/Removing Administrator privileges to an existing user](#addingremoving-administrator-privileges-to-an-existing-user)
- [Adding/Removing Administrator privileges to an existing Synapse user](#addingremoving-administrator-privileges-to-an-existing-synapse-user)
## Registering users manually
@ -23,7 +23,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-usern
**or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)):
```
/usr/local/bin/matrix-synapse-register-user <your-username> <your-password> <admin access: 0 or 1>
/matrix/synapse/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
```
**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:<your-domain>` identifier.
@ -58,13 +58,24 @@ and running the [installation](installing.md) procedure once again.
If you're opening up registrations publicly like this, you might also wish to [configure CAPTCHA protection](configuring-captcha.md).
## Adding/Removing Administrator privileges to an existing user
## Adding/Removing Administrator privileges to an existing Synapse user
The script `/usr/local/bin/matrix-change-user-admin-status` may be used to change a user's admin privileges.
* log on to your server with ssh
* execute with the username and 0/1 (0 = non-admin | 1 = admin)
To change the admin privileges for a user, you need to run an SQL query like this against the `synapse` database:
```sql
UPDATE users SET admin=ADMIN_VALUE WHERE name = '@USER:DOMAIN'
```
/usr/local/bin/matrix-change-user-admin-status <username> <0/1>
```
where:
- `ADMIN_VALUE` being either `0` (regular user) or `1` (admin)
- `USER` and `DOMAIN` pointing to a valid user on your server
If you're using the integrated Postgres server and not an [external Postgres server](configuring-playbook-external-postgres.md), you can launch a Postgres into the `synapse` database by:
- running `/matrix/postgres/bin/cli` - to launch [`psql`](https://www.postgresql.org/docs/current/app-psql.html)
- running `\c synapse` - to change to the `synapse` database
You can then proceed to run the query above.
**Note**: directly modifying the raw data of Synapse (or any other software) could cause the software to break. You've been warned!

4
docs/self-building.md
View File

@ -6,11 +6,11 @@ The playbook supports self-building of various components, which don't have a co
For other architectures (e.g. `arm32`, `arm64`), ready-made container images are used when available. If there's no ready-made image for a specific component and said component supports self-building, an image will be built on the host. Building images like this takes more time and resources (some build tools need to get installed by the playbook to assist building).
To make use of self-building, you don't need to do anything besides change your architecture variable (e.g. `matrix_architecture: arm64`). If a component has an image for the specified architecture, the playbook will use it directly. If not, it will build the image on the server itself.
To make use of self-building, you don't need to do anything. If a component has an image for the specified architecture, the playbook will use it directly. If not, it will build the image on the server itself.
Note that **not all components support self-building yet**.
List of roles where self-building the Docker image is currently possible:
Possibly outdated list of roles where self-building the Docker image is currently possible:
- `matrix-synapse`
- `matrix-synapse-admin`
- `matrix-client-element`

4
docs/uninstalling.md
View File

@ -12,7 +12,7 @@
## Uninstalling using a script
Installing places a `/usr/local/bin/matrix-remove-all` script on the server.
Installing places a `/matrix/bin/remove-all` script on the server.
You can run it to to have it uninstall things for you automatically (see below). **Use with caution!**
@ -25,8 +25,6 @@ If you prefer to uninstall manually, run these commands (most are meant to be ex
- delete the Matrix-related systemd `.service` and `.timer` files (`rm -f /etc/systemd/system/matrix*.{service,timer}`) and reload systemd (`systemctl daemon-reload`)
- delete some helper scripts (`rm -f /usr/local/bin/matrix*`)
- delete some cached Docker images (`docker system prune -a`) or just delete them all (`docker rmi $(docker images -aq)`)
- delete the Docker networks: `docker network rm matrix matrix-coturn` (might have been deleted already if you ran the `docker system prune` command)

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

@ -1,6 +1,6 @@
# Updating users passwords
## Option 1 (if you are using the default matrix-postgres container):
## Option 1 (if you are using the integrated Postgres database):
You can reset a user's password via the Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
@ -36,7 +36,7 @@ Use the Synapse User Admin API as described here: https://github.com/matrix-org/
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).
If you didn't make your account a server admin when you created it, you can learn how to switch it now by reading about it in [Adding/Removing Administrator privileges to an existing Synapse user](registering-users.md#addingremoving-administrator-privileges-to-an-existing-synapse-user).
### Example:
To set @user:domain.com's password to `correct_horse_battery_staple` you could use this curl command:

4
examples/caddy/matrix-synapse
View File

@ -21,11 +21,11 @@ https://matrix.DOMAIN {
}
# Synapse Client<>Server API
proxy /_matrix matrix-synapse:8008 {
proxy /_matrix matrix-synapse-reverse-proxy-companion:8008 {
transparent
except /_matrix/identity/ /_matrix/client/r0/user_directory/search
}
proxy /_synapse/client matrix-synapse:8008 {
proxy /_synapse/client matrix-synapse-reverse-proxy-companion:8008 {
transparent
}
}

2
examples/vars.yml
View File

@ -35,4 +35,4 @@ matrix_ssl_lets_encrypt_support_email: ''
#
# The playbook creates additional Postgres users and databases (one for each enabled service)
# using this superuser account.
matrix_postgres_connection_password: ''
devture_postgres_connection_password: ''

1190
group_vars/matrix_servers
View File

File diff suppressed because it is too large Load Diff

12
playbooks/jitsi_jvb.yml Normal file
View File

@ -0,0 +1,12 @@
---
- name: "Set up additional Jitsi JVB servers"
hosts: "jitsi_jvb_servers"
become: true
roles:
- role: galaxy/com.devture.ansible.role.playbook_help
- role: galaxy/com.devture.ansible.role.systemd_docker_base
- custom/matrix-base
- custom/matrix-jitsi
- custom/matrix-common-after

126
playbooks/matrix.yml Executable file
View File

@ -0,0 +1,126 @@
---
- name: "Set up a Matrix server"
hosts: "{{ target if target is defined else 'matrix_servers' }}"
become: true
roles:
# Most of the roles below are not distributed with the playbook, but downloaded separately using `ansible-galaxy` via the `make roles` command (see `Makefile`).
- role: galaxy/com.devture.ansible.role.playbook_help
- role: galaxy/com.devture.ansible.role.systemd_docker_base
- role: custom/matrix_playbook_migration
- when: matrix_playbook_docker_installation_enabled | bool
role: galaxy/geerlingguy.docker
vars:
docker_install_compose: false
tags:
- setup-docker
- setup-all
- install-docker
- install-all
- when: devture_docker_sdk_for_python_installation_enabled | bool
role: galaxy/com.devture.ansible.role.docker_sdk_for_python
tags:
- setup-docker
- setup-all
- install-docker
- install-all
- when: devture_timesync_installation_enabled | bool
role: galaxy/com.devture.ansible.role.timesync
tags:
- setup-timesync
- setup-all
- install-timesync
- install-all
- custom/matrix-base
- custom/matrix-dynamic-dns
- custom/matrix-mailer
- role: galaxy/com.devture.ansible.role.postgres
- custom/matrix-redis
- custom/matrix-corporal
- custom/matrix-bridge-appservice-discord
- custom/matrix-bridge-appservice-slack
- custom/matrix-bridge-appservice-webhooks
- custom/matrix-bridge-appservice-irc
- custom/matrix-bridge-appservice-kakaotalk
- custom/matrix-bridge-beeper-linkedin
- custom/matrix-bridge-go-skype-bridge
- custom/matrix-bridge-mautrix-facebook
- custom/matrix-bridge-mautrix-twitter
- custom/matrix-bridge-mautrix-hangouts
- custom/matrix-bridge-mautrix-googlechat
- custom/matrix-bridge-mautrix-instagram
- custom/matrix-bridge-mautrix-signal
- custom/matrix-bridge-mautrix-telegram
- custom/matrix-bridge-mautrix-whatsapp
- custom/matrix-bridge-mautrix-discord
- custom/matrix-bridge-mx-puppet-discord
- custom/matrix-bridge-mx-puppet-groupme
- custom/matrix-bridge-mx-puppet-steam
- custom/matrix-bridge-mx-puppet-slack
- custom/matrix-bridge-mx-puppet-twitter
- custom/matrix-bridge-mx-puppet-instagram
- custom/matrix-bridge-sms
- custom/matrix-bridge-heisenbridge
- custom/matrix-bridge-hookshot
- custom/matrix-bot-matrix-reminder-bot
- custom/matrix-bot-matrix-registration-bot
- custom/matrix-bot-maubot
- custom/matrix-bot-buscarron
- custom/matrix-bot-honoroit
- custom/matrix-bot-postmoogle
- custom/matrix-bot-go-neb
- custom/matrix-bot-mjolnir
- custom/matrix-cactus-comments
- custom/matrix-synapse
- custom/matrix-synapse-reverse-proxy-companion
- custom/matrix-dendrite
- custom/matrix-conduit
- custom/matrix-synapse-admin
- custom/matrix-prometheus-node-exporter
- custom/matrix-prometheus-postgres-exporter
- custom/matrix-prometheus-nginxlog-exporter
- custom/matrix-prometheus
- custom/matrix-grafana
- custom/matrix-registration
- custom/matrix-client-element
- custom/matrix-client-hydrogen
- custom/matrix-client-cinny
- custom/matrix-jitsi
- custom/matrix-ldap-registration-proxy
- custom/matrix-ma1sd
- custom/matrix-dimension
- custom/matrix-etherpad
- custom/matrix-email2matrix
- custom/matrix-sygnal
- custom/matrix-ntfy
- custom/matrix-nginx-proxy
- custom/matrix-coturn
- custom/matrix-aux
- role: galaxy/com.devture.ansible.role.postgres_backup
- custom/matrix-backup-borg
- custom/matrix-user-creator
- custom/matrix-common-after
- when: devture_systemd_service_manager_enabled | bool
role: galaxy/com.devture.ansible.role.systemd_service_manager
# This is pretty much last, because we want it to better serve as a "last known good configuration".
# See: https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2217#issuecomment-1301487601
- when: devture_playbook_state_preserver_enabled | bool
role: galaxy/com.devture.ansible.role.playbook_state_preserver
tags:
- setup-all
- install-all
- role: galaxy/com.devture.ansible.role.playbook_runtime_messages

19
requirements.yml
View File

@ -1,5 +1,11 @@
---
- src: geerlingguy.docker
version: 6.0.4
- src: git+https://github.com/devture/com.devture.ansible.role.docker_sdk_for_python.git
version: 6ba3be490b6f4c6f35ea109aeb8e533fa231b3a5
- src: git+https://github.com/devture/com.devture.ansible.role.playbook_help.git
version: c1f40e82b4d6b072b6f0e885239322bdaaaf554f
@ -7,10 +13,19 @@
version: 327d2e17f5189ac2480d6012f58cf64a2b46efba
- src: git+https://github.com/devture/com.devture.ansible.role.timesync.git
version: 461ace97fcf0e36c76747b36fcad8587d9b072f5
version: 660f384f176a9ea3b5cc702bde39e7dc10bf6186
- 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.postgres.git
version: e75973e3a4edc12dfc3e880e43b12ebecbf82c61
- src: git+https://github.com/devture/com.devture.ansible.role.postgres_backup.git
version: 77b1f9ae1aafa31c9078178c1036bf744c99d08b
- src: git+https://github.com/devture/com.devture.ansible.role.systemd_service_manager.git
version: 6ccb88ac5fc27e1e70afcd48278ade4b564a9096
- src: git+https://github.com/devture/com.devture.ansible.role.playbook_runtime_messages.git
version: f1c78d4e85e875129790c58335d0e44385683f6b
version: 9b4b088c62b528b73a9a7c93d3109b091dd42ec6

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

@ -1,7 +1,9 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup.yml"
when: run_stop | bool
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup.yml"
tags:
- setup-all
- setup-aux-files
- install-all
- install-aux-files

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

@ -37,9 +37,9 @@ matrix_backup_borg_location_source_directories: []
# postgres db backup
matrix_backup_borg_postgresql_enabled: true
matrix_backup_borg_supported_postgres_versions: ['12', '13', '14']
matrix_backup_borg_supported_postgres_versions: ['12', '13', '14', '15']
matrix_backup_borg_postgresql_databases: []
matrix_backup_borg_postgresql_databases_hostname: "matrix-postgres"
matrix_backup_borg_postgresql_databases_hostname: ''
matrix_backup_borg_postgresql_databases_username: "matrix"
matrix_backup_borg_postgresql_databases_password: ""
matrix_backup_borg_postgresql_databases_port: 5432

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

@ -1,4 +0,0 @@
---
- ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-backup-borg.timer'] }}"
when: matrix_backup_borg_enabled | bool

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

@ -1,22 +1,19 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup | bool and matrix_backup_borg_enabled | bool"
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_backup_borg_enabled | bool"
tags:
- setup-all
- setup-backup-borg
- install-all
- install-backup-borg
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_backup_borg_enabled | bool"
tags:
- setup-all
- setup-backup-borg
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup | bool and not matrix_backup_borg_enabled | bool"
tags:
- setup-all

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

@ -5,22 +5,22 @@
- 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.
You are not running a built-in Postgres server (`devture_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
when: not devture_postgres_enabled
- ansible.builtin.import_role:
name: custom/matrix-postgres
- ansible.builtin.include_role:
name: galaxy/com.devture.ansible.role.postgres
tasks_from: detect_existing_postgres_version
- name: Fail if detected Postgres version is unsupported
ansible.builtin.fail:
msg: "You cannot use borg backup with such an old version ({{ matrix_postgres_detected_version }}) of Postgres. Consider upgrading - link to docs for upgrading Postgres: docs/maintenance-postgres.md#upgrading-postgresql"
when: "matrix_postgres_detected_version not in matrix_backup_borg_supported_postgres_versions"
msg: "You cannot use borg backup with such an old version ({{ devture_postgres_detected_version }}) of Postgres. Consider upgrading - link to docs for upgrading Postgres: docs/maintenance-postgres.md#upgrading-postgresql"
when: "devture_postgres_detected_version not in matrix_backup_borg_supported_postgres_versions"
- name: Set the correct borg backup version to use
ansible.builtin.set_fact:
matrix_backup_borg_version: "{{ matrix_postgres_detected_version }}"
matrix_backup_borg_version: "{{ devture_postgres_detected_version }}"
- name: Ensure borg paths exist
ansible.builtin.file:
@ -105,19 +105,3 @@
src: "{{ role_path }}/templates/systemd/matrix-backup-borg.timer.j2"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.timer"
mode: 0644
register: matrix_backup_borg_systemd_timer_result
- name: Ensure systemd reloaded after matrix-backup-borg.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_backup_borg_systemd_service_result.changed | bool"
- name: Ensure matrix-backup-borg.service enabled
ansible.builtin.service:
enabled: true
name: matrix-backup-borg.service
- name: Ensure matrix-backup-borg.timer enabled
ansible.builtin.service:
enabled: true
name: matrix-backup-borg.timer

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

@ -1,41 +1,25 @@
---
- name: Check existence of matrix-backup-borg service
ansible.builtin.stat:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.service"
register: matrix_backup_borg_service_stat
- when: matrix_backup_borg_service_stat.stat.exists | bool
block:
- name: Ensure matrix-backup-borg is stopped
ansible.builtin.service:
name: matrix-backup-borg
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_backup_borg_service_stat.stat.exists | bool"
- name: Ensure matrix-backup-borg.service doesn't exist
ansible.builtin.file:
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: "{{ devture_systemd_docker_base_systemd_path }}/matrix-backup-borg.timer"
state: absent
when: "matrix_backup_borg_service_stat.stat.exists | bool"
- name: Ensure systemd reloaded after matrix-backup-borg.service removal
ansible.builtin.service:
daemon_reload: true
when: "matrix_backup_borg_service_stat.stat.exists | bool"
- name: Ensure Matrix borg paths don't exist
ansible.builtin.file:
path: "{{ matrix_backup_borg_base_path }}"
state: absent
- name: Ensure borg Docker image doesn't exist
community.docker.docker_image:
name: "{{ matrix_backup_borg_docker_image }}"
state: absent

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

@ -1,12 +1,13 @@
---
- name: Fail if required settings not defined
- name: Fail if required backup-borg settings not defined
ansible.builtin.fail:
msg: >-
You need to define a required configuration setting (`{{ item }}`).
when: "vars[item] == ''"
You need to define a required configuration setting (`{{ item.name }}`).
when: "item.when | bool and vars[item.name] == ''"
with_items:
- "matrix_backup_borg_ssh_key_private"
- "matrix_backup_borg_location_repositories"
- {'name': 'matrix_backup_borg_ssh_key_private', when: true}
- {'name': 'matrix_backup_borg_location_repositories', when: true}
- {'name': 'matrix_backup_borg_postgresql_databases_hostname', when: "{{ matrix_backup_borg_postgresql_enabled }}"}
- name: Fail if encryption passphrase is undefined unless repository is unencrypted
ansible.builtin.fail:

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

@ -34,7 +34,7 @@ hooks:
hostname: {{ matrix_backup_borg_postgresql_databases_hostname|to_json }}
username: {{ matrix_backup_borg_postgresql_databases_username|to_json }}
password: {{ matrix_backup_borg_postgresql_databases_password|to_json }}
port: {{ matrix_backup_borg_postgresql_databases_port|to_json }}
port: {{ matrix_backup_borg_postgresql_databases_port | int | to_json }}
{% endfor %}
{% endif %}
after_backup:

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

@ -31,14 +31,21 @@ ExecStartPre=-{{ devture_systemd_docker_base_host_command_docker }} run --rm --n
{{ arg }} \
{% endfor %}
{{ matrix_backup_borg_docker_image }} \
sh -c "borgmatic --init --encryption {{ matrix_backup_borg_encryption }}"
sh -c "borgmatic rcreate --encryption {{ matrix_backup_borg_encryption }}"
# The `CAP_DAC_OVERRIDE` capability is required, so that `root` in the container
# can read the `/etc/borgmatic.d/config.yaml` (`{{ matrix_backup_borg_config_path }}/config.yaml`) file,
# owned by `matrix:matrix` on the filesystem.
#
# `/root` is mountes as temporary filesystem, because we're using `--read-only` and because
# Borgmatic tries to write to at least a few paths under `/root` (`.config`, `.ssh`, `.borgmatic`).
ExecStart={{ devture_systemd_docker_base_host_command_docker }} run --rm --name matrix-backup-borg \
--log-driver=none \
--cap-drop=ALL \
--cap-add=CAP_DAC_OVERRIDE \
--read-only \
--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
--network={{ matrix_docker_network }} \
--tmpfs=/root:rw,noexec,nosuid,size=100m \
--tmpfs=/tmp:rw,noexec,nosuid,size=100m \
--mount type=bind,src={{ matrix_backup_borg_config_path }}/passwd,dst=/etc/passwd,ro \
--mount type=bind,src={{ matrix_backup_borg_config_path }},dst=/etc/borgmatic.d,ro \

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

@ -1,4 +1,5 @@
---
# The bare domain name which represents your Matrix identity.
# Matrix user ids for your server will be of the form (`@user:<matrix-domain>`).
#
@ -12,6 +13,15 @@ matrix_domain: ~
# Example value: "@someone:{{ matrix_domain }}"
matrix_admin: ''
# matrix_homeserver_enabled controls whether to enable the homeserver systemd service, etc.
#
# Unless you're wrapping this playbook in another one
# where you optionally wish to disable homeserver integration, you don't need to use this.
#
# Note: disabling this does not mean that a homeserver won't get installed.
# Whether homeserver software is installed depends on other (`matrix_HOMESERVER_enabled`) variables - see `group_vars/matrix_servers`.
matrix_homeserver_enabled: true
# Homeserver admin contacts and support page as per MSC 1929
# See: https://github.com/matrix-org/matrix-spec-proposals/pull/1929
# Users in form:
@ -86,7 +96,7 @@ matrix_federation_public_port: 8448
# Recognized values by us are 'amd64', 'arm32' and 'arm64'.
# Not all architectures support all services, so your experience (on non-amd64) may vary.
# See docs/alternative-architectures.md
matrix_architecture: amd64
matrix_architecture: "{{ 'amd64' if ansible_architecture == 'x86_64' else ('arm64' if ansible_architecture == 'aarch64' else ('arm32' if ansible_architecture.startswith('armv') else '')) }}"
# The architecture for Debian packages.
# See: https://wiki.debian.org/SupportedArchitectures
@ -107,14 +117,10 @@ matrix_user_gid: ~
matrix_base_data_path: "/matrix"
matrix_base_data_path_mode: "750"
matrix_bin_path: "{{ matrix_base_data_path }}/bin"
matrix_static_files_base_path: "{{ matrix_base_data_path }}/static-files"
# This is now unused. We keep it so that cleanup tasks can use it.
# To be removed in the future.
matrix_cron_path: "/etc/cron.d"
matrix_local_bin_path: "/usr/local/bin"
matrix_host_command_sleep: "/usr/bin/env sleep"
matrix_host_command_chown: "/usr/bin/env chown"
matrix_host_command_fusermount: "/usr/bin/env fusermount"
@ -253,13 +259,8 @@ matrix_well_known_matrix_server_enabled: true
# See `matrix_homeserver_admin_contacts`, `matrix_homeserver_support_url`, etc.
matrix_well_known_matrix_support_enabled: false
# Controls whether Docker is automatically installed.
# If you change this to false you must install and update Docker manually. You also need to install the docker (https://pypi.org/project/docker/) Python package.
matrix_docker_installation_enabled: true
# Controls the Docker package that is installed.
# Possible values are "docker-ce" (default) and "docker.io" (Debian).
matrix_docker_package_name: docker-ce
matrix_homeserver_container_extra_arguments_auto: []
matrix_homeserver_app_service_config_files_auto: []
# Variables to Control which parts of our roles run.
run_postgres_import: true

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

@ -1,9 +0,0 @@
---
- name: Get rid of old files and directories
ansible.builtin.file:
path: "{{ item }}"
state: absent
with_items:
- "{{ matrix_base_data_path }}/environment-variables"
- "{{ matrix_base_data_path }}/scratchpad"

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

@ -1,37 +1,39 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/sanity_check.yml"
tags:
- always
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/clean_up_old_files.yml"
when: run_setup | bool
tags:
- setup-all
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/server_base/setup.yml"
when: run_setup | bool
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
tags:
- setup-all
- install-all
# This needs to always run, because it populates `matrix_user_uid` and `matrix_user_gid`,
# which are required by many other roles.
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_matrix_user.yml"
when: run_setup | bool
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_matrix_user.yml"
tags:
- always
- setup-system-user
- common
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_matrix_base.yml"
when: run_setup | bool
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_matrix_base.yml"
tags:
- setup-all
- install-all
- common
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_well_known.yml"
when: run_setup | bool
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_well_known.yml"
tags:
- setup-all
- setup-ma1sd
- setup-synapse
- setup-dendrite
- setup-conduit
- setup-nginx-proxy
- install-all
- install-ma1sd
- install-synapse
- install-dendrite
- install-conduit
- install-nginx-proxy

41
roles/custom/matrix-base/tasks/server_base/setup.yml
View File

@ -1,41 +0,0 @@
---
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/server_base/setup_redhat.yml"
when: ansible_os_family == 'RedHat' and ansible_distribution_major_version | int < 8
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/server_base/setup_redhat8.yml"
when: ansible_os_family == 'RedHat' and ansible_distribution_major_version | int > 7 and ansible_distribution_major_version | int < 30
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/server_base/setup_fedora.yml"
when: ansible_os_family == 'RedHat' and ansible_distribution_major_version | int > 30
- when: ansible_os_family == 'Debian'
block:
# ansible_lsb is only available if lsb-release is installed.
- name: Ensure lsb-release installed
ansible.builtin.apt:
name:
- lsb-release
state: present
update_cache: true
register: lsb_release_installation_result
- name: Reread ansible_lsb facts if lsb-release got installed
ansible.builtin.setup:
filter: ansible_lsb*
when: lsb_release_installation_result.changed
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/server_base/setup_debian.yml"
when: (ansible_os_family == 'Debian') and (ansible_lsb.id != 'Raspbian')
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/server_base/setup_raspbian.yml"
when: (ansible_os_family == 'Debian') and (ansible_lsb.id == 'Raspbian')
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/server_base/setup_archlinux.yml"
when: ansible_distribution == 'Archlinux'
- name: Ensure Docker is started and autoruns
ansible.builtin.service:
name: docker
state: started
enabled: true

16
roles/custom/matrix-base/tasks/server_base/setup_archlinux.yml
View File

@ -1,16 +0,0 @@
---
- name: Install host dependencies
community.general.pacman:
name:
- python-docker
- python-dnspython
state: present
update_cache: true
- name: Ensure Docker is installed
community.general.pacman:
name:
- docker
state: present
when: matrix_docker_installation_enabled | bool

34
roles/custom/matrix-base/tasks/server_base/setup_debian.yml
View File

@ -1,34 +0,0 @@
---
- name: Ensure APT usage dependencies are installed
ansible.builtin.apt:
name:
- apt-transport-https
- ca-certificates
- gnupg
state: present
update_cache: true
- name: Ensure Docker's APT key is trusted
ansible.builtin.apt_key:
url: "https://download.docker.com/linux/{{ ansible_distribution | lower }}/gpg"
id: 9DC858229FC7DD38854AE2D88D81803C0EBFCD88
state: present
register: add_repository_key
ignore_errors: true
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker repository is enabled
ansible.builtin.apt_repository:
repo: "deb [arch={{ matrix_debian_arch }}] https://download.docker.com/linux/{{ ansible_distribution | lower }} {{ ansible_distribution_release }} stable"
state: present
update_cache: true
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker is installed
ansible.builtin.apt:
name:
- "{{ matrix_docker_package_name }}"
- "python{{ '3' if ansible_python.version.major == 3 else '' }}-docker"
state: present
when: matrix_docker_installation_enabled | bool

32
roles/custom/matrix-base/tasks/server_base/setup_fedora.yml
View File

@ -1,32 +0,0 @@
---
- name: Ensure Docker repository is enabled
ansible.builtin.template:
src: "{{ role_path }}/files/yum.repos.d/{{ item }}"
dest: "/etc/yum.repos.d/docker-ce.repo"
owner: "root"
group: "root"
mode: 0644
with_items:
- docker-ce-fedora.repo
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker's RPM key is trusted
ansible.builtin.rpm_key:
state: present
key: https://download.docker.com/linux/fedora/gpg
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker is installed
ansible.builtin.yum:
name:
- "{{ matrix_docker_package_name }}"
- python3-pip
state: present
when: matrix_docker_installation_enabled | bool
- name: Ensure Docker-Py is installed
ansible.builtin.pip:
name: docker-py
state: present
when: matrix_docker_installation_enabled | bool

34
roles/custom/matrix-base/tasks/server_base/setup_raspbian.yml
View File

@ -1,34 +0,0 @@
---
- name: Ensure APT usage dependencies are installed
ansible.builtin.apt:
name:
- apt-transport-https
- ca-certificates
- gnupg
state: present
update_cache: true
- name: Ensure Docker's APT key is trusted
ansible.builtin.apt_key:
url: https://download.docker.com/linux/raspbian/gpg
id: 9DC858229FC7DD38854AE2D88D81803C0EBFCD88
state: present
register: add_repository_key
ignore_errors: true
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker repository is enabled
ansible.builtin.apt_repository:
repo: "deb [arch={{ matrix_debian_arch }}] https://download.docker.com/linux/raspbian {{ ansible_distribution_release }} stable"
state: present
update_cache: true
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker is installed
ansible.builtin.apt:
name:
- "{{ matrix_docker_package_name }}"
- "python{{ '3' if ansible_python.version.major == 3 else '' }}-docker"
state: present
when: matrix_docker_installation_enabled | bool

24
roles/custom/matrix-base/tasks/server_base/setup_redhat.yml
View File

@ -1,24 +0,0 @@
---
- name: Ensure Docker repository is enabled
ansible.builtin.template:
src: "{{ role_path }}/files/yum.repos.d/docker-ce-centos.repo"
dest: "/etc/yum.repos.d/docker-ce.repo"
owner: "root"
group: "root"
mode: 0644
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker's RPM key is trusted
ansible.builtin.rpm_key:
state: present
key: https://download.docker.com/linux/centos/gpg
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker is installed
ansible.builtin.yum:
name:
- "{{ matrix_docker_package_name }}"
- docker-python
state: present
when: matrix_docker_installation_enabled | bool

37
roles/custom/matrix-base/tasks/server_base/setup_redhat8.yml
View File

@ -1,37 +0,0 @@
---
- name: Ensure Docker repository is enabled
ansible.builtin.template:
src: "{{ role_path }}/files/yum.repos.d/docker-ce-centos.repo"
dest: "/etc/yum.repos.d/docker-ce.repo"
owner: "root"
group: "root"
mode: 0644
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure Docker's RPM key is trusted
ansible.builtin.rpm_key:
state: present
key: https://download.docker.com/linux/centos/gpg
when: matrix_docker_installation_enabled | bool and matrix_docker_package_name == 'docker-ce'
- name: Ensure EPEL is installed
ansible.builtin.yum:
name:
- epel-release
state: present
update_cache: true
- name: Ensure Docker is installed
ansible.builtin.yum:
name:
- "{{ matrix_docker_package_name }}"
- python3-pip
state: present
when: matrix_docker_installation_enabled | bool
- name: Ensure Docker-Py is installed
ansible.builtin.pip:
name: docker-py
state: present
when: matrix_docker_installation_enabled | bool

9
roles/custom/matrix-base/tasks/setup_matrix_base.yml
View File

@ -1,6 +1,6 @@
---
- name: Ensure Matrix base path exists
- name: Ensure Matrix base paths exists
ansible.builtin.file:
path: "{{ item }}"
state: directory
@ -9,14 +9,15 @@
group: "{{ matrix_user_groupname }}"
with_items:
- "{{ matrix_base_data_path }}"
- "{{ matrix_bin_path }}"
- name: Ensure Matrix network is created in Docker
community.docker.docker_network:
name: "{{ matrix_docker_network }}"
driver: bridge
- name: Ensure matrix-remove-all script created
- name: Ensure remove-all script created
ansible.builtin.template:
src: "{{ role_path }}/templates/usr-local-bin/matrix-remove-all.j2"
dest: "{{ matrix_local_bin_path }}/matrix-remove-all"
src: "{{ role_path }}/templates/bin/remove-all.j2"
dest: "{{ matrix_bin_path }}/remove-all"
mode: 0750

7
roles/custom/matrix-base/tasks/setup_matrix_user.yml
View File

@ -7,10 +7,6 @@
state: present
register: matrix_group
- name: Set Matrix Group GID Variable
ansible.builtin.set_fact:
matrix_user_gid: "{{ matrix_group.gid }}"
- name: Ensure Matrix user is created
ansible.builtin.user:
name: "{{ matrix_user_username }}"
@ -22,6 +18,7 @@
system: true
register: matrix_user
- name: Set Matrix Group UID Variable
- name: Initialize matrix_user_uid and matrix_user_gid
ansible.builtin.set_fact:
matrix_user_uid: "{{ matrix_user.uid }}"
matrix_user_gid: "{{ matrix_group.gid }}"

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

@ -5,21 +5,6 @@
msg: "You need to set a valid homeserver implementation in `matrix_homeserver_implementation`"
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
ansible.builtin.fail:
msg: "You are running on Ansible {{ ansible_version.string }}, which is not supported. See our guide about Ansible: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/ansible.md"
when:
- "(ansible_version.major < 2) or (ansible_version.major == 2 and ansible_version.minor < 7) or (ansible_version.major == 2 and ansible_version.minor == 7 and ansible_version.revision < 1)"
# Though we do not support Ansible 2.9.6 which is buggy
- name: Fail if running on Ansible 2.9.6 on Ubuntu
ansible.builtin.fail:
msg: "You are running on Ansible {{ ansible_version.string }}, which is not supported. See our guide about Ansible: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/ansible.md"
when:
- ansible_distribution == 'Ubuntu'
- "ansible_version.major == 2 and ansible_version.minor == 9 and ansible_version.revision == 6"
- name: (Deprecation) Catch and report renamed settings
ansible.builtin.fail:
msg: >-
@ -32,6 +17,7 @@
- {'old': 'hostname_matrix', 'new': 'matrix_server_fqn_matrix'}
- {'old': 'hostname_riot', 'new': 'matrix_server_fqn_element'}
- {'old': 'matrix_server_fqn_riot', 'new': 'matrix_server_fqn_element'}
- {'old': 'matrix_local_bin_path', 'new': '<there is no global bin path anymore - each role has its own>'}
# We have a dedicated check for this variable, because we'd like to have a custom (friendlier) message.
- name: Fail if matrix_homeserver_generic_secret_key is undefined
@ -40,6 +26,8 @@
The `matrix_homeserver_generic_secret_key` variable must be defined and have a non-null and non-empty value.
If you're observing this error on a new installation, you should ensure that the `matrix_homeserver_generic_secret_key` is defined.
If you think you've defined it, but are still getting this error, then it's likely that you have a typo
in your domain name in `inventory/hosts` or in one of the directories leading up to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file.
If you're observing this error on an existing homeserver installation, you can fix it easily and in a backward-compatible way by adding
`{% raw %}matrix_homeserver_generic_secret_key: "{{ matrix_synapse_macaroon_secret_key }}"{% endraw %}`
@ -55,8 +43,14 @@
- {'var': matrix_server_fqn_element, 'value': "{{ matrix_server_fqn_element | default('') }}"}
- {'var': matrix_homeserver_container_url, 'value': "{{ matrix_homeserver_container_url | default('') }}"}
- {'var': matrix_homeserver_container_federation_url, 'value': "{{ matrix_homeserver_container_federation_url | default('') }}"}
- {'var': matrix_architecture, 'value': "{{ matrix_architecture | default('') }}"}
when: "item.value is none or item.value == ''"
- name: Fail if matrix_architecture is set incorrectly
ansible.builtin.fail:
msg: "Detected that variable matrix_architecture {{ matrix_architecture }} appears to be set incorrectly. See docs/alternative-architectures.md. Server appears to be {{ ansible_architecture }}."
when: matrix_architecture not in ['amd64', 'arm32', 'arm64']
- name: Fail if uppercase domain used
ansible.builtin.fail:
msg: "Detected that you're using an uppercase domain name - `{{ item }}`. This will cause trouble. Please use all-lowercase!"
@ -66,20 +60,6 @@
- "{{ matrix_server_fqn_element }}"
when: "item != item | lower"
- name: Fail if using python2 on Archlinux
ansible.builtin.fail:
msg: "Detected that you're using python2 when installing onto Archlinux. Archlinux by default only supports python3."
when:
- ansible_distribution == 'Archlinux'
- ansible_python.version.major != 3
- name: Fail if architecture is set incorrectly
ansible.builtin.fail:
msg: "Detected that variable matrix_architecture {{ matrix_architecture }} appears to be set incorrectly. See docs/alternative-architectures.md. Server appears to be {{ ansible_architecture }}."
when: (ansible_architecture == "x86_64" and matrix_architecture != "amd64") or
(ansible_architecture == "aarch64" and matrix_architecture != "arm64") or
(ansible_architecture.startswith("armv") and matrix_architecture != "arm32")
- name: Fail if encountering usage of removed role (mx-puppet-skype)
ansible.builtin.fail:
msg: >-

2
roles/custom/matrix-base/templates/usr-local-bin/matrix-remove-all.j2 → roles/custom/matrix-base/templates/bin/remove-all.j2
View File

@ -23,8 +23,6 @@ else
systemctl daemon-reload
echo "Remove matrix scripts"
find {{ matrix_local_bin_path }}/ -name "matrix-*" -delete
echo "Remove unused Docker images and resources"
docker system prune -af
echo "Remove Docker matrix network (should be gone already, but ..)"

5
roles/custom/matrix-base/templates/static-files/well-known/matrix-client.j2
View File

@ -24,6 +24,11 @@
},
"im.vector.riot.jitsi": {
"preferredDomain": {{ matrix_client_element_jitsi_preferredDomain|to_json }}
}
{% endif %}
{% if matrix_client_element_location_sharing_enabled %},
"m.tile_server": {
"map_style_url": "https://{{ matrix_server_fqn_element }}/map_style.json"
}
{% endif %}
,

7
roles/custom/matrix-base/vars/main.yml
View File

@ -1,7 +0,0 @@
---
# This will contain a list of enabled services that the playbook is managing.
# Each component is expected to append its service name to this list.
matrix_systemd_services_list: []
matrix_homeserver_container_runtime_injected_arguments: []
matrix_homeserver_app_service_runtime_injected_config_files: []

2
roles/custom/matrix-bot-buscarron/defaults/main.yml
View File

@ -43,7 +43,7 @@ matrix_bot_buscarron_sqlite_database_path_in_container: "/data/bot.db"
matrix_bot_buscarron_database_username: 'buscarron'
matrix_bot_buscarron_database_password: 'some-password'
matrix_bot_buscarron_database_hostname: 'matrix-postgres'
matrix_bot_buscarron_database_hostname: ''
matrix_bot_buscarron_database_port: 5432
matrix_bot_buscarron_database_name: 'buscarron'

5
roles/custom/matrix-bot-buscarron/tasks/init.yml
View File

@ -1,5 +0,0 @@
---
- ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-buscarron.service'] }}"
when: matrix_bot_buscarron_enabled | bool

19
roles/custom/matrix-bot-buscarron/tasks/main.yml
View File

@ -1,22 +1,19 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup | bool and matrix_bot_buscarron_enabled | bool"
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_buscarron_enabled | bool"
tags:
- setup-all
- setup-bot-buscarron
- install-all
- install-bot-buscarron
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_buscarron_enabled | bool"
tags:
- setup-all
- setup-bot-buscarron
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup | bool and not matrix_bot_buscarron_enabled | bool"
tags:
- setup-all

18
roles/custom/matrix-bot-buscarron/tasks/setup_install.yml
View File

@ -11,8 +11,11 @@
- when: "matrix_bot_buscarron_sqlite_database_path_local_stat_result.stat.exists | bool"
block:
- ansible.builtin.set_fact:
matrix_postgres_db_migration_request:
- ansible.builtin.include_role:
name: galaxy/com.devture.ansible.role.postgres
tasks_from: migrate_db_to_postgres
vars:
devture_postgres_db_migration_request:
src: "{{ matrix_bot_buscarron_sqlite_database_path_local }}"
dst: "{{ matrix_bot_buscarron_database_connection_string }}"
caller: "{{ role_path | basename }}"
@ -20,10 +23,6 @@
engine_old: 'sqlite'
systemd_services_to_stop: ['matrix-bot-buscarron.service']
- ansible.builtin.import_role:
name: custom/matrix-postgres
tasks_from: migrate_db_to_postgres
- ansible.builtin.set_fact:
matrix_bot_buscarron_requires_restart: true
@ -89,15 +88,10 @@
src: "{{ role_path }}/templates/systemd/matrix-bot-buscarron.service.j2"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-buscarron.service"
mode: 0644
register: matrix_bot_buscarron_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-buscarron.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_buscarron_systemd_service_result.changed | bool"
- name: Ensure matrix-bot-buscarron.service restarted, if necessary
ansible.builtin.service:
name: "matrix-bot-buscarron.service"
state: restarted
daemon_reload: true
when: "matrix_bot_buscarron_requires_restart | bool"

15
roles/custom/matrix-bot-buscarron/tasks/setup_uninstall.yml
View File

@ -5,32 +5,21 @@
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-buscarron.service"
register: matrix_bot_buscarron_service_stat
- when: matrix_bot_buscarron_service_stat.stat.exists | bool
block:
- name: Ensure matrix-buscarron is stopped
ansible.builtin.service:
name: matrix-bot-buscarron
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_bot_buscarron_service_stat.stat.exists | bool"
- name: Ensure matrix-bot-buscarron.service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-buscarron.service"
state: absent
when: "matrix_bot_buscarron_service_stat.stat.exists | bool"
- name: Ensure systemd reloaded after matrix-bot-buscarron.service removal
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_buscarron_service_stat.stat.exists | bool"
- name: Ensure Matrix buscarron paths don't exist
ansible.builtin.file:
path: "{{ matrix_bot_buscarron_base_path }}"
state: absent
- name: Ensure buscarron Docker image doesn't exist
community.docker.docker_image:
name: "{{ matrix_bot_buscarron_docker_image }}"
state: absent

9
roles/custom/matrix-bot-buscarron/tasks/validate_config.yml
View File

@ -1,9 +1,10 @@
---
- name: Fail if required settings not defined
- name: Fail if required Buscarron settings not defined
ansible.builtin.fail:
msg: >-
You need to define a required configuration setting (`{{ item }}`).
when: "vars[item] == ''"
You need to define a required configuration setting (`{{ item.name }}`).
when: "item.when | bool and vars[item.name] == ''"
with_items:
- "matrix_bot_buscarron_password"
- {'name': 'matrix_bot_buscarron_password', when: true}
- {'name': 'matrix_bot_buscarron_database_hostname', when: "{{ matrix_bot_buscarron_database_engine == 'postgres' }}"}

5
roles/custom/matrix-bot-go-neb/tasks/init.yml
View File

@ -1,5 +0,0 @@
---
- ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-go-neb.service'] }}"
when: matrix_bot_go_neb_enabled | bool

19
roles/custom/matrix-bot-go-neb/tasks/main.yml
View File

@ -1,22 +1,19 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup | bool and matrix_bot_go_neb_enabled | bool"
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_go_neb_enabled | bool"
tags:
- setup-all
- setup-bot-go-neb
- install-all
- install-bot-go-neb
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_go_neb_enabled | bool"
tags:
- setup-all
- setup-bot-go-neb
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup | bool and not matrix_bot_go_neb_enabled | bool"
tags:
- setup-all

6
roles/custom/matrix-bot-go-neb/tasks/setup_install.yml
View File

@ -42,13 +42,9 @@
mode: 0644
register: matrix_bot_go_neb_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-go-neb.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_go_neb_systemd_service_result.changed | bool"
- name: Ensure matrix-bot-go-neb.service restarted, if necessary
ansible.builtin.service:
name: "matrix-bot-go-neb.service"
state: restarted
daemon_reload: true
when: "matrix_bot_go_neb_requires_restart | bool"

15
roles/custom/matrix-bot-go-neb/tasks/setup_uninstall.yml
View File

@ -5,32 +5,21 @@
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-go-neb.service"
register: matrix_bot_go_neb_service_stat
- when: matrix_bot_go_neb_service_stat.stat.exists | bool
block:
- name: Ensure matrix-go-neb is stopped
ansible.builtin.service:
name: matrix-bot-go-neb
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_bot_go_neb_service_stat.stat.exists | bool"
- name: Ensure matrix-bot-go-neb.service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-go-neb.service"
state: absent
when: "matrix_bot_go_neb_service_stat.stat.exists | bool"
- name: Ensure systemd reloaded after matrix-bot-go-neb.service removal
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_go_neb_service_stat.stat.exists | bool"
- name: Ensure Matrix go-neb paths don't exist
ansible.builtin.file:
path: "{{ matrix_bot_go_neb_base_path }}"
state: absent
- name: Ensure go-neb Docker image doesn't exist
community.docker.docker_image:
name: "{{ matrix_bot_go_neb_docker_image }}"
state: absent

2
roles/custom/matrix-bot-honoroit/defaults/main.yml
View File

@ -43,7 +43,7 @@ matrix_bot_honoroit_sqlite_database_path_in_container: "/data/bot.db"
matrix_bot_honoroit_database_username: 'honoroit'
matrix_bot_honoroit_database_password: 'some-password'
matrix_bot_honoroit_database_hostname: 'matrix-postgres'
matrix_bot_honoroit_database_hostname: ''
matrix_bot_honoroit_database_port: 5432
matrix_bot_honoroit_database_name: 'honoroit'

5
roles/custom/matrix-bot-honoroit/tasks/init.yml
View File

@ -1,5 +0,0 @@
---
- ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-honoroit.service'] }}"
when: matrix_bot_honoroit_enabled | bool

19
roles/custom/matrix-bot-honoroit/tasks/main.yml
View File

@ -1,22 +1,19 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup | bool and matrix_bot_honoroit_enabled | bool"
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_honoroit_enabled | bool"
tags:
- setup-all
- setup-bot-honoroit
- install-all
- install-bot-honoroit
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_honoroit_enabled | bool"
tags:
- setup-all
- setup-bot-honoroit
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
- block:
- ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup | bool and not matrix_bot_honoroit_enabled | bool"
tags:
- setup-all

17
roles/custom/matrix-bot-honoroit/tasks/setup_install.yml
View File

@ -11,8 +11,11 @@
- when: "matrix_bot_honoroit_sqlite_database_path_local_stat_result.stat.exists | bool"
block:
- ansible.builtin.set_fact:
matrix_postgres_db_migration_request:
- ansible.builtin.include_role:
name: galaxy/com.devture.ansible.role.postgres
tasks_from: migrate_db_to_postgres
vars:
devture_postgres_db_migration_request:
src: "{{ matrix_bot_honoroit_sqlite_database_path_local }}"
dst: "{{ matrix_bot_honoroit_database_connection_string }}"
caller: "{{ role_path | basename }}"
@ -20,10 +23,6 @@
engine_old: 'sqlite'
systemd_services_to_stop: ['matrix-bot-honoroit.service']
- ansible.builtin.import_role:
name: custom/matrix-postgres
tasks_from: migrate_db_to_postgres
- ansible.builtin.set_fact:
matrix_bot_honoroit_requires_restart: true
@ -91,13 +90,9 @@
mode: 0644
register: matrix_bot_honoroit_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-honoroit.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_honoroit_systemd_service_result.changed | bool"
- name: Ensure matrix-bot-honoroit.service restarted, if necessary
ansible.builtin.service:
name: "matrix-bot-honoroit.service"
state: restarted
daemon_reload: true
when: "matrix_bot_honoroit_requires_restart | bool"

15
roles/custom/matrix-bot-honoroit/tasks/setup_uninstall.yml
View File

@ -5,32 +5,21 @@
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-honoroit.service"
register: matrix_bot_honoroit_service_stat
- when: matrix_bot_honoroit_service_stat.stat.exists | bool
block:
- name: Ensure matrix-honoroit is stopped
ansible.builtin.service:
name: matrix-bot-honoroit
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_bot_honoroit_service_stat.stat.exists | bool"
- name: Ensure matrix-bot-honoroit.service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-honoroit.service"
state: absent
when: "matrix_bot_honoroit_service_stat.stat.exists | bool"
- name: Ensure systemd reloaded after matrix-bot-honoroit.service removal
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_honoroit_service_stat.stat.exists | bool"
- name: Ensure Matrix honoroit paths don't exist
ansible.builtin.file:
path: "{{ matrix_bot_honoroit_base_path }}"
state: absent
- name: Ensure honoroit Docker image doesn't exist
community.docker.docker_image:
name: "{{ matrix_bot_honoroit_docker_image }}"
state: absent

11
roles/custom/matrix-bot-honoroit/tasks/validate_config.yml
View File

@ -1,10 +1,11 @@
---
- name: Fail if required settings not defined
- name: Fail if required honoroit settings not defined
ansible.builtin.fail:
msg: >-
You need to define a required configuration setting (`{{ item }}`).
when: "vars[item] == ''"
You need to define a required configuration setting (`{{ item.name }}`).
when: "item.when | bool and vars[item.name] == ''"
with_items:
- "matrix_bot_honoroit_password"
- "matrix_bot_honoroit_roomid"
- {'name': 'matrix_bot_honoroit_password', when: true}
- {'name': 'matrix_bot_honoroit_roomid', when: true}
- {'name': 'matrix_bot_honoroit_database_hostname', when: "{{ matrix_bot_honoroit_database_engine == 'postgres' }}"}

5
roles/custom/matrix-bot-matrix-registration-bot/tasks/init.yml
View File

@ -1,5 +0,0 @@
---
- ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-matrix-registration-bot.service'] }}"
when: matrix_bot_matrix_registration_bot_enabled | bool

23
roles/custom/matrix-bot-matrix-registration-bot/tasks/main.yml
View File

@ -1,23 +1,20 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- block:
- when: matrix_bot_matrix_registration_bot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup | bool and matrix_bot_matrix_registration_bot_enabled | bool"
- when: matrix_bot_matrix_registration_bot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
tags:
- setup-all
- setup-bot-matrix-registration-bot
- install-all
- install-bot-matrix-registration-bot
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_matrix_registration_bot_enabled | bool"
tags:
- setup-all
- setup-bot-matrix-registration-bot
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup | bool and not matrix_bot_matrix_registration_bot_enabled | bool"
- block:
- when: not matrix_bot_matrix_registration_bot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
tags:
- setup-all
- setup-bot-matrix-registration-bot

11
roles/custom/matrix-bot-matrix-registration-bot/tasks/setup_install.yml
View File

@ -61,14 +61,3 @@
src: "{{ role_path }}/templates/systemd/matrix-bot-matrix-registration-bot.service.j2"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-matrix-registration-bot.service"
mode: 0644
register: matrix_bot_matrix_registration_bot_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-matrix-registration-bot.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_matrix_registration_bot_systemd_service_result.changed | bool"
- name: Ensure matrix-bot-matrix-registration-bot.service restarted, if necessary
ansible.builtin.service:
name: "matrix-bot-matrix-registration-bot.service"
state: restarted

15
roles/custom/matrix-bot-matrix-registration-bot/tasks/setup_uninstall.yml
View File

@ -5,32 +5,21 @@
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-matrix-registration-bot.service"
register: matrix_bot_matrix_registration_bot_service_stat
- when: matrix_bot_matrix_registration_bot_service_stat.stat.exists | bool
block:
- name: Ensure matrix-matrix-registration-bot is stopped
ansible.builtin.service:
name: matrix-bot-matrix-registration-bot
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_bot_matrix_registration_bot_service_stat.stat.exists | bool"
- name: Ensure matrix-bot-matrix-registration-bot.service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-matrix-registration-bot.service"
state: absent
when: "matrix_bot_matrix_registration_bot_service_stat.stat.exists | bool"
- name: Ensure systemd reloaded after matrix-bot-matrix-registration-bot.service removal
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_matrix_registration_bot_service_stat.stat.exists | bool"
- name: Ensure Matrix matrix-registration-bot paths don't exist
ansible.builtin.file:
path: "{{ matrix_bot_matrix_registration_bot_base_path }}"
state: absent
- name: Ensure matrix-registration-bot Docker image doesn't exist
community.docker.docker_image:
name: "{{ matrix_bot_matrix_registration_bot_docker_image }}"
state: absent

2
roles/custom/matrix-bot-matrix-reminder-bot/defaults/main.yml
View File

@ -44,7 +44,7 @@ matrix_bot_matrix_reminder_bot_sqlite_database_path_in_container: "/data/bot.db"
matrix_bot_matrix_reminder_bot_database_username: 'matrix_reminder_bot'
matrix_bot_matrix_reminder_bot_database_password: 'some-password'
matrix_bot_matrix_reminder_bot_database_hostname: 'matrix-postgres'
matrix_bot_matrix_reminder_bot_database_hostname: ''
matrix_bot_matrix_reminder_bot_database_port: 5432
matrix_bot_matrix_reminder_bot_database_name: 'matrix_reminder_bot'

5
roles/custom/matrix-bot-matrix-reminder-bot/tasks/init.yml
View File

@ -1,5 +0,0 @@
---
- ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-matrix-reminder-bot.service'] }}"
when: matrix_bot_matrix_reminder_bot_enabled | bool

23
roles/custom/matrix-bot-matrix-reminder-bot/tasks/main.yml
View File

@ -1,23 +1,20 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- block:
- when: matrix_bot_matrix_reminder_bot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup | bool and matrix_bot_matrix_reminder_bot_enabled | bool"
- when: matrix_bot_matrix_reminder_bot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
tags:
- setup-all
- setup-bot-matrix-reminder-bot
- install-all
- install-bot-matrix-reminder-bot
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_matrix_reminder_bot_enabled | bool"
tags:
- setup-all
- setup-bot-matrix-reminder-bot
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup | bool and not matrix_bot_matrix_reminder_bot_enabled | bool"
- block:
- when: not matrix_bot_matrix_reminder_bot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
tags:
- setup-all
- setup-bot-matrix-reminder-bot

17
roles/custom/matrix-bot-matrix-reminder-bot/tasks/setup_install.yml
View File

@ -12,8 +12,11 @@
- when: "matrix_bot_matrix_reminder_bot_sqlite_database_path_local_stat_result.stat.exists | bool"
block:
- ansible.builtin.set_fact:
matrix_postgres_db_migration_request:
- ansible.builtin.include_role:
name: galaxy/com.devture.ansible.role.postgres
tasks_from: migrate_db_to_postgres
vars:
devture_postgres_db_migration_request:
src: "{{ matrix_bot_matrix_reminder_bot_sqlite_database_path_local }}"
dst: "{{ matrix_bot_matrix_reminder_bot_database_connection_string }}"
caller: "{{ role_path | basename }}"
@ -21,10 +24,6 @@
engine_old: 'sqlite'
systemd_services_to_stop: ['matrix-bot-matrix-reminder-bot.service']
- ansible.builtin.import_role:
name: custom/matrix-postgres
tasks_from: migrate_db_to_postgres
- ansible.builtin.set_fact:
matrix_bot_matrix_reminder_bot_requires_restart: true
@ -92,13 +91,9 @@
mode: 0644
register: matrix_bot_matrix_reminder_bot_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-matrix-reminder-bot.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_matrix_reminder_bot_systemd_service_result.changed | bool"
- name: Ensure matrix-bot-matrix-reminder-bot.service restarted, if necessary
ansible.builtin.service:
name: "matrix-bot-matrix-reminder-bot.service"
state: restarted
daemon_reload: true
when: "matrix_bot_matrix_reminder_bot_requires_restart | bool"

15
roles/custom/matrix-bot-matrix-reminder-bot/tasks/setup_uninstall.yml
View File

@ -5,32 +5,21 @@
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-matrix-reminder-bot.service"
register: matrix_bot_matrix_reminder_bot_service_stat
- when: matrix_bot_matrix_reminder_bot_service_stat.stat.exists | bool
block:
- name: Ensure matrix-matrix-reminder-bot is stopped
ansible.builtin.service:
name: matrix-bot-matrix-reminder-bot
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_bot_matrix_reminder_bot_service_stat.stat.exists | bool"
- name: Ensure matrix-bot-matrix-reminder-bot.service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-matrix-reminder-bot.service"
state: absent
when: "matrix_bot_matrix_reminder_bot_service_stat.stat.exists | bool"
- name: Ensure systemd reloaded after matrix-bot-matrix-reminder-bot.service removal
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_matrix_reminder_bot_service_stat.stat.exists | bool"
- name: Ensure Matrix matrix-reminder-bot paths don't exist
ansible.builtin.file:
path: "{{ matrix_bot_matrix_reminder_bot_base_path }}"
state: absent
- name: Ensure matrix-reminder-bot Docker image doesn't exist
community.docker.docker_image:
name: "{{ matrix_bot_matrix_reminder_bot_docker_image }}"
state: absent

11
roles/custom/matrix-bot-matrix-reminder-bot/tasks/validate_config.yml
View File

@ -1,15 +1,16 @@
---
- name: Fail if required settings not defined
- name: Fail if required matrix-reminder-bot settings not defined
ansible.builtin.fail:
msg: >-
You need to define a required configuration setting (`{{ item }}`).
when: "vars[item] == ''"
when: "item.when | bool and vars[item.name] == ''"
with_items:
- "matrix_bot_matrix_reminder_bot_matrix_user_password"
- "matrix_bot_matrix_reminder_bot_reminders_timezone"
- {'name': 'matrix_bot_matrix_reminder_bot_matrix_user_password', when: true}
- {'name': 'matrix_bot_matrix_reminder_bot_reminders_timezone', when: true}
- {'name': 'matrix_bot_matrix_reminder_bot_database_hostname', when: "{{ matrix_bot_matrix_reminder_bot_database_engine == 'postgres' }}"}
- name: (Deprecation) Catch and report renamed settings
- name: (Deprecation) Catch and report renamed matrix-reminder-bot settings
ansible.builtin.fail:
msg: >-
Your configuration contains a variable, which now has a different name.

2
roles/custom/matrix-bot-maubot/defaults/main.yml
View File

@ -27,7 +27,7 @@ matrix_bot_maubot_sqlite_database_path_in_container: "/data/maubot.db"
matrix_bot_maubot_database_username: matrix_bot_maubot
matrix_bot_maubot_database_password: ~
matrix_bot_maubot_database_hostname: 'matrix-postgres'
matrix_bot_maubot_database_hostname: ''
matrix_bot_maubot_database_port: 5432
matrix_bot_maubot_database_name: matrix_bot_maubot

5
roles/custom/matrix-bot-maubot/tasks/init.yml → roles/custom/matrix-bot-maubot/tasks/inject_into_nginx_proxy.yml
View File

@ -1,10 +1,5 @@
---
- name: Add maubot to the systemd service list
ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-maubot.service'] }}"
when: matrix_bot_maubot_enabled | bool
- name: Configure nginx for maubot
block:
- name: Generate Maubot proxying configuration for matrix-nginx-proxy

30
roles/custom/matrix-bot-maubot/tasks/main.yml
View File

@ -1,23 +1,29 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
- block:
- when: matrix_bot_maubot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/inject_into_nginx_proxy.yml"
tags:
- always
- setup-all
- setup-nginx-proxy
- install-all
- install-nginx-proxy
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup|bool and matrix_bot_maubot_enabled|bool"
- block:
- when: matrix_bot_maubot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
- when: matrix_bot_maubot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
tags:
- setup-all
- setup-bot-maubot
- install-all
- install-bot-maubot
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup|bool and matrix_bot_maubot_enabled|bool"
tags:
- setup-all
- setup-bot-maubot
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup|bool and not matrix_bot_maubot_enabled|bool"
- block:
- when: not matrix_bot_maubot_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
tags:
- setup-all
- setup-bot-maubot

6
roles/custom/matrix-bot-maubot/tasks/setup_install.yml
View File

@ -65,9 +65,3 @@
src: "{{ role_path }}/templates/systemd/matrix-bot-maubot.service.j2"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-maubot.service"
mode: 0644
register: matrix_bot_maubot_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-maubot.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_maubot_systemd_service_result.changed|bool"

15
roles/custom/matrix-bot-maubot/tasks/setup_uninstall.yml
View File

@ -5,32 +5,21 @@
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-maubot.service"
register: matrix_bot_maubot_service_stat
- when: matrix_bot_maubot_service_stat.stat.exists | bool
block:
- name: Ensure matrix-bot-maubot is stopped
ansible.builtin.service:
name: matrix-bot-maubot
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_bot_maubot_service_stat.stat.exists | bool"
- name: Ensure matrix-bot-maubot.service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-bot-maubot.service"
state: absent
when: "matrix_bot_maubot_service_stat.stat.exists | bool"
- name: Ensure systemd reloaded after matrix-bot-maubot.service removal
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_maubot_service_stat.stat.exists | bool"
- name: Ensure Matrix maubot paths don't exist
ansible.builtin.file:
path: "{{ matrix_bot_maubot_base_path }}"
state: absent
- name: Ensure maubot Docker image doesn't exist
community.docker.docker_image:
name: "{{ matrix_bot_maubot_docker_image }}"
state: absent

11
roles/custom/matrix-bot-maubot/tasks/validate_config.yml
View File

@ -1,10 +1,11 @@
---
- name: Fail if required settings not defined
- name: Fail if required maubot settings not defined
ansible.builtin.fail:
msg: >-
You need to define a required configuration setting (`{{ item }}`).
when: "vars[item] == ''"
You need to define a required configuration setting (`{{ item.name }}`).
when: "item.when | bool and vars[item.name] == ''"
with_items:
- matrix_bot_maubot_unshared_secret
- matrix_bot_maubot_admins
- {'name': 'matrix_bot_maubot_unshared_secret', when: true}
- {'name': 'matrix_bot_maubot_admins', when: true}
- {'name': 'matrix_bot_maubot_database_hostname', when: "{{ matrix_bot_maubot_database_engine == 'postgres' }}"}

2
roles/custom/matrix-bot-mjolnir/defaults/main.yml
View File

@ -4,7 +4,7 @@
matrix_bot_mjolnir_enabled: true
matrix_bot_mjolnir_version: "v1.5.0"
matrix_bot_mjolnir_version: "v1.6.1"
matrix_bot_mjolnir_container_image_self_build: false
matrix_bot_mjolnir_container_image_self_build_repo: "https://github.com/matrix-org/mjolnir.git"

11
roles/custom/matrix-bot-mjolnir/tasks/init.yml
View File

@ -1,11 +0,0 @@
---
# See https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1070
# and https://github.com/spantaleev/matrix-docker-ansible-deploy/commit/1ab507349c752042d26def3e95884f6df8886b74#commitcomment-51108407
- name: Fail if trying to self-build on Ansible < 2.8
ansible.builtin.fail:
msg: "To self-build the Mjolnir image, you should use Ansible 2.8 or higher. See docs/ansible.md"
when: "ansible_version.major == 2 and ansible_version.minor < 8 and matrix_bot_mjolnir_container_image_self_build and matrix_bot_mjolnir_enabled"
- ansible.builtin.set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-mjolnir.service'] }}"
when: matrix_bot_mjolnir_enabled | bool

23
roles/custom/matrix-bot-mjolnir/tasks/main.yml
View File

@ -1,23 +1,20 @@
---
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- block:
- when: matrix_bot_mjolnir_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup | bool and matrix_bot_mjolnir_enabled | bool"
- when: matrix_bot_mjolnir_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
tags:
- setup-all
- setup-bot-mjolnir
- install-all
- install-bot-mjolnir
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup | bool and matrix_bot_mjolnir_enabled | bool"
tags:
- setup-all
- setup-bot-mjolnir
- ansible.builtin.import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup | bool and not matrix_bot_mjolnir_enabled | bool"
- block:
- when: not matrix_bot_mjolnir_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
tags:
- setup-all
- setup-bot-mjolnir

6
roles/custom/matrix-bot-mjolnir/tasks/setup_install.yml
View File

@ -66,13 +66,9 @@
mode: 0644
register: matrix_bot_mjolnir_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-mjolnir.service installation
ansible.builtin.service:
daemon_reload: true
when: "matrix_bot_mjolnir_systemd_service_result.changed | bool"
- name: Ensure matrix-bot-mjolnir.service restarted, if necessary
ansible.builtin.service:
name: "matrix-bot-mjolnir.service"
state: restarted
daemon_reload: true
when: "matrix_bot_mjolnir_requires_restart | bool"

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