Install Matrix Synapse on Ubuntu 20.04 LTS

In this tutorial, we will build Matrix Synapse using the Ubuntu 20.04 operating system.

1. Make sure your Ubuntu repository is updated.

apt update

2. Make sure your hostname is a domain name or subdomain / FQDN that has resolved to the server IP address.

3. Install some components

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

4. Add GPG key

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

5. Update again & install the main package

apt update
apt install matrix-synapse-py3

Enter the hostname for your server. If asked if you want to report anonymously, you can answer Yes or No.

6. Make sure the service is started and enabled

systemctl start matrix-synapse
systemctl enable matrix-synapse

7. Make sure the service is running by checking if port 8008 is listening

ss -plnt

8. Configuration on Synapse Matrix

Use the command below to generate the Matrix Synapse registration. The code is used to edit the next config.

cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

9. Edit Bind Address

We change the bind-address to listen using the server's public IP.

cd /etc/matrix-synapse/
nano homeserver.yaml

Make sure to modify the bind_addresses section below

- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['ip.ip.ip.ip', '']
- names: [client, federation]
compress: false

Disable registration User by default if for private. Add the following line.

enable_registration: false

Modify the registration_shared_secret in the config file. Add this line.

registration_shared_secret: xxxxxxxxxxxxxxxxxxxxxxxx

For more detailed configuration, please refer to

10. install SSL certbot

apt install certbot -y

Then generate the subdomain that has been pointed

certbot certonly --rsa-key-size 2048 --standalone --agree-tos --no-eff-email --email email@customer -d

When it's done, the SSL will be installed in this folder:

ls -la /etc/letsencrypt/live/

11. Install NGINX Reverse Proxy

apt install nginx -y

Configuration in nginx config

cd /etc/nginx/sites-available/
nano matrix

Then use the following nginx config. Customize it with your settings.

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

    # For the federation port
    listen 8448 ssl http2 default_server;
    listen [::]:8448 ssl http2 default_server;

    ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem;


    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-public-address: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;

We link the config, then check if the nginx config is correct.

ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/
nginx -t

Make sure nginx is started and enabled auto startup

systemctl restart nginx
systemctl enable nginx

12. Register a new user as admin.

register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://ip-public-server:8008

In this section, enter the desired user and password. When asked if you want to be an admin, then select yes.

Congratulations! The admin user registration has been completed.

13. Test run

To use Matrix Synapse, we need an existing web client,

Use the Sign In menu then in the homeserver section click Edit then fill in your server-name-then proceed to enter your username and password.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.