billysoftacademy.com

Learn how to create a Chat Server Using Matrix Synapse and Element on Ubuntu 22.04 LTS

Introduction

Matrix is a platform that offers open APIs for secure, decentralized communication that is end-to-end encrypted. By utilizing a network of federation servers, it allows users to communicate in real-time via instant messaging, voice calls, and even IoT devices. The account information and chat history are securely stored on homeservers. Users have the option to either use a server hosted by someone else or host their own Matrix server, which provides them with greater control over their data. In case of a server failure, the decentralized nature of the servers ensures that the communication can continue on other servers. Synapse is a widely used implementation of Matrix homeserver that was created by the Matrix.org team and is written in Python. In this guide, we will show you how to install Matrix Synapse and Element web client on an Ubuntu 22.04 server.

Requirements

The following is a list of items needed to complete this installation successfully:
1) A computer with 4GB RAM, a dual core processor and 50GB of free disk space
2) An SSH client such as Putty or the macOS terminal app
3) Linux Ubuntu 22.04 LTS or any newer version
4) A stable internet connection
5) Cloud servers: A domain name and a public static IPv4 or IPv6 address.

Overview

The following is an overview of the steps covered in this guide:
1) Configuring the firewall and installing matrix synapse.
2) Installing PostgreSQL and NGINX.
3) Installing SSL and configuring synapse.
4) Configuring NGINX and installing Coturn.
5) Installing and configuring Element.

Step 1: Configuring the firewall and installing matrix synapse

To configure Firewall for Matrix Synapse, you need to open HTTP, HTTPS, and port 8448. You can do this using the Uncomplicated Firewall (UFW). To open these ports, you can run the following commands:

sudo ufw allow http
sudo ufw allow https
sudo ufw allow 8448

After opening the required ports, you should check the firewall status using the following command:

sudo ufw status

To install Matrix Synapse, you need to follow these steps:

1. Download and import the GPG key using the following command:

sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
2. Add the Matrix official APT repository using the following command:
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

3. Update the system repositories list using the following command:

sudo apt update
4. Install Matrix Synapse using the following command:
sudo apt install matrix-synapse-py3

During the installation process, you will be prompted to enter your Matrix domain name as the server name. You can change it later in the `/etc/matrix-synapse/conf.d/server_name.yaml` file. You will also be asked if you want to report anonymized statistics. If you don’t want to report the statistics, enter N.

Step 2: Installing PostgreSQL and NGINX

To improve the performance of Synapse, it is recommended to use PostgreSQL instead of SQLite for production environments. Here’s how you can install and configure PostgreSQL:

1. Install PostgreSQL server by running the following command:

sudo apt install postgresql postgresql-contrib

2. Log in to the PostgreSQL shell using the following command:

sudo -su postgres psql

3. Create a Synapse SQL user by running the following command:

CREATE ROLE synapse LOGIN PASSWORD 'yourpassword';

4. Create a Synapse Database by running the following command:

CREATE DATABASE synapsedb OWNER synapse LOCALE 'C' ENCODING 'UTF-8' TEMPLATE template0;

5. Exit the PostgreSQL shell by running the following command:

exit

To install the latest version of Nginx, follow these steps:

1. Add the official Nginx repository by running the following commands:

curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor
sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" sudo tee /etc/apt/sources.list.d/nginx.list

2. Update the system repository list by running the following command:

sudo apt update

3. Install Nginx by running the following command:

sudo apt install nginx
4. Start the Nginx server by running the following command:
sudo systemctl start nginx

Step 3: Installing SSL and configuring synapse

To install SSL, you need to follow the steps below: 1. Ensure that you have the latest version of snapd required to install Certbot by issuing the following commands:
sudo snap install core
sudo snap refresh core
2. Install Certbot by running the command:
sudo snap install --classic certbot
3. Create a symlink for Certbot to the /usr/bin directory using this command:
sudo ln -s /snap/bin/certbot /usr/bin/certbot
4. Issue the SSL Certificate by running this command:
sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m name@example.com -d matrix.example.com
5. Generate a Diffie-Hellman group certificate using this command:
sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096
6. Do a dry run of the SSL renewal process to ensure it works:
sudo certbot renew --dry-run
To configure Synapse, follow the steps below: Do not configure Synapse using the /etc/matrix-synapse/homeserver.yaml file, as it gets overwritten during an APT update. Instead, create files in the /etc/matrix-synapse/conf.d/ directory. Create a database configuration file by running this command:
sudo nano /etc/matrix-synapse/conf.d/database.yaml
Then, paste the following lines in the editor and replace “yourpassword” with the database user set in Step 3: database:
  name: psycopg2
  args:
    user: synapse
    password: 'yourpassword'
    database: synapsedb
    host: localhost
    cp_min: 5
    cp_max: 10
Save the file by pressing CTRL+X, then Y. Create a registration key and store it in the /etc/matrix-synapse/conf.d/registration_shared_secret.key file by running this command:

