udelarinterior.matrix_synapse

Ansible Role for Matrix Synapse

Easy Installation with Nginx and PostgreSQL

This role helps install, upgrade, and configure a Matrix Synapse homeserver. It uses the from source method, which is the best way to get the latest version without known security issues.

The setup includes an Nginx reverse proxy and valid Let’s Encrypt certificates, making it easier to communicate with clients and other servers.

For the database, you can use PostgreSQL (ideal for production) or SQLite (better for small setups). By default, it installs and configures PostgreSQL.

It can also set up a simple Postfix email server or use an external SMTP server for sending notifications, account recovery emails, and more, with customizable templates.

Optionally, this role can install CoTURN to enable VoIP relaying for your Matrix homeserver.

Through various authentication options, you can add decentralized login support. This role also allows integration with LDAP if needed.

Lastly, you can serve the Element web app alongside Synapse, though this feature is turned off by default (synapse_installation_with_element: false) due to security recommendations. Serving Element is recommended if you have different domain names for each (synapse_server_name != element_server_name). Otherwise, you can host both on the same domain at your own risk (synapse_server_name == element_server_name).

Starting from version 3.0.0, the role works with Element web app version 1.7.15 and higher, but is not compatible with earlier versions.

Deployment Diagram

Basic Installation

This is the basic setup to get your matrix homeserver running for production (this is how the role behaves by default):

                        80,443,8448/tcp           25/tcp
                              |                     |
+-----------------------------|------------+   +----+----+
|                             |            |   | Postfix |
|  Nginx server               |            |   +----^----+
|                   +---------v----------+ |        |
|                   | Reverse Proxy Site | |        |
|                   +----------------^---+ |        |
+------------------------------------|-----+        |
                                     | 8008/tcp     |
                                  +--v--------------+-----+
   +-------------------+ 5432/tcp |                       |
   | PostgreSQL Server |<---------+ Matrix Synapse Server |
   +-------------------+          |                       |
                                  +-----------------------+

Full Installation

