How to install and set up a Matrix Synapse server on Ubuntu 20.04 (w/ Element)
7 min read

How to install and set up a Matrix Synapse server on Ubuntu 20.04 (w/ Element)

Matrix and Synapse are two different things. Synapse is a reference homeserver implementation. Matrix is an open standard for interoperable and decentralized communication.
How to install and set up a Matrix Synapse server on Ubuntu 20.04 (w/ Element)

What is Matrix Synapse?

You may be wondering "what is Matrix Synapse and why should I know about it?".

First, Matrix and Synapse are two different things. Synapse is a reference homeserver implementation written in Python/Twisted by the core team over at  Matrix is an open standard for interoperable and decentralized communication over IP. Users are able to use the open source technology for real-time communication with peers.

Matrix allows for users to connect their own homeserver to the Matrix network through federation. But, what is federation?

Federation is a group of smaller entities that together form a larger entity; a union of entities. Matrix allows for open federation so that anyone, anywhere, can join the Matrix ecosystem if they have their own Matrix Synapse server.

Matrix Synapse is a great alternative for applications like Slack, Discord,, Skype and others.

In this tutorial we will go through the process step-by-step on the prerequisites, installation, and configuration of a Matrix Synapse server. This tutorial will be using Ubuntu 18.04 and the Apache web server as a reverse proxy. Matrix can be configured to use Nginx as well. This will be shown in a later tutorial.

What you will need

  • A VPS server with Ubuntu 18.04
  • Root privileges
  • A domain name or subdomain to be used for Matrix Synapse


Install Universe Repository

sudo add-apt-repository universe

Install Apache Web Server

sudo apt install apache2

Note: We will be configuring Apache at a later step

Install Let's Encrypt (certbot)

Add the repository

sudo add-apt-repository ppa:certbot/certbot

Install Certbot's Apache Web Server package

sudo apt install python-certbot-apache

Set up well.known
On your VPS create an 'index.html' file in the directory /.well-known/matrix/server with the following content:

cd /var/www/html/.well-known/matrix/server

sudo nano index.html

Set up SRV Record

An SRV record tells other Matrix Synapse servers where they should connect to your server. The below record points them to the correct hostname and port. Replace with your own domain/subdomain. 3600 IN SRV 10 5 443

Install Matrix-Synapse Server

Add Matrix Key

wget -qO - | sudo apt-key add -

Add Matrix Repository

sudo add-apt-repository

Install Matrix-Synapse

sudo apt install matrix-synapse -y

Step 1: Enter your domain (or subdomain) as your server name

Step 2: Choose 'No' for the anonymous data report (unless your really want to)

After the installation completes, start the service.

sudo systemctl start matrix-synapse

Enable the service to start at system boot.

sudo systemctl enable matrix-synapse

Next, verify that Matrix Synapse is running using the netstat command. The default configuration is to use ports '8008' (HTTP) and '8448' (HTTPS).

netstat -plntu

Configuration of Matrix Synapse

Awesome! Now that you have Matrix Synapse installed, let's go ahead and configure it to work properly.

In this tutorial we will show you how to configure Matrix Synapse to run under the local IP and enable registration through the registration-secret-key.

Before you edit the default homeserver configuration file, generate your server's shared-secret-key. Save this key somewhere safe.

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

Now, let's edit the main homeserver configuration file. Fair warning: YAML files are finnicky and space sensitive. When editing ensure you do not change the formatting or spacing; only the values.

cd /etc/matrix-synapse/

sudo nano homeserver.yaml

Change the HTTP Listener port (8008) to the local IP address of '':

Disable Matrix Synapse registration by setting 'enable_registration' to false and then uncomment 'registration_shared_secret'. Paste your shared-secret-key where 'insert_secret_key' is in the screenshot below (Tip: use CTRL + W to search/find)

*Important Note: 'registration_shared_secret' once set allows anyone who has the secret key to register USERS and ADMINS. Even when registration has been disabled.

Restart your Matrix Synapse server to implement the changes.

sudo systemctl restart matrix-synapse

Generate your Let's Encrypt Certificates

Since we are using Apache Web Server in this tutorial use the following command to generate your SSL certificate (replace with your own domain/subdomain).

sudo certbot --apache -d,

*Note: 'www' domain is not a requirement.

Follow the steps presented to you as required. You should get the following results when it is complete:

Configuration of Apache Web Server

Now that the Matrix Synapse server is all set up let's go ahead and configure the Apache host file.

Apache Modules Required

Before we do that though, we need to enable a few Apache modules.

sudo a2enmod proxy

sudo a2enmod proxy_http

sudo a2enmod proxy_balancer

sudo a2enmod ssl

sudo a2enmod headers

sudo a2enmod lbmethod_byrequests

Edit the Configuration File

Next, go to the Apache Web Server directory

cd /etc/apache2/sites-enabled/

Open the configuration file

sudo nano 000-default.conf

Edit your host file to look like the following:

<IfModule mod_ssl.c>
        DocumentRoot /var/www/html/

        # Configuration of the SSL Certificate
        SSLEngine On
        Include /etc/letsencrypt/options-ssl-apache.conf
        SSLCertificateFile /etc/letsencrypt/live/
        SSLCertificateKeyFile /etc/letsencrypt/live/

        <Location />
        ProxyPass nocanon

<IfModule mod_ssl.c>
        DocumentRoot /var/www/html/

        ProxyRequests off
        ProxyPreserveHost On
        ProxyVia full

        ProxyPass /_matrix/identity

        <Location />
        ProxyPass nocanon

        RequestHeader set X-Forwarded-Proto "https"

        # Configuration of the SSL Certificate
        SSLEngine On
        Include /etc/letsencrypt/options-ssl-apache.conf
        SSLCertificateFile /etc/letsencrypt/live/
        SSLCertificateKeyFile /etc/letsencrypt/live/

Set Up UFW Firewall

In order for all services to work properly we will need to allow a few ports. Run the following commands to allow them:

ufw allow ssh

ufw allow http

ufw allow https

Now enable UFW Firewall service to run at each startup.

ufw start

ufw enable

Check the status and verify

ufw status

Adding Users to your Matrix Synapse Server

Let's add some users and admins! To add a user use the below command:

sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml

The system will now ask for the users username, password, and whether they should be made an admin of the server or not. After you have filled out the questions the user or admin will be successfully created.

Here is the result:

Test The Connection

Test Connection to Your Matrix Synapse Server

In your web browser open your domain. In the example, this would be . If it worked, you should see this screen.

Test Federation

There is a great tool that a contributor of the Matrix project has created to allow users to test if federation has been configured properly on their own server. Navigate to the federation tester by clicking here and entering in your domain. If all is working you should see a similar result like below:

Now that your Matrix-Synapse install is ready to go, test your connection using the recommended client of Element. Element is widely supported on platforms like Windows, MacOS, Android, iOS, and even on your browser. Check out their 'Getting Started' options here.

Test Using Their Web Client

You'll first need to change the homeserver on the web client by clicking the "Change" button below:

Enter in the homeserver URL that you had set up previously and click next:

Next, log in with your user details:

If all went well, you should now be logged in to your Matrix-Synapse install!

Mobile & Desktop Applications

For mobile and desktop applications, after the download and installation process you should be prompted with very similar steps as the web client for each application. This means you will need to:

  1. Change the homeserver URL
  2. Log in with your user

How to Host Your Own Element Web Client

Check out our tutorial on how to host your own Element Web Client.

Enjoying these posts? Subscribe for more