How To Install Matrix Synapse on Ubuntu 16.04

Introduction

Matrix is an open standard for decentralized communication. It's a collection of servers and services used for online messaging which speak a standardized API that synchronizes in real time.

Matrix uses homeservers to store your account information and chat history. They work in a similar way to how an email client connects to email servers through IMAP/SMTP. Like email, you can either use a Matrix homeserver hosted by somebody else or host your own and be in control of your own information and communications.

By following this guide you will install Synapse, the reference homeserver implementation of Matrix. When you're finished, you will be able to connect to your homeserver via any Matrix client and communicate with others users across other Matrix federated homeservers.

A registered domain name set up with the appropriate DNS records by following this hostname tutorial. Which DNS records you need depend on how you're using your domain.

If you're using your domain exclusively for Synapse, or if you will be using the same server to host your website and Synapse, you only need an A record with the hostname @.

If you will be installing Synapse on a separate server, you will need an A record with the hostname set to the subdomain you want to use, like matrix.example.com, and a SRV record with the hostname _matrix._tcp pointing to the same subdomain on port 8448, with the default priority and weights of 10 and 100 respectively. This will tell Matrix clients and homeservers where to find your Synapse installation.

Step 1 — Installing Matrix Synapse

Log in to your server as your non-root user to begin.

Before you start installing anything, make sure your local package index is up to date.

sudo apt-get update

Next, add the official Matrix repository to APT.

sudo add-apt-repository https://matrix.org/packages/debian/

To make sure your server remains secure, you should add the repository key. This will check to make sure any installations and updates have been signed by the developers and stop any unauthorized packages from being installed on your server.

After adding the repository, update the local package index so it will include the new repository.

sudo apt-get update

With the repository added, installing Synapse is as simple as running a single APT command.

sudo apt-get install matrix-synapse

During the installation, you will be prompted to enter a server name, which should be your domain name. You will also be asked to choose whether or not you wish to send anonymized statistics about your homeserver back to Matrix. Then, Synapse will install.

That command only starts Synapse when the whole server starts. Your server is already running, so use systemctl manually to start Synapse now.

sudo systemctl start matrix-synapse

Synapse is now installed and running on your server, but you'll need to create a user before you can start using it.

Step 2 — Creating a User for Synapse

Before you can start using Synapse, you will need to add a user account. Before you can add a new user, you need to set up a shared secret. A shared secret is a string that can be used by anybody who knows it to register, even if registration is disabled.

Use the following command to generate a 32-character string.

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

Copy the string you create, then open the Synapse configuration file with nano or your favorite text editor.

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

In the registration section, look for the registration_shared_secret key. Update its value to the random string you copied, inserting it between quotation marks (" "). Remember to activate the key by uncommenting the line (i.e. deleting the # at the beginning of the line).

If you want to enable public registration as well, you can update the value of enable_registration to True here.

You will be prompted to choose a username and a password. You'll also be asked if you want to make the user an administrator or not; it's up to you, but an administrator isn't necessary for this tutorial.

Once your user is created, let's make sure the webserver is able to serve Synapse requests.

Step 3 — Configuring Nginx and SSL

Matrix clients make requests to https://example.com/_matrix/ to connect to Synapse. You'll need to configure Nginx to listen for these requests and pass them on to Synapse, which is listening locally on port 8008. You'll also secure your setup by using SSL backed by Let's Encrypt.

To do this, you'll create a custom Nginx configuration file for your website. Create this new configuration file.

sudo nano /etc/nginx/sites-available/example.com

The location /_matrix block below specifies how Nginx should handle requests from Matrix clients. In addition to the request handling, the /.well-known block makes the directory of the same name available to Let's Encrypt.

Correct the syntax based on the error output, if any. When no errors are reported, use systemctl reload Nginx so the changes take effect.

sudo systemctl reload nginx

To finish securing Nginx with a Let's Encrypt certificate, follow this Let's Encrypt for Nginx on Ubuntu 16.04 tutorial. Remember to use /etc/nginx/sites-available/example.com instead of the default configuration file. You've already added the ~/.well-known block mentioned in Step 2 of that tutorial.

Once Let's Encrypt is set up, you can move on to configuring the firewall to allow the necessary traffic for Synapse to communicate with other homeservers.

Step 4 — Allowing Synapse through the Firewall

Client traffic connects to Synapse via the HTTPS port 443, (which is already open in your firewall from the Nginx guide). However, traffic from other servers connects directly to Synapse on port 8448 without going through the Nginx proxy, so you need to allow this traffic through the firewall as well.

This means that all the necessary traffic is allowed through your firewall. The last step you should take is improving Synapse's security by updating its SSL certificates.

Step 5 — Securing Federation with SSL (Recommended)

Now that Synapse is configured and can communicate with other homeservers, you can increase its security by using the same SSL certificates you requested from Let's Encrypt at the end of Step 3. By default Synapse uses self signed certificates which do the job, but seeing as you already requested the Let's Encrypt certificates it's simple to use those and improve security.