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:
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:
To set up the database, you need to be logged in as the postgres user:
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:
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!