nfdi4plants / communicationplatform

Matrix server, Element Chat Client, and Keycloak SSO setup using Ansible and Docker

Purpose

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

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

Homeserver

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

Clients

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

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

Infrastructure Overview

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.

Installation

To configure and install Matrix on the server, follow the README in the docs/ directory.

Features

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

Prerequisites

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.

Configuration

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

Access URLs

• Matrix Server (Synapse): http://matrix-server_ip
• Element Chat Client: http://your-element-client
• Keycloak SSO: http://keycloak_instance_ip

Bridges

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

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.

Acknowledgments

This project is based on the work of matrix ansible.