This article describes the steps one can take to install 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.
How to 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.
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.
Login with the admin account, and you are done.
That should do it!
This post showed you how to set up your Matrix Synapse server on Ubuntu Linux. Please use the comment form below if you find any errors above or have something to add.