An Ansible role for automating the installation and configuration of a Matrix Synapse server to create secure organisational communication channels.
Matrix-Automation creates a functioning Synapse Homeserver by configuring five rootless Podman containers:
- A PostgreSQL Database - Storing Synapse Data
- A Synapse Homeserver - Federating Rooms
- A MA1SD Identity Server - Handling 3PID Mappings
- A MA1SD Extender API - Handling MA1SD Corporate Integration
- A Reverse Proxy - Link Connections to Synapse
It supports LDAP and SSO integrations for login and user search, and can federate with other Synapse homeservers and identity servers. The link to the Ansible Galaxy page is here, and example playbooks can be seen below.
Matrix-Automation uses Podman to create rootless containers. The Ansible Podman collection must therefore be installed before the role can be utilised:
ansible-galaxy collection install containers.podman
The Matrix-Automation role can then be installed via Ansible Galaxy using:
ansible-galaxy install cameronwickes.matrix_automation
The following variables are required by Matrix-Automation:
synapse_server_name: The domain name of the server you wish to setup Synapse on.postgres_user: The username for PostgreSQL container access.postgres_password: The password for PostgreSQL container access. Should be secure.synapse_federation_list: The list of other owned homeservers to federate room state and identity with.ma1sd_extender_username: The username for MA1SD extender access.ma1sd_extender_password: The password for MA1SD extender access.
These variables are necessary to configure Synapse and Ma1sd effectively:
synapse_configuration: Additional configuration settings to go in Synapse's homeserver.yaml file.ma1sd_configuration: Additional configuration settings to go in MA1SD's ma1sd.yaml file.
These variables help tweak configuration to user liking:
postgres_container_name: The name to attach to the PostgreSQL container.synapse_container_name: The name to attach to the Synapse container.https_portal_container_name: The name to attach to the HTTPS Portal (Reverse Proxy) Container.ma1sd_container_name: The name to attach to the MA1SD container.ma1sd_extender_container_name: The name to attach to the MA1SD Extender container.synapse_db_name: The name of the synapse database within the PostgreSQL container.
An example playbook for a single server Synapse setup can be seen below:
# Example Single Server Matrix Automation Playbook
# Author: Cameron Wickes
# Date: 18/04/22
---
- hosts: server_one
roles:
- "matrix-automation"
vars:
postgres_user: synapse
postgres_password: synapse
postgres_database: synapse
ma1sd_extender_username: ma1sd
ma1sd_extender_password: ma1sd
synapse_server_name: example.org
synapse_federation_list: []
synapse_configuration: |
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
mode: "search"
uri: "ldap://ldap.example.org:389"
start_tls: false
base: "ou=employees,dc=example,dc=org"
attributes:
uid: "uid"
mail: "email"
name: "givenName"
bind_dn: "cn=synapse,ou=services,dc=example,dc=org"
bind_password: "synapse"
filter: ""
ma1sd_configuration: |
ldap:
enabled: true
lookup: true
connection:
host: "example.org"
port: 389
bindDn: "cn=synapse,ou=services,dc=example,dc=org"
bindPassword: "synapse"
baseDNs:
- "ou=employees,dc=example,dc=org"
attribute:
uid:
type: "uid"
value: "uid"
name: "givenName"
email: "email"
msisdn: "phone"
An example playbook for a multi-server Synapse setup can be seen below:
# Example Multi Server Matrix Automation Playbook
# Author: Cameron Wickes
# Date: 18/04/22
---
- hosts: server_one
roles:
- "matrix-automation"
vars:
postgres_user: synapse
postgres_password: synapse
postgres_database: synapse
ma1sd_extender_username: ma1sd
ma1sd_extender_password: ma1sd
synapse_server_name: example.org
synapse_federation_list: [other.org]
synapse_configuration: |
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
mode: "search"
uri: "ldap://ldap.example.org:389"
start_tls: false
base: "ou=employees,dc=example,dc=org"
attributes:
uid: "uid"
mail: "email"
name: "givenName"
bind_dn: "cn=synapse,ou=services,dc=example,dc=org"
bind_password: "synapse"
filter: ""
ma1sd_configuration: |
ldap:
enabled: true
lookup: true
connection:
host: "example.org"
port: 389
bindDn: "cn=synapse,ou=services,dc=example,dc=org"
bindPassword: "synapse"
baseDNs:
- "ou=employees,dc=example,dc=org"
attribute:
uid:
type: "uid"
value: "uid"
name: "givenName"
email: "email"
msisdn: "phone"
- hosts: server_two
roles:
- "matrix-automation"
vars:
postgres_user: synapse
postgres_password: synapse
postgres_database: synapse
ma1sd_extender_username: ma1sd
ma1sd_extender_password: ma1sd
synapse_server_name: other.org
synapse_federation_list: [example.org]
synapse_configuration: |
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
mode: "search"
uri: "ldap://ldap.other.org:389"
start_tls: false
base: "ou=employees,dc=other,dc=org"
attributes:
uid: "uid"
mail: "email"
name: "givenName"
bind_dn: "cn=synapse,ou=services,dc=other,dc=org"
bind_password: "synapse"
filter: ""
ma1sd_configuration: |
ldap:
enabled: true
lookup: true
connection:
host: "other.org"
port: 389
bindDn: "cn=synapse,ou=other,dc=example,dc=org"
bindPassword: "synapse"
baseDNs:
- "ou=employees,dc=other,dc=org"
attribute:
uid:
type: "uid"
value: "uid"
name: "givenName"
email: "email"
msisdn: "phone"
Matrix-Automation is free and open-source software licensed under the MIT License.