94c1503a60
Squashed based on the work done in https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3042 commit 49932b8f3c17c4c4db7a884658c42f9a8b0550ca Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:21:31 2023 +0200 Fix syntax in matrix-bridge-hookshot/tasks/reset_encryption.yml Also, this task always does work and side-effects, so it should always report changes (`changed_when: true`). commit 6bdf7a9dcb73385313a1f34d52e27ad0cf95fb3e Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:12:41 2023 +0200 Add Hookshot validation task to ensure queue settings are set when encryption is enabled commit 8c531b7971b5dfd15ca541b5072b3eb8237cdcf9 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:10:17 2023 +0200 Add missing variables rewiring in group_vars/matrix_servers for Hookshot commit 7d26dabc2fe692f5e1236c0e250f85996f3fd0c2 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:08:19 2023 +0200 Add defaults for matrix_hookshot_queue_host and matrix_hookshot_queue_port commit 74f91138c92f1d1b69eb973803b882849e31a259 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:06:17 2023 +0200 Fix syntax for connecting to additional networks for Hookshot commit ca7b41f3f2d0c2900b2805294476f70e82461304 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:05:28 2023 +0200 Fix indentation and remove unnecessary if-statements commit ac4a918d58fc76e7332446a65609b56c5e4da00c Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:04:44 2023 +0200 Add missing --network for Hookshot This seems to have been removed by accident. commit 6a81fa208fca28951fc131cbf33b95ec78748a40 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:02:47 2023 +0200 Make automatic Redis enabling safer, when Hookshot encryption enabled If we ever default encryption to enabled for Hookshot, we only wish to force-enable Redis if Hookshot is actually enabled. commit 75a8e0f2a6cbf1562cb99c68ad1f20e4d47735ed Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:01:10 2023 +0200 Fix typo commit 98ad182eaccc7ab457ead4e03cc0d4f2a525a47d Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:37:40 2023 +0100 Add defaults for Hookshot's encryption commit 29fa9fab151f513908d3e45882003da107a63c93 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:35:11 2023 +0100 Improve wording of Hookshot's encryption section commit 4f835e0560012754d7ce0b56619a97c68a297992 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:28:52 2023 +0100 use safer mount options for the container's files commit 8c93327e25c5e6af2442c676d5f264d4051c80e2 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:26:01 2023 +0100 fix filename commit 03a7bb6e7798dd95f7894311e4dd34dfa09f70fa Merge: e55d7694 06047763 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:23:44 2023 +0100 Merge branch 'HarHarLinks/hookshot-encryption' of https://github.com/real-joshua/matrix-docker-ansible-deploy into HarHarLinks/hookshot-encryption commit 06047763bbd427dde117c6635ac7301198571158 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:15:54 2023 +0100 Update roles/custom/matrix-bridge-hookshot/templates/config.yml.j2 change the if statement to not require a variable with a length > 0 and add a filter to json for the redis host Co-authored-by: Slavi Pantaleev <slavi@devture.com> commit e55d769465bd299081464e68d34851729d42d5ff Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:13:50 2023 +0100 clarify that Redis is required, standardadise on Hookshot with an upper-case first letter for consistency commit 66706e4535704deba63e5aa2102f324f9b14dae3 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:08:20 2023 +0100 Update roles/custom/matrix-bridge-hookshot/templates/config.yml.j2 fix for a typo Co-authored-by: Slavi Pantaleev <slavi@devture.com> commit f6aaeb9a16f84409d31188e696885afed89fbdcc Merge: e5d34002 869dd33f Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 00:22:34 2023 +0100 Merge branch 'master' into HarHarLinks/hookshot-encryption commit e5d34002fd6c39c3e18df04e20d0c8b25475db78 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 00:09:27 2023 +0100 Add Jinja loop to allow adding multiple networks commit 69f947782d6e072c3edc4ee4c7d5ccf69eccf3fd Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Thu Dec 14 23:52:41 2023 +0100 split if statements for the message queue and experimental encryption support into seperate statements commit 4c13be1c89ffb1b06475c7da546f7956e67b36a1 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Thu Dec 14 23:31:19 2023 +0100 change variable name per spantaleev's suggestion (https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2979#discussion_r1379015551) commit 9905309aa9448f91297f8c7618bf62682eee2af7 Author: HarHarLinks <kim.brose@rwth-aachen.de> Date: Wed Nov 1 16:14:04 2023 +0100 amend docs commit 94abf2d5bde63919c6b5597f3142eea5fed73815 Author: HarHarLinks <kim.brose@rwth-aachen.de> Date: Wed Nov 1 16:05:22 2023 +0100 draft encryption support for hookshot
Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker
Purpose
This Ansible playbook is meant to help you run your own Matrix homeserver, along with the various services related to that.
That is, it lets you join the Matrix network using your own @<username>:<your-domain> identifier, all hosted on your own server (see prerequisites).
We run all services in Docker containers (see the container images we use), which lets us have a predictable and up-to-date setup, across multiple supported distros (see prerequisites) and architectures (x86/amd64 being recommended).
Installation (upgrades) and some maintenance tasks are automated using Ansible (see our Ansible guide).
Self-hosting or SaaS
This Ansible playbook tries to make self-hosting and maintaining a Matrix server fairly easy. Still, running any service smoothly requires knowledge, time and effort.
If you like the FOSS spirit of this Ansible playbook, but prefer to put the responsibility on someone else, you can also get a managed Matrix server from etke.cc - a service built on top of this Ansible playbook, which can help you run a Matrix server with ease.
If you like learning and experimentation, but would rather reduce future maintenance effort, you can even go for a hybrid approach - self-hosting manually using this Ansible playbook at first and then transferring server maintenance to etke.cc at a later time.
Supported services
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.
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 | ✓ | Storing your data and managing your presence in the Matrix network | Link |
| Conduit | x | Storing your data and managing your presence in the Matrix network. Conduit is a lightweight open-source server implementation of the Matrix Specification with a focus on easy setup and low system requirements | Link |
| Dendrite | x | Storing your data and managing your presence in the Matrix network. Dendrite is a second-generation Matrix homeserver written in Go, an alternative to Synapse. | Link |
Clients
Web clients for matrix that you can host on your own domains.
| Name | Default? | Description | Documentation |
|---|---|---|---|
| Element | ✓ | Web UI, which is configured to connect to your own Synapse server by default | Link |
| Hydrogen | x | Lightweight matrix client with legacy and mobile browser support | Link |
| Cinny | x | Simple, elegant and secure web client | Link |
| SchildiChat | x | Based on Element, with a more traditional instant messaging experience | Link |
Server Components
Services that run on the server to make the various parts of your installation work.
| Name | Default? | Description | Documentation |
|---|---|---|---|
| PostgreSQL | ✓ | Database for Synapse. Using an external PostgreSQL server is also possible. | Link |
| Coturn | ✓ | STUN/TURN server for WebRTC audio/video calls | Link |
| Traefik | ✓ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver is possible | Link |
| nginx | x | (Deprecated) Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Deprecated in favor of Traefik | Link |
| Let's Encrypt | ✓ | Free SSL certificate, which secures the connection to all components | Link |
| ma1sd | x | Matrix Identity Server | Link |
| Exim | ✓ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | Link |
| Dimension | x | An open source integrations manager for matrix clients | Link |
| Sygnal | x | Push gateway | Link |
| ntfy | x | Push notifications server | Link |
Authentication
Extend and modify how users are authenticated on your homeserver.
| Name | Default? | Description | Documentation |
|---|---|---|---|
| matrix-synapse-rest-auth (advanced) | x | REST authentication password provider module | Link |
| matrix-synapse-shared-secret-auth (advanced) | x | Password provider module | Link |
| matrix-synapse-ldap3 (advanced) | x | LDAP Auth password provider module | Link |
| matrix-ldap-registration-proxy (advanced) | x | A proxy that handles Matrix registration requests and forwards them to LDAP. | Link |
| matrix-registration | x | A simple python application to have a token based matrix registration | Link |
File Storage
Use alternative file storage to the default media_store folder.
| Name | Default? | Description | Documentation |
|---|---|---|---|
| Goofys | x | Amazon S3 (or other S3-compatible object store) storage for Synapse's content repository (media_store) files |
Link |
| synapse-s3-storage-provider | x | Amazon S3 (or other S3-compatible object store) storage for Synapse's content repository (media_store) files |
Link |
| matrix-media-repo | x | matrix-media-repo is a highly customizable multi-domain media repository for Matrix. Intended for medium to large deployments, this media repo de-duplicates media while being fully compliant with the specification. | Link |
Bridges
Bridges can be used to connect your matrix installation with third-party communication networks.
Bots
Bots provide various additional functionality to your installation.
| Name | Default? | Description | Documentation |
|---|---|---|---|
| matrix-reminder-bot | x | Bot for scheduling one-off & recurring reminders and alarms | Link |
| matrix-registration-bot | x | Bot for invitations by creating and managing registration tokens | Link |
| maubot | x | A plugin-based Matrix bot system | Link |
| honoroit | x | A helpdesk bot | Link |
| Postmoogle | x | Email to matrix bot | Link |
| Go-NEB | x | A multi functional bot written in Go | Link |
| Mjolnir | x | A moderation tool for Matrix | Link |
| Draupnir | x | A moderation tool for Matrix (Fork of Mjolnir) | Link |
| Buscarron | x | Web forms (HTTP POST) to matrix | Link |
| matrix-chatgpt-bot | x | ChatGPT from matrix | Link |
Administration
Services that help you in administrating and monitoring your matrix installation.
| Name | Default? | Description | Documentation |
|---|---|---|---|
| synapse-admin | x | A web UI tool for administrating users and rooms on your Matrix server | Link |
| Metrics and Graphs | x | Consists of the Prometheus time-series database server, the Prometheus node-exporter host metrics exporter, and the Grafana web UI | Link |
| Borg | x | Backups | Link |
| Rageshake | x | Bug report server | Link |
Misc
Various services that don't fit any other category.
| Name | Default? | Description | Documentation |
|---|---|---|---|
| sliding-sync | x | Sliding Sync support for clients which require it (e.g. Element X) | Link |
| synapse_auto_compressor | x | A cli tool that automatically compresses state_groups database table in background. |
Link |
| synapse-simple-antispam (advanced) | x | A spam checker module | Link |
| Matrix Corporal (advanced) | x | Reconciliator and gateway for a managed Matrix server | Link |
| Etherpad | x | An open source collaborative text editor | Link |
| Jitsi | x | An open source video-conferencing platform | Link |
| Cactus Comments | x | A federated comment system built on matrix | Link |
Installation
To configure and install Matrix on your own server, follow the README in the docs/ directory.
Changes
This playbook evolves over time, sometimes with backward-incompatible changes.
When updating the playbook, refer to the changelog to catch up with what's new.
Support
-
Matrix room: #matrix-docker-ansible-deploy:devture.com
-
IRC channel:
#matrix-docker-ansible-deployon the Libera Chat IRC network (irc.libera.chat:6697) -
GitHub issues: spantaleev/matrix-docker-ansible-deploy/issues
Related
You may also be interested in mash-playbook - another Ansible playbook for self-hosting non-Matrix services (see its List of supported services).
mash-playbook also makes use of Traefik as its reverse-proxy, so with minor interoperability adjustments, you can make matrix-docker-ansible-deploy and mash-playbook co-exist and host Matrix and non-Matrix services on the same server.