Decentralized Communication with Matrix on Ubuntu 16.04

Decentralized Communication Matrix Logo

Introduction to Decentralized Communication

Matrix is an open standard for real-time, interoperable and decentralized communication over IP, used to power VoIP/WebRTC signalling, Internet of Things communication, Instant Messaging, and every program that requires a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.

Developed as an open initiative with no company behind it, its “longer term goal is for Matrix to act as a generic HTTP messaging and data synchronization system for the whole web – allowing people, services and devices to easily communicate with each other, empowering users to own and control their data and select the services and vendors they want to use”.

Besides being a standard, Matrix provides many features:

  • Open Standard HTTP APIs for transferring JSON messages (e.g. instant messages, WebRTC signalling)
  • Client<->Server API defining how Matrix compatible clients communicate with Matrix home servers.
  • Server<->Server API defining how Matrix home servers exchange messages and synchronize history with each other.
  • Application Service API defining how to extend the functionality of Matrix with ‘integrations’ and bridge to other networks.
  • Modules specifying features that must be implemented by particular classes of clients.
  • Open source reference implementations of clients, client SDKs, home serves and application services.

We mentioned home servers: they are what store account information and communication history, sharing data with the wider Matrix ecosystem by synchronizing the communication history with other home servers.

This tutorial is about the installation of Synapse, the reference home server implementation of Matrix.

Install Matrix

Matrix provides a repository for Ubuntu, so that installations can be handled through apt.

Add Matrix Repository

First of all, add the repository key:

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

Add the official Matrix repository by executing:

# add-apt-repository

Update apt packages index:

# apt-get update
Install Matrix Synapse

Install Synapse with apt:

# apt-get install matrix-synapse

During the installation process, enter a domain name and choose whether or not to send statistics to Matrix.

Start and Enable Matrix

Start Matrix with systemctl

# systemctl start matrix-synapse

Enable it to start at boot time:

# systemctl enable matrix-synapse

Create a New User

Creating a new user for Matrix requires a shared secret. Generate a 32-character string that will be used as shared secret with:

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

Copy the generated string, and then open the homeserver configuration file, /etc/matrix-synapse/homeserver.yaml, with a text editor:

# $EDITOR /etc/matrix-synapse/homeserver.yaml

In this file, look for registration_shared_secret. Uncomment that line and set its value as the 32-character string generated with the previous command:

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

Save and close the file.

Restart Matrix Synapse with systemctl:

# systemctl restart matrix-synapse

Now it is possible to create a new Matrix user. Use the register_new_matrix_user command as follows:

$ register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml https://

Configure NGINX for Matrix

Create a new virtual host file for the domain used by Matrix:

# nano /etc/nginx/sites-available/

In this new file, paste the following content:

server {
    listen 80;
    listen [::]:80;

    root /var/www/html;
    index index.html index.htm;


    location /_matrix {
        proxy_pass http://localhost:8008;

    location ~ /.well-known {
        allow all;

The location block needs to be set up for _matrix, since this is where all Matrix clients send requests.

Enable this newly created configuration:

# ln -s /etc/nginx/sites-available/ /etc/nginx/sites-enabled/

Test it with:

# nginx -t

Its output should be a syntax OK one.


Matrix is the basis for many different clients that can be used to connect to the configured homeserver and decentralize communication systems. This tutorial has covered the most basic steps for obtaining and running a powerful server for decentralized communication backed by Ubuntu 16.04.