Book of Knowledge

Run a Matrix home server on Synology NAS

Alex Camilleri -

Matrix is an open network for secure, decentralized communicationcan. It allows you to reate chatrooms, direct chats and chat bots, complete with end-to-end encryption, file transfer, audio/video calls, synchronised conversation history, formatted messages, read receipts and more.

This idea is that you can make your own home server as part of the Matrix network:

Conversations are replicated over all the servers participating in them, meaning there are no single point of control or failure. You can reach any other user in the global Matrix ecosystem of over 25M users, even including those on other networks via bridges.

We can deploy Matrix on our home server using the matrixdotorg/synapse container. But let's clarify a couple of things first:

For our setup, our goal is to be able to have a Matrix server named YOURDOMAIN.com and be able to reach it via the url https://matrix.YOURDOMAIN.com.
This is so that your Matrix username will look something like @YOURUSERNAME:YOURDOMAIN.com rather than @YOURUSERNAME:matrix.YOURDOMAIN.com.
To explain it in a different way, it's as if we wanted your email address to be YOURUSERNAME@YOURDOMAIN.com instead of YOURUSERNAME@email.YOURDOMAIN.com.

Another important aspect of this tutorial is that it relies on the default setup which uses sqlite for your database. This is NOT ideal, but it is faster to get things running. At the end of the page there is a section on migrating from sqlite to PostgreSQL.

Setting up server and container

Generating the Matrix config file

Now that this is done, we first need to generate our synapse config file and keys.

docker run -it --rm -v /PATH/TO/SYNAPSE/data:/data -e SYNAPSE_SERVER_NAME=MYDOMAIN.com -e SYNAPSE_REPORT_STATS=yes matrixdotorg/synapse:latest generate

Once this is done, in the mounted folder you will find:

  • homeserver.yaml: this is your Matrix server config file
  • homeserver.db: the default sqlite3 database where the chat data is stored
  • YOURDOMAIN.com.log.config: no need to worry about this
  • YOURDOMAIN.com.signing.key: an important signing file

Editing the Matrix config file

  • Make sure that server_name is "YOURDOMAIN.com" and not matrix.YOURDOMAIN.com
  • Make sure that enable_registration is set to true

Running the synapse container

In your docker-compose.yaml file, add:

synapse: 
    container_name: synapse
    image: matrixdotorg/synapse:latest
    volumes:
      - /PATH/TO/SYNAPSE/data/:/data/
    ports:
    - 8008:8008
    restart: unless-stopped

You can then go to http://YOURIP:8008 to confirm that Matrix is running.

Creating subdomain redirect via DDNS

Go to your domain provider control panel, and make sure you create a CNAME record that points matrix. to the target DDNS address. You can follow this article to set it up.

Setting up your nginx config

If you are using swag as a reverse proxy, go to swag/config/nginx/proxy-confs/ and create a file called matrix.subdomain.conf containing the following:

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    listen 8448 ssl http2 default_server;
    listen [::]:8448 ssl http2 default_server;

    server_name matrix.*;

    include /config/nginx/ssl.conf;

    location ~* ^(\/_matrix|\/_synapse\/client) {

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;

        set $upstream_app synapse;
        set $upstream_port 8008;
        set $upstream_proto http;

        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
        #proxy_set_header X-Forwarded-For $remote_addr;
        #proxy_set_header X-Forwarded-Proto $scheme;
        #proxy_set_header Host $host;

        client_max_body_size 0;
    }  
}

From the SSH terminal, restart swag with docker restart swag.

Setting up server federation

There are two ways of setting up federation. One involves creating an SRV record for your domain, and another is to create a specific file on your server.

Here we will cover the second scenario.

Creating the server file

  • Open your text editor of choise, and create a new file called server (_NOTE: the file has no extention).
  • Inside the file, paste the following:
{
  "m.server": "matrix.YOUR_DOMAIN.com:8448"
}
  • Now go to your domain root folder, and place the file in the folder .well-known/matrix/. (you might have to create these folders).

Testing the federation

For things to move forward, federation needs to work.

  • Visit the federation tester
  • Insert YOURDOMAIN.com
  • If you get Success results, then this means that everything is setup correctly and you are finally good to go!

Creating users and logging in

Clients and user

You can reach your Matrix server via several different clients. Element.io is a very solid option.

  • Visit Element.io
  • Click on Sign In, and, under Homeserver (which defaults to matrix.org) click Edit.
  • Select Other homeserver, and type https://matrix.YOURDOMAIN.com (remember this is the subdomain we use to reach our Matrix instance).
  • Select a username and a password

Giving admin role to your user

  • Open your SSH terminal and navigate to /PATH/TO/SYNAPSE/data/
  • Type sqlite3 homeserver.db, which will allow you to access the database
  • Type SELECT * FROM users to check your users
  • Type UPDATE users SET admin=1 WHERE name=’@USERNAME:YOURDOMAIN.com’

Enjoy Matrix

Now you are running a Matrix server which is part of the federated Matrix network. You will be able to create your own rooms and users, as well as joining any other space from other servers all across the world!

Setting up PostgreSQL instead of sqlite

PostgretSQL seems to be a preferred way of setting up the synapse database. It is faster and more efficient. I didn't want to overload this page, so I put all the migration info in a separate tutorial that you can find here.