Matrix is a cutting-edge ecosystem for real-time, decentralized communication encompassing open, federated instant messaging and VoIP services. By offering RESTful HTTP JSON APIs, Matrix enables the creation of distributed chat servers without a centralized point of control or failure, along with comprehensive API documentation.
Synapse, developed by the Matrix team and written in Python/Twisted, is a reference implementation of the Matrix home server. Synapse facilitates decentralized communication by allowing users to host their own home server, store user data and chat history, and create private chat rooms.
This article provides a step-by-step guide on installing and configuring Matrix Synapse on Ubuntu 20.04. We will integrate Matrix Synapse with Nginx as a reverse proxy and secure it using SSL certificates from Let’s Encrypt.
Prerequisites
This tutorial requires a server running Ubuntu 20.04 with at least 1GB of RAM, 25GB of free disk space, and 2 CPUs. Root privileges are also necessary to access your server.
Objectives
- Install Matrix Synapse
- Configure Matrix Synapse
- Generate SSL Certificate with Let’s Encrypt
- Set up Nginx as a Reverse Proxy
- Configure UFW Firewall
- Register a New User
- Test the Installation
Step 1 – Install Matrix Synapse
Begin by installing Matrix Synapse on your Ubuntu 20.04 server. First, add the GPG key and the official Matrix Synapse repository.
Install necessary packages:
sudo apt install -y lsb-release wget apt-transport-https
Add the GPG key and repository:
sudo wget -qO /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
Now update all package repositories and install Matrix Synapse:
sudo apt update sudo apt install matrix-synapse-py3
Input your domain name and select ‘OK‘ to continue. For anonymous data collection, choose ‘No‘.
The Matrix Synapse installation is complete. Start the service and enable it to start automatically on boot:
systemctl start matrix-synapse systemctl enable matrix-synapse
Check the status:
systemctl status matrix-synapse ss -plnt
Your Matrix Synapse should be active on TCP port ‘8008’.
Step 2 – Configure Matrix Synapse
Modify the bind-addresses, disable registration, and set up the registration shared secret.
Generate a registration secret:
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
Save the generated key:
GH7AP4Zcthz02Cmg58sqUgonm7zlwH0f
Edit the configuration file:
cd /etc/matrix-synapse/ vim homeserver.yaml
listeners:
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['127.0.0.1']
resources:
- names: [client, federation]
compress: false
enable_registration: false
registration_shared_secret: "GH7AP4Zcthz02Cmg58sqUgonm7zlwH0f"
Save changes and restart the service:
systemctl restart matrix-synapse
Verify:
ss -plnt systemctl status matrix-synapse
Step 3 – Generate SSL with Let’s Encrypt
Generate an SSL certificate using Certbot to secure your Matrix Synapse. Install Certbot:
sudo apt install certbot -y
Create an SSL certificate:
certbot certonly --rsa-key-size 2048 --standalone --agree-tos --no-eff-email --email user@hakase-labs.io -d hakase-labs.io
Your SSL certificates are now located in ‘/etc/letsencrypt/live/domain.com/’:
ls -lah /etc/letsencrypt/live/domain.com/
Step 4 – Setup Nginx as a Reverse Proxy
We’ll configure Nginx to serve as a reverse proxy for Matrix Synapse.
Install Nginx:
sudo apt install nginx -y
Create a virtual host configuration for Matrix:
cd /etc/nginx/sites-available/ vim matrix
server {
listen 80;
server_name hakase-labs.io;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name hakase-labs.io;
ssl_certificate /etc/letsencrypt/live/hakase-labs.io/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/hakase-labs.io/privkey.pem;
location /_matrix {
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
client_max_body_size 10M;
}
}
server {
listen 8448 ssl;
server_name hakase-labs.io;
ssl_certificate /etc/letsencrypt/live/hakase-labs.io/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/hakase-labs.io/privkey.pem;
location / {
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
Activate the configuration and restart Nginx:
ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/ nginx -t systemctl restart nginx systemctl enable nginx
Verify Nginx is operational:
ss -plnt systemctl status nginx
Step 5 – Configure UFW Firewall
Ensure security by setting up the UFW firewall:
for svc in ssh http https 8448 do ufw allow $svc done
Enable UFW:
ufw enable ufw status numbered
Step 6 – Register a New User
Create a new user for Matrix Synapse:
sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
New user localpart [root]: changbin
Password:
Confirm password:
Make admin [no]:
Sending registration request...
Success!
Your new Matrix user is now registered.
Step 7 – Testing
Testing Matrix Synapse Federation
Visit the Matrix Synapse Federation Tester:
https://federationtester.matrix.org/
Enter your domain and click ‘Go‘. Success is shown below:
Test Matrix Login
Access Matrix via the Riot web client:
Click ‘Sign In‘ and choose to use your Matrix Synapse server:
Enter your domain, then ‘Next‘.
Enter your credentials and sign in. You should see the following page:
You will be asked a few additional security questions. After you’ve successfully logged in, you should see this screen:
Conclusion
Congratulations! You have successfully installed and configured Matrix Synapse with Nginx reverse proxy and enabled Federation support on Ubuntu 20.04.
Frequently Asked Questions (FAQ)
1. What is Matrix?
Matrix is an open standard for decentralized communication, providing RESTful HTTP JSON APIs to facilitate real-time communication without central control points.
2. Why use Synapse?
Synapse is the reference implementation of a Matrix home server, which allows users to run their own communication server, ensuring privacy, security, and ownership over data.
3. Is it necessary to have a domain name?
Yes, a domain name is required for configuring SSL certificates and setting up federated communication within the Matrix ecosystem.
4. What is the purpose of using Nginx?
Nginx serves as a reverse proxy to handle client requests and provide SSL encryption, enhancing the security and availability of your Matrix home server.
5. How can I ensure my server is secure?
Implement security measures such as a firewall (e.g., UFW), SSL encryption (using Let’s Encrypt), and regularly update your server to protect against vulnerabilities.