What is Matrix Synapse?
You may be wondering "what is Matrix Synapse and why should I know about it?".
First, Matrix and Synapse are two different things. Synapse is a reference homeserver implementation written in Python/Twisted by the core team over at Matrix.org. Matrix is an open standard for interoperable and decentralized communication over IP. Users are able to use the open source technology for real-time communication with peers.
Matrix allows for users to connect their own homeserver to the Matrix network through federation. But, what is federation?
Federation is a group of smaller entities that together form a larger entity; a union of entities. Matrix allows for open federation so that anyone, anywhere, can join the Matrix ecosystem if they have their own Matrix Synapse server.
Matrix Synapse is a great alternative for applications like Slack, Discord, Rocket.chat, Skype and others.
In this tutorial we will go through the process step-by-step on the prerequisites, installation, and configuration of a Matrix Synapse server. This tutorial will be using Ubuntu 18.04 and the Apache web server as a reverse proxy. Matrix can be configured to use Nginx as well. This will be shown in a later tutorial.
What you will need
- A VPS server with Ubuntu 18.04
- Root privileges
- A domain name or subdomain to be used for Matrix Synapse
Install Universe Repository
sudo add-apt-repository universe
Install Apache Web Server
sudo apt install apache2
Note: We will be configuring Apache at a later step
Install Let's Encrypt (certbot)
Add the repository
sudo add-apt-repository ppa:certbot/certbot
Install Certbot's Apache Web Server package
sudo apt install python-certbot-apache
Set up well.known
On your VPS create an 'index.html' file in the directory /.well-known/matrix/server with the following content:
sudo nano index.html
Set up SRV Record
An SRV record tells other Matrix Synapse servers where they should connect to your server. The below record points them to the correct hostname and port. Replace matrix.decibite.com with your own domain/subdomain.
_matrix._tcp.decibite.com. 3600 IN SRV 10 5 443 matrix.decibite.com.
Install Matrix-Synapse Server
Add Matrix Key
wget -qO - https://matrix.org/packages/debian/repo-key.asc | sudo apt-key add -
Add Matrix Repository
sudo add-apt-repository https://matrix.org/packages/debian/
sudo apt install matrix-synapse -y
Step 1: Enter your domain (or subdomain) as your server name
Step 2: Choose 'No' for the anonymous data report (unless your really want to)
After the installation completes, start the service.
sudo systemctl start matrix-synapse
Enable the service to start at system boot.
sudo systemctl enable matrix-synapse
Next, verify that Matrix Synapse is running using the netstat command. The default configuration is to use ports '8008' (HTTP) and '8448' (HTTPS).
Configuration of Matrix Synapse
Awesome! Now that you have Matrix Synapse installed, let's go ahead and configure it to work properly.
In this tutorial we will show you how to configure Matrix Synapse to run under the local IP and enable registration through the registration-secret-key.
Before you edit the default homeserver configuration file, generate your server's shared-secret-key. Save this key somewhere safe.
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
Now, let's edit the main homeserver configuration file. Fair warning: YAML files are finnicky and space sensitive. When editing ensure you do not change the formatting or spacing; only the values.
sudo nano homeserver.yaml
Change the HTTP Listener port (8008) to the local IP address of '127.0.0.1':
Disable Matrix Synapse registration by setting 'enable_registration' to false and then uncomment 'registration_shared_secret'. Paste your shared-secret-key where 'insert_secret_key' is in the screenshot below (Tip: use CTRL + W to search/find)
*Important Note: 'registration_shared_secret' once set allows anyone who has the secret key to register USERS and ADMINS. Even when registration has been disabled.
Restart your Matrix Synapse server to implement the changes.
sudo systemctl restart matrix-synapse
Generate your Let's Encrypt Certificates
Since we are using Apache Web Server in this tutorial use the following command to generate your SSL certificate (replace matrix.decibite.com with your own domain/subdomain).
sudo certbot --apache -d matrix.decibite.com,www.matrix.decibite.com
*Note: 'www' domain is not a requirement.
Follow the steps presented to you as required. You should get the following results when it is complete:
Configuration of Apache Web Server
Now that the Matrix Synapse server is all set up let's go ahead and configure the Apache host file.
Apache Modules Required
Before we do that though, we need to enable a few Apache modules.
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_balancer
sudo a2enmod ssl
sudo a2enmod headers
sudo a2enmod lbmethod_byrequests
Edit the Configuration File
Next, go to the Apache Web Server directory
Open the configuration file
sudo nano 000-default.conf
Edit your host file to look like the following:
<IfModule mod_ssl.c> <VirtualHost matrix.decibite.com:8448> ServerName matrix.decibite.com ServerAlias www.matrix.decibite.com DocumentRoot /var/www/html/ # Configuration of the SSL Certificate SSLEngine On Include /etc/letsencrypt/options-ssl-apache.conf SSLCertificateFile /etc/letsencrypt/live/matrix.decibite.com/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/matrix.decibite.com/privkey.pem <Location /> ProxyPass http://127.0.0.1:8008/ nocanon ProxyPassReverse http://127.0.0.1:8008/ </Location> </VirtualHost> </IfModule> <IfModule mod_ssl.c> <VirtualHost matrix.decibite.com:443> ServerName matrix.decibite.com ServerAlias www.matrix.decibite.com DocumentRoot /var/www/html/ ProxyRequests off ProxyPreserveHost On ProxyVia full ProxyPass /_matrix/identity http://127.0.0.1:8090/_matrix/identity <Location /> ProxyPass http://127.0.0.1:8008/ nocanon ProxyPassReverse http://127.0.0.1:8008/ </Location> RequestHeader set X-Forwarded-Proto "https" # Configuration of the SSL Certificate SSLEngine On Include /etc/letsencrypt/options-ssl-apache.conf SSLCertificateFile /etc/letsencrypt/live/matrix.decibite.com/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/matrix.decibite.com/privkey.pem </VirtualHost> </IfModule>
Set Up UFW Firewall
In order for all services to work properly we will need to allow a few ports. Run the following commands to allow them:
ufw allow ssh
ufw allow http
ufw allow https
Now enable UFW Firewall service to run at each startup.
Check the status and verify
Adding Users to your Matrix Synapse Server
Let's add some users and admins! To add a user use the below command:
sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml https://127.0.0.1:8008
The system will now ask for the users username, password, and whether they should be made an admin of the server or not. After you have filled out the questions the user or admin will be successfully created.
Here is the result:
Test The Connection
Test Connection to Your Matrix Synapse Server
In your web browser open your domain. In the example, this would be https://matrix.decibite.com . If it worked, you should see this screen.
There is a great tool that a contributor of the Matrix project has created to allow users to test if federation has been configured properly on their own server. Navigate to the federation tester by clicking here and entering in your domain. If all is working you should see a similar result like below:
Recommended Client (Element.io)
Now that your Matrix-Synapse install is ready to go, test your connection using the recommended client of Element. Element is widely supported on platforms like Windows, MacOS, Android, iOS, and even on your browser. Check out their 'Getting Started' options here.
Test Using Their Web Client
You'll first need to change the homeserver on the web client by clicking the "Change" button below:
Enter in the homeserver URL that you had set up previously and click next:
Next, log in with your user details:
If all went well, you should now be logged in to your Matrix-Synapse install!
Mobile & Desktop Applications
For mobile and desktop applications, after the download and installation process you should be prompted with very similar steps as the web client for each application. This means you will need to:
- Change the homeserver URL
- Log in with your user
How to Host Your Own Element Web Client
Check out our tutorial on how to host your own Element Web Client.