Last updated on May 5, 2021

Matrix is an open standard for decentralized persistent communication, shares somewhat similar goals to Jabber/XMPP. It attracts people from using centralized communicating software such as Facebook Messenger, WhatsApp, etc. In the Matrix protocol, a piece of software called "homeserver" plays a key role to connect users. To use Matrix, one such server must be set up. In this post, we will set up Synapse, an implementation of the Matrix homeserver maintained by the Matrix team, using a minimal configuration on Ubuntu 16.04/20.04.

Throughout the rest of this post, everything has been tested with Ubuntu 20.04/16.04 on Digital Ocean. If you are very new to Ubuntu server setup in general or on Digital Ocean, you can consult Initial Server Setup with Ubuntu 20.04 (or Initial Server Setup with Ubuntu 16.04). We also need a domain name, which is assumed to be example.org throughout this post. You can register a domain name from a reseller such as namecheap if you don't have one.

After the initial server setup, we first update the DNS configuration by creating a subdomain such as matrix.example.org that has an A record pointing to the Ubuntu server. After DNS propagation, the server should be accessible from that domain (you can check this by running host matrix.example.org on the command line). We also need to configure an SRV record of the subdomain _matrix._tcp.example.org to point to the server's domain such as matrix.example.org.

On the server, we should first make sure all packages are up-to-date by running the following command which should probably be followed by a reboot to ensure changes to take effect:

sudo apt update && sudo apt upgrade

Then add the official repository of synapse and add its key:

sudo apt install -y lsb-release wget apt-transport-https
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
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

Then we install synapse:

sudo apt update
sudo apt install matrix-synapse-py3

Edit the main configuration files to fit your need: (You may not need to edit anything, but just skimming them a little bit is potentially helpful.)

sudo $EDITOR /etc/matrix-synapse/homeserver.yaml
sudo $EDITOR /etc/matrix-synapse/conf.d/server_name.yaml

At this point, if you want to increase your security level or a publicly accepted TLS certificate, you may want to replace the server key /etc/matrix-synapse/homeserver.tls.key and certificate /etc/matrix-synapse/homeserver.tls.crt with your own. Please consult Creating a TLS Encryption Key and Certificate if you are not sure how to do so.

We will use the command register_new_matrix_user to register new users, which requires the option registration_shared_secret to be set in the file /etc/matrix-synapse/homeserver.yaml. The value of registration_shared_secret is better to be a random string, which can be generated by running cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 10 | head -1 on the server, in which you can replace 10 with a different number if you want a string of different length. Then add the following line to your homeserver.yaml file:

registration_shared_secret: "your_random_string"

Start the synapse server and automatically start it on system startup:

sudo systemctl enable matrix-synapse.service
sudo systemctl start matrix-synapse.service

Finally, use the following command and follow the prompted instructions to register new users:

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

Now the new homeserver should be accessible by using a Matrix client such as Riot Android and Riot iOS, with the homeserver on these clients set to be the server (https://matrix.example.org:8448 in this example).

Fun fact: The previous version of this post was written solely for Ubuntu 16.04, but it turns out that the steps still work for Ubuntu 20.04.