setting up a matrix homeserver

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.

assumptions

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 _matrix._tcp.example.org                               
_matrix._tcp.example.org has SRV record 0 0 8448 matrix.example.org.

add the synapse repositories and repo key:

deb http://matrix.org/packages/debian/ stretch main
deb-src http://matrix.org/packages/debian/ stretch main

wget -q https://matrix.org/packages/debian/repo-key.asc
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 acme.sh and got a certificate
    ## client ports
    #listen 443 ssl;
    #listen [::]:443 ssl;

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

    #ssl_certificate /etc/ssl/matrix.example.com/fullchain.pem;
    #ssl_certificate_key /etc/ssl/matrix.example.com/key.pem;   
    server_name matrix.example.org;

    # 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 acme.sh
    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 https://acme.sh 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 acme.sh.

after the certs have been correctly issued install them using acme.sh install. they should all go to /etc/ssl/matrix.example.org.

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

chown root:ssl /etc/ssl/matrix.example.org/*.pem
chmod g+r /etc/ssl/matrix.example.org/*.pem

acme.sh 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 acme.sh 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/matrix.example.org/cert.pem"
tls_private_key_path: "/etc/ssl/matrix.example.org/key.pem"

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 https://github.com/vector-im/riot-web/releases 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/config.matrix.example.org.json and change the values to something like this:

{
    "default_hs_url": "https://matrix.example.org",
    "default_is_url": "",
    "brand": "example.org",
    "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