echo "registration_shared_secret: '$(cat /dev/urandom | tr -cd '[:alnum:]' | fold -w 256 | head -n 1)'" | sudo tee /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
Create a new Matrix user by running this command and type “yes” to set it as administrator:
register_new_matrix_user -c /etc/matrix-synapse/conf.d/registration_shared_secret.yaml http://localhost:8008
Enable public registration by creating a configuration file:
sudo nano /etc/matrix-synapse/conf.d/registration.yaml
Paste the following line:
enable_registration: true
Enable email verification for new users by pasting the following lines:
registrations_require_3pid:
  - email
email:
  smtp_host: mail.example.com
  smtp_port: 587

  # If mail server has no authentication, skip these 2 lines
  smtp_user: 'noreply@example.com'
  smtp_pass: 'password'

  # Optional, require encryption with STARTTLS
  require_transport_security: true

  app_name: 'Example Chat'  # defines value for %(app)s in notif_from and email subject
  notif_from: "%(app)s "
You can disable user verification using the following code:
enable_registration_without_verification: true
Save the file by pressing CTRL+X, then Y. To disable the user’s online status, create a new configuration file:
sudo nano /etc/matrix-synapse/conf.d/presence.yaml
Paste the following lines:
presence:
  enabled: false
Save the file by pressing CTRL+X, then Y. Finally, restart Synapse to apply the changes:
sudo systemctl restart matrix-synapse

Step 4: Configuring NGINX and installing Coturn

To configure Nginx, follow the steps below:

1. Open the Nginx configuration file using the command:

sudo nano /etc/nginx/nginx.conf

2. Add the following line before the line `/etc/nginx/conf.d/*.conf`:

server_names_hash_bucket_size 64;

3. Save the file by pressing `CTRL+X`, then `Y`.

4. Create an Nginx configuration file for Synapse by entering the command:

sudo nano /etc/nginx/conf.d/synapse.conf

5. Copy and paste the following code in the editor. Replace `matrix.example.com` with your server’s domain name:

# enforce HTTPS
server {
    # Client port
    listen 80;
    listen [::]:80;
    server_name matrix.example.com;
    return 301 https://$host$request_uri;
}

server {
    server_name matrix.example.com;

    # Client port
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    # Federation port
    listen 8448 ssl http2 default_server;
    listen [::]:8448 ssl http2 default_server;

    access_log  /var/log/nginx/synapse.access.log;
    error_log   /var/log/nginx/synapse.error.log;

    # TLS configuration
    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/matrix.example.com/chain.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

    location ~ ^(/_matrix|/_synapse/client) {
            proxy_pass http://localhost:8008;
            proxy_http_version 1.1;

            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header Host $host;

            # Nginx by default only allows file uploads up to 1M in size
            # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
            client_max_body_size 50M;
    }
}

6. Save the file by pressing `CTRL+X`, then `Y`.

7. Verify the configuration file syntax using the command:

sudo nginx -t

8. Restart Nginx server using the command:

sudo systemctl restart nginx

To install Coturn, follow the steps below:

1. Install Coturn by running the command:

sudo apt install coturn

2. Open the TURN and UDP ports using the commands:

sudo ufw allow 3478
sudo ufw allow 5349
sudo ufw allow :/udp

3. Issue an SSL certificate for Coturn using the command:

sudo certbot certonly --nginx -d coturn.example.com

4. Back up the default configuration file using the command:

sudo mv /etc/turnserver.conf /etc/turnserver.conf.bak

5. Generate an authentication secret and store it in the configuration file using the command:

echo "static-auth-secret=$(cat /dev/urandom | tr -cd '[:alnum:]' | fold -w 256 | head -n 1)" | sudo tee /etc/turnserver.conf

6. Open the Coturn configuration file using the command:

sudo nano /etc/turnserver.conf

7. Paste the following lines below the authentication secret. Replace `coturn.example.com` with your server’s domain name:

use-auth-secret
realm=coturn.example.com
cert=/etc/letsencrypt/live/coturn.example.com/fullchain.pem
pkey=/etc/letsencrypt/live/coturn.example.com/privkey.pem

# VoIP is UDP, no need for TCP
no-tcp-relay

# Do not allow traffic to private IP ranges
no-multicast-peers
denied-peer-ip=0.0.0.0-0.
denied-peer-ip=10.0.0.0-10.
denied-peer-ip=100.64.0.0-
denied-peer-ip=127.0.0.0-127.
denied-peer-ip=169.254.0.0-
denied-peer-ip=172.16.0.0-172.31.255.255
denied-peer-ip=192.0.0.0-192.0.0.255
denied-peer-ip=192.0.2.0-192.0.2.255
denied-peer-ip=192.88.99.0-192.88.99.255
denied-peer-ip=192.168.0.0-
denied-peer-ip=198.18.0.0-198.19.255.255
denied-peer-ip=198.51.100.0-198.51.100.255
denied-peer-ip=203.0.113.0-203.0.113.255
denied-peer-ip=240.0.0.0-.255
denied-peer-ip=::1
denied-peer-ip=64:ff9b::-64:ff9b::ffff:ffff
denied-peer-ip=::ffff:0.0.0.0-::ffff:.255
denied-peer-ip=100::-100::ffff:ffff:ffff:ffff
denied-peer-ip=2001::-2001:1ff:ffff:ffff:ffff:ffff:ffff:ffff
denied-peer-ip=2002::-2002:ffff:ffff:ffff:ffff:ffff:ffff:ffff
denied-peer-ip=fc00::-fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
denied-peer-ip=fe80::-febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff

