There is a new version of this tutorial available for Ubuntu 20.04 (Focal Fossa).

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

18 Comment(s)

Add comment


By: RIchard van der Hoff

I suspect federation won't work with this setup because the federation port (8448) is firewalled.

By: Ben Parsons

Hi Muhammad,

If you read this, could you contact me? I work for which produces Matrix/Synapse, we like your tutorial.

You can email me at: benp at matrix dot org


By: Abhinaw

Hello sir,

I am Abhinaw.I`m useing ubuntu linux.I am install matrix but show the message 404 Not Found [IP:xxxxxxxxx] .

By: Dirk

Great tutorial, works like a charme. Thank you very much!

Greetings from Switzerland :)

By: Sam

Hi, thank you for this great walkthrough.

I am now having the issue that I have no idea how to increase the file size.  I am getting following error:

upload request body too large

I have tried adding

client_max_body_size 500M;

to the Nginx.config, edited the php.ini, what did I miss?


By: Andy

The netstat command doesnt show matrix running. How can i check that matrix is running? I also looked in services but matrix is obviously not a service.

By: Bebo Do


thanks for the tutorial. whats the best way to upgrade to a newer version when installed based on your tutorial?

By: nima

when i enter this command :wget -qO - | sudo apt-key add -it says :

gpg: no valid OpenPGP data found.

By: eupator

The repo error use:


wget -qO - | sudo apt-key add -

By: Clemens

Thank you Muhammad, Great step-by-step tutorial. Worked like a dream.But....There is always a but. Federation does NOT work with this setup. That sort of defeats the prupose unless you wish to run an inhouse (only) IM system. What do I do to get federation to work? I have already opened up ports 8008 and 8448 in UFW but so far to no avail. Help.... Thank you in advance.

By: Michael MacDonald

This is the good part about this.  I only want a localized chat that only I have control over, I really don't want anything else.  There are other tutorials on how to set things up differently.  I'm moving away from Discord or Slack because I do not want dark overlords monitoring my conversations.  The idea that a Discord Admin can come in out of nowhere and ban users for me, or delete comments, whatever?  I really don't want that, they have no right.

By: atefeh

i wrote all the commands just fine until "the step for Activate the virtual host file and test the configuration." Now when i write this Command

nginx -t

i face with this Error :

bash:: command not found

i checked that nginx is installed or not but apparently it is installed . But the Commands are somehow unknown for ubuntu ! Can you guys help me with this?

By: Keoz

I am facing the same issue as you do atefeh, I can't get Nginx restarted ?

I have been posting a thread with screen captures of content in the Nginx config host file, and content of results out of command lines to search for failure details :

I hope someone may help me to solve this issue.

By: Jake

I don't have a domain name.  What do I do?

Also, how to I re-run the configuration?

I need something super simple to start.  Are these the minimum instructions?



By: Vlad

Not working in 2020 with latest ubuntu and synapse

By: fishtail

I am stuck as well...just before Step3, I did "netstat -plntu", and I don't see port 8448 being used.

By: Olof Gross

Vlad & fishtail,

i had the same problem as you but i found it out! If you look at the output from 'systemctl status matrix-synapse' you see error messages from the daemon that it can't read the tls certificate files installed by letsencrypt because of lack of permissions. I'm not sure how to do this the proper way but i just copied 'privkey.pem' and 'fullchain.pem' to synapses directory under /etc, renamed them to the filenames you can see at the top of the config file and changed the ownership to 'matrix-synapse' and group to 'nogroup' (like the file 'homeserver.signing.key' in same dir). Now it works for me :)

By: fishtail

@Olof & @Vlad,

I got past my problem, but it wasn't what Olof suggested.  My problem was that the 'homeserver.yaml' that was installed had "bind_address" (singular) on soon as I changed them to "bind_addresses" and follow the odd formation/spacing that's in the tutorial, it works!

HOWEVER, I got all the way to the bottom, but when I go to the website, it just says "Welcome to nginx!".

If I go to "https://site/_matrix", it says Method Not Allowed:  Your browser approached me (at /_matrix) with the method "GET". I only allow the method HEAD here.

If I change "location /_matrix" to "location /", it says No Such Resource:  No such child resource.

SO, I am still at a loss, at a different place.