The full recommended setup includes the following architecture (this is also the role's default behavior, added the settings synapse_installation_with_element and synapse_with_turn to true):

         +~~~~~~~~~~~~~~~~~~~~~~~~~+
         |    Element Web App      |
         | (Run on client browser) |<----<---+
         +~~~~~~~~~~~~~~~~~~~~~~~~~+         |
                                 ^           v
                                 ^           |                         3478,5349/tcp&upd
   GET on 80,443/tcp will return ^       443,8448/tcp         25/tcp    49152:65535/udp
                  |                          |                   |         |
+-----------------|--------------------------|-------------------|---------|------+
|                 |                          |                   |         |      |
|  +--------------|--------------------------|----------+   +----+----+    |      |
|  | Nginx server |                          |          |   | Postfix |    |      |
|  |   +----------v--------+                 |          |   +----^----+    |      |
|  |   |   Standard Site   |     +-----------v--------+ |        |         |      |
|  |   |  (Serve riot.js)  |     | Reverse Proxy Site | |        |         |      |
|  |   +-------------------+     +----------------^---+ |        |         |      |
|  +----------------------------------------------|-----+        |         |      |
|                                                 | 8008/tcp     |         |      |
|                                             +---v--------------+----+    |      |
|              +-------------------+ 5432/tcp |                       |    |      |
|              | PostgreSQL Server |<---------+ Matrix Synapse Server |    |      |
|              +-------------------+          |                       |    |      |
|                                             +--------------------^--+    |      |
|                                                                  |       |      |
|                                                3478,5349/tcp&upd |       |      |
|                                                      +-----------v-------v-+    |
|                                                      |    coTURN Server    |    |
|   Your Debian                                        +---------------------+    |
|   based server                                                                  |
+---------------------------------------------------------------------------------+

Requirements

Ansible version >= 2.7

Role Variables

# The domain name for the Synapse server
# e.g., my-organization.org (this gives you @users:my-organization.org and #rooms:my-organization.org)
synapse_server_name: "{{ inventory_hostname }}"

# Fully qualified domain name of the server hosting Synapse (matrix endpoint)
# e.g., matrix.my-organization.org
synapse_server_fqdn: "{{ inventory_hostname }}"

# Directory for downloading and installing Synapse from PyPI
synapse_installation_path: /var/lib/matrix-synapse

# Version control for Synapse installation; 'present' keeps the current version, 'latest' upgrades if there is a new one
# Before upgrading, check https://github.com/matrix-org/synapse/blob/master/UPGRADE.rst
synapse_pip_state: present

# Specify a version of matrix-synapse to install
matrix_synapse_pip_pkg: "matrix-synapse"

# Allow new user registrations
synapse_enable_registration: "false"
synapse_enable_registration_with_captcha: false
synapse_recaptcha_public_key: 2Q1toXytnLYl4WIrpWgvBJOaQS1Ym36tNAJnKcZY
synapse_recaptcha_private_key: QgsOB0r79J9fpn8fAAnEIiITv7IMnjnUftdJwThs

synapse_report_stats: 'no'

# Maximum upload size allowed in bytes
synapse_max_upload_size: 10M

# Admin endpoints are password protected; we don't recommend making them public
synapse_enable_admin_endpoints: false

# Local sources for custom templates and configuration, if you want to use your own
synapse_confd_templates_src: var/lib/matrix-synapse/conf.d

### Use PostgreSQL Server with Synapse
synapse_with_postgresql: true
# PostgreSQL credentials
synapse_psql_db_name: matrix-synapse
synapse_psql_db_host: localhost
synapse_psql_user: matrix-synapse
synapse_psql_password: secret-password

### Email Settings
# If email isn't set up, password resets and notifications won't work.
synapse_email_enable: true

synapse_smtp_host: localhost
synapse_smtp_port: 25
# synapse_smtp_user: synapse
# synapse_smtp_pass: secret

synapse_email_hostname: "{{ synapse_server_fqdn }}"
synapse_email_notif_from: "MyOrganization Matrix Homeserver <[email protected]>"

synapse_email_with_custom_templates: false
# If true, use a customized version of the templates in conf.d/email.yaml.j2
synapse_email_templates_src: email_notif_templates
synapse_email_templates_dest: "{{ synapse_installation_path }}/email_notif_templates"

###  LDAP Authentication
synapse_with_ldap_authentication: false
synapse_ldap_uri: ldap.example.com:389
synapse_ldap_start_tls: 'true'
synapse_ldap_base: ou=users,dc=example,dc=com
synapse_ldap_uid: cn
synapse_ldap_mail: email
synapse_ldap_name: givenName
synapse_ldap_bind_dn: ""
synapse_ldap_bind_password: ""

###  TURN Server
synapse_with_turn: false
synapse_turn_uri: "{{ synapse_server_fqdn }}"
synapse_turn_port: 3478
# synapse_turn_tls_port: 5349  (Undefined to avoid forcing TLS on TURN)
synapse_turn_communication_min_port: 49152
synapse_turn_communication_max_port: 65535
synapse_turn_shared_secret: 5Eydym68SovsZkYLT8G9TOSCFwc2E6ijVLwL4FQgbukKPUalQZOe5gj22E9EhYrm # change this and secure it
synapse_turn_user_lifetime: 86400000
synapse_turn_allow_guests: True
synapse_turn_denied_peer_ip:
  - 10.0.0.0-10.255.255.255
  - 172.16.0.0-172.31.255.255
  - 192.168.0.0-192.168.255.255
synapse_turn_allowed_peer_ip:
  - "{{ ansible_default_ipv4.address if(ansible_default_ipv4.address) is defined else '' }}"
  - "{{ ansible_default_ipv6.address if(ansible_default_ipv6.address) is defined else '' }}"
synapse_turn_external_ip: []
  # - 1.2.3.4/172.16.0.1   # Public IPs when behind NAT
synapse_turn_tls_cert: "/etc/letsencrypt/live/{{ synapse_turn_uri }}/cert.pem"
synapse_turn_tls_pkey: "/etc/letsencrypt/live/{{ synapse_turn_uri }}/privkey.pem"

### Element Web App
# Install Element web app along with Synapse
synapse_installation_with_element: false
element_installation_path: /var/www/element
# Public domain name for the Element Web client
# e.g., element.my-organization.org
element_server_name: "{{ synapse_server_name }}"
# Latest version can be found at https://github.com/vector-im/element-web/releases
element_version: '1.7.15'
element_jitsi_preferred_domain: jitsi.riot.im
# Display name for the server
element_display_name: 'My Org Chat'
element_default_theme: light # options: 'light', 'dark', or 'custom-${theme-name}'

### Customizing Element UI
element_customatize_ui: false

element_welcome_page_template_src: var/www/element/custom-welcome.html.j2   # Leave empty to keep the default welcome page
element_welcome_logo_url: welcome/images/logo.svg
element_welcome_title: 'Welcome to Element!'
element_welcome_description: 'Decentralized, encrypted chat & collaboration powered by [matrix]'

element_custom_branding:
  welcomeBackgroundUrl: themes/element/img/backgrounds/lake.jpg
  authHeaderLogoUrl: themes/element/img/logos/element-logo.svg
  authFooterLinks:
    - text: blog
      url: https://element.io/blog
    - text: twitter
      url: https://twitter.com/element_hq
    - text: github
      url: https://github.com/vector-im/riot-web

element_custom_themes:
  - name: "Deep Purple"
    is_dark: true
    colors:
      accent-color: "#6503b3"
      primary-color: "#368bd6"
      warning-color: "#b30356"
      sidebar-color: "#15171B"
      roomlist-background-color: "#22262E"
      roomlist-text-color: "#A1B2D1"
      roomlist-text-secondary-color: "#EDF3FF"
      roomlist-highlights-color: "#343A46"
      roomlist-separator-color: "#a1b2d1"
      timeline-background-color: "#181b21"
      timeline-text-color: "#EDF3FF"
      timeline-text-secondary-color: "#A1B2D1"
      timeline-highlights-color: "#22262E"

Dependencies

This role requires geerlingguy.certbot to create and renew Let's Encrypt certificates, ensuring secure communication with clients and other servers.

Example Playbook

- hosts: servers
  roles:
    - role: udelarinterior.matrix_synapse
      vars:
        synapse_enable_registration: "true"
        synapse_with_postgresql: true
        synapse_psql_db_name: matrix-synapse
        synapse_psql_db_host: localhost
        synapse_psql_user: matrix-synapse
        synapse_psql_password: my-password
        certbot_admin_email: [email protected]
        certbot_certs:
          - domains:
            - "{{ synapse_server_name }}"
            - 'msg.my-organization.org'
            - 'chat.my-organization.org'