Enter the Matrix

I will explain how to run a Matrix server on a Raspberry Pi 4 in a docker container. The server we will install is the Synapse server written and maintained by the Matrix team.

I assume you have a Raspberry pi running some Linux distribution, having a fairly recent install of Docker installed on it.

We cannot simply pull the image from the DockerHub since there is no ARM build yet.

I will also show how to run a nginx proxy server to your new chat server so it can run under a subdomain. (matrix.example.com instead of example.com)

All commands are run on the raspberry pi.

Ingredients

You'll need a domain name. Buy one, borrow one get a free one! As long as the domain points to the RPi you are using for this mini tutorial.

Build an image

Create a folder somewhere, prefferably on a USB hdd if you have one. It will speeds up the build process significantly.

Clone the synapse github repo and go to the synapse folder

git clone https://github.com/matrix-org/synapse
cd synapse

Do a docker build, do not forget to tag it! Also do not forget the dot at the end!

docker build -f docker/Dockerfile --tag synapse-armv7h .

Go get comfy, this will take about 10 minutes.

Configure

Now here is the where stuff will get slightly weird. Synapse generates its own config files and folders, since we are using Docker we need to generate these in our container.

First read the commands and change accordingly!

docker run -it --rm \
--mount type=volume,src=synapse-data,dst=/data \
-e SYNAPSE_SERVER_NAME=matrix.example.com \
-e SYNAPSE_REPORT_STATS=yes \
synapse-armv7h generate

What this command wil do is the following:

• [-it] Run a command in a docker contianer
• [--rm] Delete the resulting contianer (it will keep the volume)
• [--mount] Mount a volume, couple it to the synapse-data folder in the container, and link it to the /data folder on the Docker host. The folder on the host will usualy be: /var/lib/docker/volumes/synapse-data/_data.
• [-e SYNAPSE_SERVER_NAME=] The server domain name, I assume you have a domain.
• [-e SYNAPSE_REPORT_STATS=] Share the statistics of this server with the Matrix team, your choice.
• [synapse-armv7h] The tag we gave our Docker image.
• [generate] The command to run in the container.

Go run it!

So a config file was now generated in the Docker volume. And since the volume is accesable (as root) from the host you can access it with an editor. It is at /var/lib/docker/volumes/synapse-data/_data/homeserver.yml. Luckily it is heavily commented and with some help of the Matrix website quite understandable. But we will change a few lines to get up and testing quickly.

Run!

Run the following command to spin up a container using your freshly baked config:

sudo docker run -d --name synapse \
    --mount type=volume,src=synapse-data,dst=/data\
    -p 8008:8008 \
    synapse-arm-testbuild:latest

Now browse to the ip address (do not forget to go to port 8008) of your Pi to be greeted by the synapse succes screen!

You should now grab a Matrix Client from somewhere and connect to your server.

User Management

We have two choices to register a user to our server, you can open up the registration to everyone, or you can manually add users.

• Set enable_registration=true to let anyone register
• Run the register_new_matrix_user script inside the docker container to register manually

The first option will allow the creation of new accounts on the server, by any client who can connect to the server. The second option gives you full control over who can use your server as homeserver.

To add a user to the running Synapse server we need to interact with the running container. To do this we run first need to open a terminal in the container:

docker exec -it synapse sh

This will open a very basic terminal in the container. Now to add a new user run the following command in the terminal:

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

and fill out the form. Repeat for all the users you want to add. Exit by typing exit.

Congratulations, you know have a running Matrix server on a raspberry pi 4 in your network!

Reverse-proxy

The following is a quick reminder on how to do a proxy with Nginx. If you do not get what is happening here, please read up on how to proxy on the Nginx documentation site!

Having a reverse-proxy allows you to use a subdomain and a https connection to your matrix server. Certbot (the certificate tool from Let's Encrypt) can auto detect your proxy and autamagically get you a certificate and renew it every 3 months. This makes it really easy to maintain.

Add the following code to your nginx.conf inside the http block:

server {
    listen 443 ssl http2;
    # Change me!
    matrix.example.com; 

    location / {
        # Change to your matrix server
        proxy_pass http://localhost:8008; 

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}