This repository contains Ansible playbooks for automating the deployment of Matrix (Synapse) server, Element (Matrix Web Client), and Keycloak SSO (Single Sign-On) in a Dockerized environment.
That is, it lets you join the Matrix network using your own @<username>:<your-domain>
identifier, all hosted on your own server.
We run all services in Docker containers, which lets us have a predictable and up-to-date setup, across multiple supported distros and architectures (x86/amd64 being recommended).
Installation (upgrades) and some maintenance tasks are automated using Ansible
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 includes optional or even some advanced components that you will most likely not need. Sticking with the defaults is the best choice, especially for a new installation. You can always re-run the playbook later to add or remove components.
The homeserver
is the backbone of the matrix system: in our deployment we use Synapse. Synapse, synapse stores your data and manages your presence in the Matrix network Link
We have multiple Web clients for Matrix that you can host on your own domains. in our deployment we use Element
:Element, Element is a Web UI, which is configured to connect to your own Synapse server by default Link
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 |
nginx | ✓ | Web server, listening on ports 80 and 443 - standing in front of all the other services. Using our own webserver is possible | Link |
Let's Encrypt | ✓ | Free SSL certificate, which secures the connection to the Synapse server and the Element web UI | Link |
Our Matrix/Keycloak installation utilizes the following components:
- Denbi OpenStack: An open-source cloud computing platform, providing scalable and flexible virtualized resources.
- Ceph Storage: A distributed object storage and file system designed to provide excellent performance, reliability, and scalability.
To configure and install Matrix on the server, follow the README in the docs/ directory.
- Matrix Server (Synapse): Decentralized communication platform.
- Element Chat Client: User-friendly interface for Matrix.
- Keycloak SSO: Centralized authentication and authorization.
- Ansible Playbooks: Automated deployment and configuration.
- Docker: Containerization for seamless deployment.
- de.NBI Cloud: Scalable cloud infrastructure.
- Ceph Storage: Distributed and scalable storage solution.
Before running the Ansible playbooks, ensure the following prerequisites are met:
- Ansible installed on the control machine where you plan to run the playbook.
- Docker installed on target servers.
- Target servers reachable from the control machine.
- SSH access configured for target servers.
- Cloud account and access credentials.
- Ceph storage configured in the cloud environment.
- Inventory File: Modify the inventory file with the target server details.
- In the
roles
repository, there are sub-repositories for Matrix, Keycloak, and nginix-proxy. Edit Variables, yml files, and config files located in each sub-repository to match your environment.
- Matrix Server (Synapse): http://matrix-server_ip
- Element Chat Client: http://your-element-client
- Keycloak SSO: http://keycloak_instance_ip
Bridges can be used to connect the matrix installation with third-party communication networks.
Name | Default? | Description | Documentation |
---|---|---|---|
mautrix-discord | x | Bridge for bridging Matrix server to Discord | Link |
mautrix-telegram | x | Bridge for bridging Matrix server to Telegram | Link |
mautrix-whatsapp | x | Bridge for bridging Matrix server to WhatsApp | Link |
mautrix-facebook | x | Bridge for bridging Matrix server to Facebook | Link |
mautrix-twitter | x | Bridge for bridging Matrix server to Twitter | Link |
mautrix-hangouts | x | Bridge for bridging Matrix server to Google Hangouts | Link |
mautrix-googlechat | x | Bridge for bridging Matrix server to Google Chat | Link |
mautrix-instagram | x | Bridge for bridging Matrix server to Instagram | Link |
mautrix-signal | x | Bridge for bridging Matrix server to Signal | Link |
beeper-linkedin | x | Bridge for bridging Matrix server to LinkedIn | Link |
matrix-appservice-irc | x | Bridge for bridging Matrix server to IRC | Link |
matrix-appservice-discord | x | Bridge for bridging Matrix server to Discord | Link |
matrix-appservice-slack | x | Bridge for bridging Matrix server to Slack | Link |
matrix-appservice-webhooks | x | Bridge for slack compatible webhooks (ConcourseCI, Slack etc. pp.) | Link |
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 |
matrix-sms-bridge | x | Bridge for bridging Matrix server to SMS | Link |
Heisenbridge | x | Bridge for bridging Matrix server to IRC bouncer-style | Link |
go-skype-bridge | x | Bridge for bridging Matrix server to Skype | Link |
mx-puppet-slack | x | Bridge for bridging Matrix server to Slack | Link |
mx-puppet-instagram | x | Bridge for Instagram-DMs (Instagram) | Link |
mx-puppet-twitter | x | Bridge for Twitter-DMs (Twitter) | Link |
mx-puppet-discord | x | Bridge for Discord | Link |
mx-puppet-groupme | x | Bridge for GroupMe | Link |
mx-puppet-steam | x | Bridge for Steam | Link |
Email2Matrix | x | Bridge for relaying email messages to Matrix rooms | Link |
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.
This project is based on the work of matrix ansible.