Last updated on April 26, 2019
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.
Throughout the rest of this post, everything has been tested with Ubuntu 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 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
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
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).