What Is the Matrix Protocol and How to Install It

Matrix Protocol Featured

Matrix is an innovative, open-source alternative to chat services such as Discord and Slack that is both feature-rich and easy to use. It fully supports end-to-end encryption and is available for almost all operating systems. You can also host it on your own server, making it a fully secure and private way to chat on the internet.

Here we will show you how you can install Matrix on your server.

What Is the Matrix Protocol?

At its core, Matrix is a set of protocols that define how messages are sent over the internet. Similar to HTTP, Matrix aims to be an open standard that promotes free and transparent sharing of information online. It does so by doing two things:

  • The core protocol team provides an open source server that you can create and deploy for clients and users to connect to. This also serves as the reference for third-party developers when creating their own software.
  • These servers, in turn, are made to communicate with each other. This means that you can talk to other users even if they are on a different server than you.

Why Use the Matrix Protocol?

One of the main selling points of Matrix is that it allows you to create a network of servers that can seamlessly talk to each other in real time. This is similar to technologies such as Email, IRC and Pleroma.

In that, you can create a server for yourself and instantly connect with the wider world. This can be incredibly helpful if you want to be able to control your own data when communicating online.

Further, this model of communication is also highly resilient and secure. Being able to have your own server gives you the ability to maintain service even if parts of the larger network goes down. Not only that, this also ensures that only you can access the accounts and messages that are in your server.

Hosting Your Own Matrix Server

The easiest way to use Matrix is by hosting your own server.

However, it is important to note that Matrix will need a number of things before you can install and use it:

  • First, you need to have a domain name for your instance. This is because, Synapse, the server that you are going to use needs a Fully Qualified Domain Name to function.
  • You also need a machine that you can access from outside your network. This can be a PC in your home that has a proper Static IP address or a VPS that you rent online.
  • Lastly, if you intend to installl Synapse on a VPS, you need to make sure that you have root access for that machine. This is because Synapse depends on a number of system packages to function properly.

Knowing all this, this guide will focus on setting up Synapse in a Debian VPS from Digitalocean. Let’s get started.

Matrix Server 29 Digitalocean Server

1. Installing Synapse

Login to your VPS instance and download all of the dependencies for Synapse:

sudo apt install lsb-release wget apt-transport-https
Matrix Server 12 Install Dependencies

By default, Debian does not include the official Synapse packages in its repositories. You will have to import the Synapse repository to your server.

  1. First, import the GPG keys of the developers to your machine:
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
Matrix Server 13 Add Matrix Repo Keys
  1. Next, add the Synapse repository to the “sources.list”:
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
Matrix Server 14 Add Matrix Repository
  1. From there, you can now use apt to update the list of packages that you can install for your system:
sudo apt update
Matrix Server 15 Apt Update

With that done, you can now install Synapse through apt:

sudo apt install matrix-synapse-py3

Synapse will ask for a couple of things during the installation.

  1. First, you’ll need to name your server aka the domain name that you want to use with Matrix. In my case, I used “yetanothermatrixserver.xyz”.
Matrix Server 16 Server Name
  1. From there, you can choose whether you want to report the statistics of your server to the Matrix developers. Since I want my server to be wholly private, I selected “No”.
Matrix Server 17 Anonymous Stat 1

2. Set Up Synapse

Once Synapse is installed, the next thing that you need to do is to setup a reverse proxy with nginx. Doing this will allow you to access Synapse from outside the local machine. This works by using the Nginx webserver to listen for incoming traffic and forwarding it to a different port in the system.

  1. To get started, you need to first install Nginx:
sudo apt install nginx
Matrix Server 18 Install Nginx
  1. Now, you need to create the Nginx configuration file for Synapse. You can do this by running the following command:
sudo touch /etc/nginx/sites-available/default
  1. Once done, you can edit this configuration file and create a reverse proxy for Synapse. For example, a reverse proxy configuration could look something like this:
