We are setting up a matrix-synapse instance on our homeserver using an Ubuntu 22.04 VM. Most of these instructions were collected from the official documentation on github. We want to have our domain (example.com) responding for our matrix handle (e.g. @john:example.com), not the hostname (matrix.example.com) of the server.

Installation of Matrix-synapse

First install some packages we’ll need:

sudo apt install -y lsb-release wget apt-transport-https

Now add the keyrings and the repository for matrix-synapse server:

sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
    sudo tee /etc/apt/sources.list.d/matrix-org.list

Now update your apt repositories:

sudo apt update

And install matrix-synapse

sudo apt install matrix-synapse-py3

When asked for the server name, we enter example.com . For further informations on this, consult the first chapter of the installation instructions: Choosing your server name. Decide if you want to have homeserver usage statistics and you are done.

Setting up Synapse

Install PostgreSQL

sudo apt install postgresql

Select your geographic area. Done. Install the libpq5 libraries:

apt install libpq5

To set up the database, you need to be logged in as the postgres user:

sudo -u postgres bash

Create the synapse user

createuser --pwprompt synapse_user

Create a safe password and note it down. Create the database:

createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse

Let’s enable password authentication so that synapse_user can connect to the database:

cd /etc/postgresql/14/main
nano pg_hba.conf

Add the (last) line for the synapse_user as follows to the pg_hba.conf file. As we use local, you do not need to provide an address (leave the fourth column empty). Save and exit.

local   replication   all                                peer
host    replication   all        127.0.0.1/32            scram-sha-256
host    replication   all        ::1/128                 scram-sha-256
local   synapse       synapse_user                       scram-sha-256

Exit the shell for postgres user and fall back to your standard user:

exit

Configure synapse to use postgreSQL

cd /etc/matrix-synapse
nano homeserver.yaml

Modify the database parameters in homeserver.yaml to match the following, save and exit.

database:
  name: psycopg2
  args:
    user: synapse_user
    password: <password>
    database: synapse
    host: localhost
    cp_min: 5
    cp_max: 10

Make sure that postgreSQL starts on boot. Open the postgres.conf file:

cd /etc/postgresql/14/main
nano postgresql.conf

Under Connection Settings, uncomment (delete the hash sign) the following line:

#listen_addresses = 'localhost' 

Save, exit. Now let’s restart matrix-synaose and the postgres service.

systemctl restart postgresql
systemctl restart matrix-synapse

For more information or debugging, consult the official documentation.

TLS certificates and reverse proxy setup

We assume that you have a functioning Nginx server. We set up two (see first paragraph of this page for the reason) basic reverse proxy configuration files in /etc/nginx/sites-available, one for the matrix server (matrix.example.com) and one for the domain itself (example.com), using the default files provided. Create the SSL certificates (do not forget to enable the sites first). Do not forget to point the corresponding DNS records to your reverse proxy and allow the firewall to let the incoming connections (port 80 & 443) through.

The matrix.example.com sites configuration file should look like this:

server {

    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/matrix.exmaple.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot


    server_name matrix.example.com;
    access_log /var/log/nginx/matrix.example.com.access.log;
    error_log /var/log/nginx/matrix.example.com.error.log;

   location ~ ^(/|/_matrix|/_synapse/client) {
        # note: do not add a path (even a single /) after the port in `proxy_pass`,
        # otherwise nginx will canonicalise the URI and cause signature verification
        # errors.
        proxy_pass http://<IP OF SYNAPSE SERVER>:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;

        # Nginx by default only allows file uploads up to 1M in size
        # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
        client_max_body_size 50M;

    # Synapse responses may be chunked, which is an HTTP/1.1 feature.
    proxy_http_version 1.1;
    }

}


server {
    if ($host = matrix.example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80;

    server_name matrix.example.com;
    return 404; # managed by Certbot

}

The example.com sites configuration file should look like this:

server {

    server_name example.com;
    access_log /var/log/nginx/example.com.access.log;
    error_log /var/log/nginx/example.com.error.log;

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

# the root folder should redirect to your regular website under your domain name (if needed)
location / {

        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_headers_hash_max_size 512;
        proxy_headers_hash_bucket_size 128;
        proxy_pass http://<WEBSERVER>;
        include proxy_params;
     }

location /.well-known/matrix/client {
    return 200 '{"m.server": "matrix.example.com:443"}';
    default_type application/json;
    add_header Access-Control-Allow-Origin *;
}

location /.well-known/matrix/server {
    return 200 '{"m.server": "matrix.example.com:443"}';
    default_type application/json;
    add_header Access-Control-Allow-Origin *;
}
}


server {
    if ($host = example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;

    server_name example.com;
    return 404; # managed by Certbot


}

When configuring your client, use the matrix.example.com URL. The .well-known json message is used by other matrix servers that want to connect to your server. They will be informed that they should use a different hostname than the one provided by the user’s handles. More information is available in the official delegation documentation.

The official documentation states that port 8448 should be open for federation and also listened to by the reverse proxy, but our configuration works fine without it. Maybe the other matrix servers also try port 443 if 8448 is not available?

If your reverse proxy is running on a different machine than the synapse server, than you have to adjust the listeners bind_addresses in the /etc/matrix-synapse/homeserver.yaml to the following. Do not forget to restart the matrix service after saving the changes.

bind_addresses: ['::1', '0.0.0.0']

Test delegation / federation using the Matrix Federation Tester.

Adding a Matrix user

In order to be able to add users, you need to define the registration shared secret in the /etc/matrix-synapse/homeserver.yaml file. Add the following line at the end, generating some random salt. Restart the matrix service afterwards.

registration_shared_secret: YOURRANDOMSALTSTRING

Now add a user, using the following command:

register_new_matrix_user -u john -c /etc/matrix-synapse/homeserver.yaml -a https://matrix.example.com

-u, --user
Local part of the new user. Will prompt if omitted.
-p, --password
New password for user. Will prompt if omitted. Supplying the password on the command line is not recommended. Use the STDIN instead.
-a, --admin
Register new user as an admin. Will prompt if omitted.
-c, --config
Path to server config file containing the shared secret.
-k, --shared-secret
Shared secret as defined in server config file. This is an optional parameter as it can be also supplied via the YAML file.
server_url
URL of the home server. Defaults to ´https://localhost:8448´.

Use a matrix client (e.g. https://app.element.io) to test your server and user. Have fun!