Synapse

Updated 4 June 2020

Matrix

Contents

Introduction

Matrix is an open and free protocol for real-time distributed communication. It can be used for instant messaging, audio and video calls via WebRTC, the Internet of Things, and anything else where you may need a standard HTTP API to publish and subscribe to updates while keeping track of your communication history. Matrix is a fully implemented federated network, thus allowing you to communicate seamlessly, create shared rooms for users on different servers, and make video and audio calls.

There are currently several supported servers for this protocol, the most popular of which is Synapse.

Preparing a LXC container

We recommend that you install Synapse in a separate container and set it up as described in the manual.

Installing and configuring PostgreSQL

Install and configure PostgreSQL for peer authentication, according to the manual . Create a user and a database both called synapse, as shown below:

psql -U postgres

Password for user postgres: 
psql (11.2)
Type "help" for help.

postgres=# create role synapse with login;
CREATE ROLE
postgres=# \password synapse
Enter new password:
Enter it again: 
postgres=# CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER synapse;
CREATE DATABASE

Installing and configuring Synapse

Create the synapse user:

useradd -d /var/calculate/synapse synapse

Create and activate a virtual environment for Python:

su - synapse

python3 -m venv env

echo 'source ~/env/bin/activate' >> ~/.bashrc

source env/bin/activate

Install Synapse and the PostgreSQL module in the virtual environment:

pip install --upgrade pip

pip install --upgrade setuptools

pip install matrix-synapse[all]

pip install psycopg2-binary

Create a Synapse configuration:

python -m synapse.app.homeserver --server-name matrix.example.org --config-path homeserver.yaml --generate-config --report-stats=yes

Exit the user session:

exit

Configure Synapse to connect to the database:

/var/calculate/synapse/homeserver.yaml
...
# Database configuration
database:
  # The database engine name
  name: "psycopg2"
  # Arguments to pass to the engine
  args:
    # Path to the database
    database: synapse
    host: localhost
    user: synapse
    password: "secret"
...

Add support for searching all server users:

/var/calculate/synapse/homeserver.yaml
...
# User Directory configuration
#
# 'search_all_users' defines whether to search all users visible to your HS
# when searching the user directory, rather than limiting to users visible
# in public rooms.  Defaults to false.  If you set it True, you'll have to run
# UPDATE user_directory_stream_pos SET stream_id = NULL;
# on your database to tell it to rebuild the user_directory search indexes.
#
user_directory:
   search_all_users: true
...

If Nginx will be configured on a separate server later on, enable interaction with Synapse using not only a loopback interface:

/var/calculate/synapse/homeserver.yaml
...
listeners:
  - port: 8008
    tls: false
    bind_addresses: ['0.0.0.0']
    type: http
    x_forwarded: true
...

Getting Let's Encrypt certificate

Get the matrix.example.org domain certificate for Nginx, according to the manual.

Installing and configuring Nginx

Install and configure the Nginx Web server as a reverse proxy, according to the manual. Add the following settings for matrix.example.org:

/etc/nginx/sites-enabled/matrix.conf
server {
    listen 443 ssl;
    server_name matrix.example.org;

    include ssl.conf;
    ssl_certificate /etc/nginx/ssl/matrix.example.org/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/matrix.example.org/privkey.pem;
    client_max_body_size 1000M;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;

    }
}

To join the federation with your Matrix server, add the following parameters:

/etc/nginx/sites-enabled/matrix.conf
server {
    listen 8448 ssl;
    server_name matrix.example.org;

    include ssl.conf;
    ssl_certificate /etc/nginx/ssl/matrix.example.org/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/matrix.example.org/privkey.pem;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

To make your server visible to clients and other servers via the distributed protocol, add an SRV record to the DNS of ~matrix.example.org~:

_matrix._tcp.matrix.example.org. 3600 IN SRV 10 0 8448 matrix.example.org.

Starting Synapse

Create an OpenRC script to manage the Synapse daemon:

/etc/init.d/synapse
#!/sbin/openrc-run
# Copyright 2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

name="Synapse daemon"
description="Synapse daemon"
command=/var/calculate/synapse/env/bin/synctl
command_user=synapse
command_args="${synapse_args}"
directory=/var/calculate/synapse
pidfile="/var/calculate/synapse/homeserver.pid"

depend() {
        use net
        need postgresql nginx
}

start() {
        ebegin "Starting Synapse"
        start-stop-daemon -u "${command_user}" -S "${command}" \
        -d "${directory}" -p "$pidfile" \
                -- start &>/dev/null
        eend $?
}

stop() {
        ebegin "Stopping Synapse"
        start-stop-daemon -u "${command_user}" -K "${command}" \
                -d "${directory}" -p "$pidfile" -- stop

        eend $?
}

Set execution privileges:

chmod 0755 /etc/init.d/synapse

Start the Synapse daemon:

/etc/init.d/synapse start

Add Synapse to autostart:

rc-update add synapse

Congratulations, your Matrix server is up and running! But this is not all. Feel free to discover more of the amazing features of your personal Matrix server.

Adding users

To add a new user, myuser, run:

su - synapse

register_new_matrix_user -c homeserver.yaml http://localhost:8008

New user localpart [root]: myuser
Password: 
Confirm password: 
Make admin [no]: no
Sending registration request...
Success!

Updating Synapse

Update the Python libraries for user:

su - synapse

pip install --upgrade matrix-synapse[all]

exit

Restart the Synapse server:

/etc/init.d/synapse restart

Bridging

To configure Matrix integration with other messaging services, refer to Matrix bridges.