server {
        server_name yetanothermatrixserver.xyz;
        listen 80;
        listen [::]:80;
        location / {
                proxy_pass http://localhost:8008;
        location ~* ^(\/_matrix|\/_synapse\/client) {
                proxy_pass http://localhost:8008;
                proxy_set_header X-Forwarded-For $remote_addr;
                client_max_body_size 50M;
        location /.well-known/matrix/server {
                return 200 '{"m.homeserver": {"base_url": "https://yetanothermatrixserver.xyz"}}';
                default_type application/json;
                add_header Access-Control-Allow-Origin *;
  • The server_name points to the domain name that you are using. In my case, I used “yetanothermatrixserver.xyz” as my server_name.
  • The two listen commands tell Nginx where to look for incoming connections. The first line looks for IPv4 connections while the second one looks for IPv6.
  • The three location blocks indicate what Nginx will do for the specific paths that a user might request. For example, the first location block tells Nginx to automatically redirect traffic to port 8008. While the latter location block handles the ACME challenge for SSL.
Matrix Server 19 Sample Nginx Config

3. Set Up SSL for Synapse

With that done, the next thing that you need to do is to setup encryption. By default, Synapse does not do SSL by itself, but you can easily set up SSL with Let’s Encrypt.

  1. You can install certbot by running the following command:
sudo apt install certbot python3-certbot-nginx
Matrix Server 20 Install Certbot
  1. Once done, you can run the following command to start the automatic certificate process:
sudo certbot --nginx -d yetanothermatrixserver.xyz
  1. After that, you can now reload nginx to verify that your Synapse installation is working.
sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/
sudo systemctl restart nginx
Matrix Server 21 Install Success

4. Create an User Account in Synapse

Now you can now create your first user account in Synapse. In order to do that, you need to do two things:

  • create a pre-shared secret
  • run the user creation script.

Knowing that, it is relatively simple to create a pre-shared secret. This is a random string of characters that you need to place in your Synapse configuration file. This, in turn, allows you to create and remove accounts from your VPS’ command line.

  1. You can easily create a random string by using “/dev/random”. For example, this is a file that goes along with other programs to create a random string of characters:
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
Matrix Server 22 Pre Shared Secret
  1. From there, you can now insert this text in your Synapse homeserver.yaml configuration file. You can find this file in your “/etc/matrix-synapse” directory.
  1. While this is a relatively long file, the only thing that you need to edit here is the “registration_shared_secret” option. You need to uncomment this line and replace its value with the text that you just made.
Matrix Server 23 Homeserver Yaml Secret
  1. Once done, you can now save this file and reload Synapse. Doing this makes sure that the server will load the pre-shared secret properly.
sudo systemctl restart matrix-synapse

The last thing that you need to do is to create the user account itself.

  1. To do that, you can run the following command:
register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
  1. Synapse will now ask a few things about the account that you want to make. First, you’ll need an username for your account.
Matrix Server 24 First User Name
  1. With this step completed, Synapse will require you to set a password for the account. Unlike other services, the server will not restrict you when setting a weak password. As such, you need to make sure that you enter a sufficiently strong password here.
Matrix Server 25 First User Password
  1. Next, Synapse will ask whether you want this account to be an admin or not. Enabling this for your account will allow you to easily manage your server from a Matrix client.
Matrix Server 26 First User Admin

Congratulations! You now have a basic working installation of Synapse.

From here, you can now login to your server through a web client such as Element. On the other hand, you can also use either a desktop or a mobile client such as Ditto.

Matrix Server 27 Element Connected

Frequently Asked Questions

Is it possible for me to use Synapse under a subdomain instead?

Yes! You can easily host Synapse under a subdomain. To do that, you just need to make sure the subdomain’s IP address is pointed to your server. You also need to change the “server_name” entry in the Nginx configuration file to make sure it is listening for access to the subdomain.

Does Synapse include its own Matrix client?

Sadly no. Synapse does not include its own web client by default. This is also the reason why you only get a confirmation screen in your website. Knowing that, there are number of good open source clients that you can install now to access your Synapse server.

Is there a way to enable external registrations for my Matrix server?

Yes! It is relatively easy to enable external registrations with Synapse. All you need to do is to change the “enable_registration” option to “true” in your homeserver.yaml file.

One important thing to note, however, is that doing it this way means that the server will not check whether the user is a real human or not. In order to do that, you need to either use CAPTCHA or email for Synapse to send out confirmation emails.

Image credit: Message speech bubble symbol by 123RF

Ramces Red
Ramces Red

Ramces is a technology writer that lived with computers all his life. A prolific reader and a student of Anthropology, he is an eccentric character that writes articles about Linux and anything *nix.

Subscribe to our newsletter!

Our latest tutorials delivered straight to your inbox