How to Install Matrix Synapse on Ubuntu

This article describes installing the Matrix Synapse chat server on Ubuntu Linux.

Matrix is an open-source, real-time web-based platform for communications on the internet, supporting federation, encryption, and VoIP.

Synapse is an open-source Matrix home server written and maintained by the Matrix.org Foundation.

With Synapse, you host your server to fit your needs, allowing you to bridge to other chat networks (such as IRC, XMPP, Discord, Telegram, etc.) or to host bots.

Below is how to install and use Matrix Synapse on Ubuntu Linux.

Install Matrix Synapse chat server on Ubuntu Linux

As mentioned above, Matrix is an open-source, real-time web-based platform for communications on the internet, supporting federation, encryption, and VoIP.

Below is how to install Matrix Synapse on Ubuntu Linux.

Install prerequisite packages

Before you can install Synapse on Ubuntu, make sure to install the packages below. They will help you get Synapse installed successfully.

sudo apt update
sudo apt install curl wget gnupg2 apt-transport-https

Add Matrix package repository

By default, Synapse packages are not available in Ubuntu repositories. To install Matrix Synapse, you must first add its repository and key.

Run the commands below to add the Synapse repository GPG key.

sudo wget -qO /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg

After that, run the commands below to add its repository file.

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

Finally, update the Ubuntu package index and install Matrix Synapse.

sudo apt update
sudo apt install matrix-synapse-py3

During the installation, you’ll be prompted to enter the server hostname.

Type in a hostname and continue. After installation, Matrix Synapse service is started and listening on port 8008.

Configure Matrix Synapse

Now that the installation is complete go and configure the Matrix Synapse server.

First, create a secret registration shared key using the following command.

cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

Grab the string and store it somewhere for later. You’ll use it in the configuration file later.

Next, run the commands below to open the Matrix Synapse default configuration file.

sudo nano /etc/matrix-synapse/homeserver.yaml

Then disable registration for new users and define the secret key created above as highlighted below.

# This is set in /etc/matrix-synapse/conf.d/server_name.yaml for Debian installations.

# server_name: "SERVERNAME"
pid_file: "/var/run/matrix-synapse.pid"
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['::1', '127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false
database:
  name: sqlite3
  args:
    database: /var/lib/matrix-synapse/homeserver.db
log_config: "/etc/matrix-synapse/log.yaml"
media_store_path: /var/lib/matrix-synapse/media
signing_key_path: "/etc/matrix-synapse/homeserver.signing.key"
trusted_key_servers:
  - server_name: "matrix.org"

# Enable registration for new users.
enable_registration: false

# If set, allows registration by anyone who also has the shared
# secret, even if registration is otherwise disabled.
registration_shared_secret: "3fUV0Bjfx3Oky1rshdWYsKoytq2EA0j1"

Save the file and exit.

After that, restart the Matrix Synapse server.

sudo systemctl restart matrix-synapse

You should now be able to access its portal using the hostname of the server provider.

http://synapse.example.com:8008

Create Matrix Synapse super user

Now that the server is running run the commands below to create a super user to manage the platform.

sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://synapse.example.com:8008

You will be prompted to create an admin account.

New user localpart [richard]: matrixadmin
Password: 
Confirm password: 
Make admin [no]: yes
Sending registration request...
Success!

The most efficient way to use Matrix Synapse is to run it behind a reverse proxy. Below are two posts that show you how to set up a reverse proxy with either Nginx or Apache.

You may also use the Let’s Encrypt certificate with Sails. Below are two posts that may help you.

That should do it!

Everything’s set up, so now you can connect to your homeserver with any Matrix client and start communicating with others.