# Limit number of sessions per user
user-quota=12
# Limit total number of sessions
total-quota=1200

8. Save the file by pressing `CTRL+X`, then `Y`. Restart Coturn to apply the settings by running the command:

sudo systemctl restart coturn

To create a Synapse configuration file for Coturn, follow the steps below:

1. Open the Synapse configuration file using the command:

sudo nano /etc/matrix-synapse/conf.d/turn.yaml

2. Paste the following lines in the editor. Replace the `turn_shared_secret` value with the value of the `static-auth-secret` variable from the `/etc/turnserver.conf` file.

turn_uris: [ "turn:coturn.example.com?transport=udp", "turn:coturn.example.com?transport=tcp" ]
turn_shared_secret: 'static-auth-secret'
turn_user_lifetime: 
turn_allow_guests: True

3. Save the file by pressing `CTRL+X`, then `Y`.

4. Restart Synapse to apply the configuration using the command:

sudo systemctl restart matrix-synapse

Step 5: Installing and configuring Element

To use Synapse, you can use any of the available Matrix clients. Element is the most popular client and is available as a web app, desktop app, and mobile app. When logging in, add your homeserver address https://matrix.example.com and use the credentials you created in step 6. After logging in, create a secure backup of your encrypted messages and data using a security key or a phrase.

If you want to host your instance of Element web client, follow the instructions below:

Install JSON text processor by running

sudo apt install jq

Create a public directory for Element using

sudo mkdir -p /var/www/element

and switch to the directory using

cd /var/www/element

Then grab the latest version of Element from its GitHub releases page using

latest="$(curl -s https://api.github.com/repos/vector-im/element-web/releases/latest | jq -r .tag_name)", download Element using "$ sudo wget https://github.com/vector-im/element-web/releases/download/${latest}/element-${latest}.tar.gz 

and extract the archive using

sudo tar xf element-${latest}.tar.gz

Create another directory as a soft link using

sudo ln -s element-${latest} current

To update Element in the future, run the following command to update the soft link after extracting the archive:

sudo ln -nfs element-${latest} current

2. Configure Element: Switch to the current directory using “cd current”. Create the Element configuration file using the sample using

sudo cp config.sample.json config.json 

Open the configuration file using

sudo nano config.json

Edit the base_url and server_name attributes referencing your matrix subdomain and the base domain. For example:

"m.homeserver": {
    "base_url": "https://matrix.example.com",
    "server_name": "matrix.element.com"
}

Change the brand name if you want to customize the website title, for example:

"brand": "My Example Chat"

Edit the disable_guests variable to disallow Guests from using Element, for example:

"disable_guests": true

Save the file by pressing CTRL+X, then Y.

3. Generate an SSL certificate for the Element client: Use “sudo certbot certonly –nginx -d element.example.com” to generate an SSL certificate.

4. Create and open the file /etc/nginx/conf.d/element.conf for editing using “sudo nano /etc/nginx/conf.d/element.conf”. Paste the following lines in it:

server {
    listen 80;
    listen [::]:80;
    server_name element.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name element.example.com;
    root /var/www/element/current;
    index index.html;
    access_log  /var/log/nginx/element.access.log;
    error_log   /var/log/nginx/element.error.log;
    add_header Referrer-Policy "strict-origin" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    ssl_certificate /etc/letsencrypt/live/element.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/element.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/element.example.com/chain.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
}

Save the file by pressing CTRL+X, then Y.

5. Verify the Nginx configuration file syntax using “sudo nginx -t”.

6. Restart the Nginx server using “sudo systemctl restart nginx”.

You can access Element via the URL https://element.example.com.

Conclusion

This guide has comprehensively covered the installation and configuration of Matrix Synapse homeserver and Element web client on an Ubuntu 22.04 server. By following these steps, you’ve successfully established a secure and decentralized communication platform that offers features like real-time messaging, voice calls, and even integration with IoT devices.

Here’s a quick recap of the key points achieved:

1. Installed Matrix Synapse, a popular homeserver implementation.
2. Configured Synapse to utilize PostgreSQL for improved performance.
3. Secured communication with SSL certificates for both Synapse and Element.
4. Installed and configured Coturn to enable VoIP functionality.
5. Set up Element, a user-friendly web client for interacting with your Matrix server.

Now you have a fully functional Matrix server ready to use! Remember to customize the configurations further to fit your specific needs, such as user access control and branding for Element.

For ongoing maintenance, keep your server software and Synapse updated to benefit from the latest security patches and features. Additionally, explore the vast array of third-party Matrix clients available to suit different preferences.

Scroll to Top