setting up a matrix homeserver

3 March 2018 matrix

matrix is another take on federated messaging, supporting fancy features. this roughly shows how to setup a homeserver with matrix synapse and serve the riot web ui for matrix.


add a dns srv record

to use the second level domain as domain for usernames etc. you need a srv record pointing clients and other servers in the right direction:

$ host -t srv                       has SRV record 0 0 8448

add the synapse repositories and repo key:

deb stretch main
deb-src stretch main

wget -q
apt-key add repo-key.asc

install synapse

apt-get update
apt-get install matrix-synapse

install nginx

apt-get install nginx

setup the site config for nginx

server {
    # remove this after the cert has been issued
    listen 80;

    ## uncomment this after you have run and got a certificate
    ## client ports
    #listen 443 ssl;
    #listen [::]:443 ssl;

    ## federation ports
    #listen 8448 ssl;
    #listen [::]:8448 ssl;

    #ssl_certificate /etc/ssl/;
    #ssl_certificate_key /etc/ssl/;   

    # allow larger uploads
    client_max_body_size 50M;

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

    # /var/www/html/.well-known is writeable by
    location /.well-known {
        alias /var/www/html/.well-known;

    # the riot webui will live here
    location / {
        alias /var/www/html/riot/;

start nginx to have .well-known served for the next step: systemctl start nginx

setup letsencrypt for your domain

i like to use for that as it is less bloated than the standard certbot.

follow the instructions for webroot, and use /var/www/html/ as webroot. the directory .well-known has to be writeable by the user running

after the certs have been correctly issued install them using install. they should all go to /etc/ssl/

after installing create a new unix group ssl, and chown the certificate files which are now in /etc/ssl/

chown root:ssl /etc/ssl/*.pem
chmod g+r /etc/ssl/*.pem renews them using cat > $file, so the owner will be kept. add the user matrix-synapse to the ssl group so it can read the certificates.

gpasswd -a matrix-synapse ssl

(if you don’t want to run as root, add the user to the ssl group as well)

now, remove the listener on port 80 and enable the listeners on 443 and 8448 in the nginx config and restart it systemctl restart nginx. it should now listen on port 443 and port 8448.

synapse config

with nginx and certificates configured, synapse needs to be told that it’s behind a proxy and stuff. here are the relevant parts from /etc/matrix-synapse/homeserver.yaml:

use our certificates for signing

tls_certificate_path: "/etc/ssl/"
tls_private_key_path: "/etc/ssl/"

don’t do ssl as we’re proxied

no_tls: True

http listener config

in the http (not https which isn’t used as we disabled tls) listener configuration set this

bind_address: 'localhost'

enable registration

at the end of the file enable registration:

enable_registration: True

install riot webui

get a release from and unpack it to /var/www/html/riot .

riot needs to be configured for your homeserver, copy /var/www/html/riot/config.sample.json to /var/www/html/riot/ and change the values to something like this:

    "default_hs_url": "",
    "default_is_url": "",
    "brand": "",
    "bug_report_endpoint_url": "",
    "integrations_ui_url": "",
    "integrations_rest_url": "",
    "features": {
        "feature_groups": "labs",
        "feature_pinning": "labs"
    "default_federate": false,
    "welcomeUserId": ""

start synapse

systemctl start matrix-synapse