How to Install Matrix Synapse Chat on Ubuntu 18.04 LTS

Matrix is a new ecosystem for decentralized communication in real time for open federated instant messaging and VoIP services. It provides RESTful HTTP JSON APIs for building distributed and federated chat servers with no single point of control and failure and provides all references for the APIs.

Synapse is an implementation of the matrix homeserver that's created by matrix team and written in Python/Twisted. With this software, we can implement the matrix way for decentralized communication, we can create our own home server and store all user personal info, chat history, create the room for own use, etc.

In this tutorial, we will show you step-by-step how to install and configure Matrix Synapse on Ubuntu 18.04. We will configure Matrix Synapse on the local IP address, and configure the Nginx web server as a reverse proxy for it, and implement the HTTPS connection between clients and the front-end Nginx web server.


  • Ubuntu 18.04
  • Root privileges
  • Matrix Domain name or sub-domain -

What we will do?

  1. Update and Upgrade the Ubuntu 18.04 System
  2. Install Matrix Synapse
  3. Configure Matrix Synapse
  4. Generate SSL Letsencrypt
  5. Install and Configure Nginx as a Reverse proxy for Matrix Synapse
  6. Setup UFW Firewall
  7. Setup New Matrix User
  8. Testing

Step 1 - Update and Upgrade System

Login to your Ubuntu server, update the repository and upgrade all packages using the apt command below.

sudo apt update
sudo apt upgrade

And all ubuntu packages have been upgraded.

Step 2 - Install Matrix Synapse

In this step, we will install the matrix synapse software using the Debian packages from the official matrix repository.

Add the matrix key and repository by running all commands below.

wget -qO - | sudo apt-key add -
sudo add-apt-repository

The command will automatically update the repository.

Install Matrix Synapse

Now install matrix synapse using the apt command as below.

sudo apt install matrix-synapse -y

During the installation, it will ask you about the matrix server name - type the matrix domain name ''.

Matrix synapse apt installer - part 1

And for the anonymous data report, choose 'No'.

Matrix synapse apt installer - part 1

When the matrix synapse installation is complete, start the service and enable it to launch everytime at system boot.

sudo systemctl start matrix-synapse
sudo systemctl enable matrix-synapse

The matrix synapse is now up and running using the default configuration on port '8008' and '8448'. Check using netstat command.

netstat -plntu

Check open ports

Step 3 - Configure Matrix Synapse

After the matrix synapse installation, we will configure it to run under the local IP address, disable matrix synapse registration, and enable the registration-shared-secret.

Before editing the home server configuration, we need to generate the shared secret key.

Run the command below.

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

And you will get the generated key. Copy the result key.

Now we need to edit the home server configuration file 'homeserver.yaml' on the '/etc/matrix-synapse/' directory. Change the current directory to '/etc/matrix-synapse' and edit the configuration file using vim.

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

Change the HTTP and HTTPS Listener port '8008' and '8448' to the local IP address ''.

    port: 8448
      - ''

    - port: 8008
    bind_addresses: ['']

Matrix Synapse configuration

Matrix Synapse port config

Disable the matrix synapse registration, uncomment the 'registration_shared_secret' configuration and paste the secret key generated.

enable_registration: False
registration_shared_secret: "MtkF9JOkNHsRRISyR5L91KAQlrrPhyWX"

Save and exit.


registration_shared_secret: If set allows registration by anyone who also has the shared secret, even if registration is disabled.

Now restart the matrix synapse services.

sudo systemctl restart matrix-synapse

restart matrix-synapse

Check the homeserver service using the command below.

netstat -plntu

You will get the matrix synapse service is now on the local IP address.

Check Matrix Synapse Ports

And we have completed the matrix synapse installation and configuration.

Step 4 - Generate SSL Letsencrypt Certificates

In this tutorial, we will enable HTTPS for the Nginx reverse proxy, and we will generate the SSL certificate files from Letsencrypt.

Install the letsencrypt tool using the apt command below.

sudo apt install letsencrypt -y

The Letsencrypt tool is installed on the system, now generate the SSL certificate files for the matrix domain name '' using the certbot command as shown below.

certbot certonly --rsa-key-size 2048 --standalone --agree-tos --no-eff-email --email [email protected] -d

The Letsencrypt tool will generate SSL certificate files by running the 'standalone' temporary web server for verification.

And when it's complete, you will get the result as shown below.

Generate SSL Letsencrypt Certificates

SSL certificate files for the matrix synapse domain name '' is generated inside the '/etc/letsencrypt/live/' directory.

Step 5 - Install and Configure Nginx as a Reverse Proxy

In this step, we will install the Nginx web server and configure it as a reverse proxy for home server that is running on the port '8008'.

Install the Nginx web server using the apt command below.

sudo apt install nginx -y

After the installation is complete, start the service and enable it to launch everytime at system boot

sudo systemctl start nginx
sudo systemctl enable nginx

Next, we will create a new virtual host configuration for the matrix domain name ''.

Go to the '/etc/nginx' configuration directory and create a new virtual host file 'matrix'.

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

Paste the following configuration there.

server {
       listen 80;
       return 301 https://$server_name$request_uri;

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

    ssl_certificate /etc/letsencrypt/live/;
    ssl_certificate_key /etc/letsencrypt/live/;

    # If you don't wanna serve a site, comment this out
    root /var/www/html;
    index index.html index.htm;

    location /_matrix {
      proxy_set_header X-Forwarded-For $remote_addr;

Save and exit.

Activate the virtual host file and test the configuration.

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

Make sure there is no error, then restart the Nginx services.

sudo systemctl restart nginx

Nginx installation and configuration as a reverse proxy for the Matrix Synapse homeserver has been completed.

Configure Nginx

Step 6 - Setup UFW Firewall

In this tutorial, we will only open three ports for our services. We will only allow SSH, HTTP, and HTTPS connection on the UFW firewall configuration.

Add the SSH, HTTP, and HTTPS services to the UFW firewall configuration by running the command below.

ufw allow ssh
ufw allow http
ufw allow https

setup UFW firewall

Now enable the UFW firewall service and then check the status.

ufw enable
ufw status

And you will get the result as shown below.

Check Firewall status

And we've completed the UFW firewall configuration.

Step 7 - Create a New Matrix User

At this stage, the matrix synapse homeserver installation and configuration is complete. And in this step, we will show you how to add a new matrix user from the command line server.

To create a new matrix user, run the command below.

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

Now you need to input the user name, password, and decide whether the user will have the admin privileges or not.

Below is the result on my system.

Create a New Matrix User

And we have created a new matrix user named 'hakase' with admin privilege.

Step 8 - Testing

Download the Riot desktop application for your operating system and install it.

Open the Riot software and you will get the Matrix login page as below.

Test Matrix Synapse

Type the matrix username and password, then choose the 'Custom server' option and type the custom domain name ''.

Click the 'Sign In' button.

And now you will get the Riot Dashboard.

Riot Dashboard

The Matrix Synapse home server is up and running under the Nginx reverse proxy HTTPS connection, and the 'hakase' user is now logged in to the matrix homeserver using the Riot application desktop.

Matrix user configuration.

User settings

Matrix chat user as a Group.

Matrix Chat


Share this page:

Suggested articles

0 Comment(s)

Add comment