How to Create a Chat Server Using Matrix Synapse on Ubuntu 16.04

By Hitesh Jethva, Alibaba Cloud Tech Share Author. Tech Share is Alibaba Cloud’s incentive program to encourage the sharing of technical knowledge and best practices within the cloud community.

Matrix is an open source protocol for real-time communication, Instant Messaging and VoIP. It is specially designed to allow a user with accounts at one communications service provider to communicate with users of a different service provider via online chat and Voice over IP. Matrix uses home servers to store your account information and chat history. Homeserver plays a key role to connect users. You can access Matrix server by either using a web browser or many other clients like, Riot, bots, bridges, servers and other implementations of the Matrix protocol.


  • Provides a RESTful HTTP API for creating and managing the distributed chat servers.
  • Provides advanced chat features such as VoIP and Video calls.
  • Allow us to use email addresses, phone numbers, Facebook accounts to authenticate, identify and discover users on Matrix.
  • Supports various clients including, Riot, Tensor, Quaternion, Fractal, palaver and much more.

In this tutorial, we will learn how to install and configure Matrix Synapse on an Alibaba Cloud Elastic Compute Service (ECS) instance with Ubuntu 16.04.


  • A static IP address is configured on the instance
  • A Root password is setup on the instance.

Launch Alibaba Cloud ECS Instance

Once you are logged into your Ubuntu 16.04 instance, run the following command to update your base system with the latest available packages.

apt-get update -y

Install Nginx

apt-get install nginx -y

Once Nginx is installed, start Nginx service and enable it to start on boot time using the following command:

systemctl start nginx
systemctl enable nginx

Next, you can proceed to install Matrix Synapse.

Install Required Dependencies

apt-get install build-essential python2.7-dev libffi-dev python-pip python-setuptools sqlite3 libssl-dev python-virtualenv libjpeg-dev libxslt1-dev -y

Install and Configure Matrix Synapse

First, create virtual environment for Synapse using the following command:

virtualenv -p python2.7 ~/.synapse
source ~/.synapse/bin/activate

Next, upgrade pip and setup tools with the following command:

pip2.7 install --upgrade pip
pip2.7 install --upgrade setuptools

Finally, install Synapse from source using the following command:

pip2.7 install

Next, you will need to generate a configuration file for Synapse. First, change the directory to the ~/.synapse and generate configuration file using the following command:

python -m --server-name --config-path homeserver.yaml --generate-config --report-stats=yes

You should see the following output:

A config file has been generated in 'homeserver.yaml' for server name '' with corresponding SSL keys and self-signed 
certificates. Please review this file and customise it to your needs.
If this server name is incorrect, you will need to regenerate the SSL certificates

Next, you will need to create at least one user on your server to use a Matrix client. First, activate the Synapse source and start Synapse service using the following command:

source ~/.synapse/bin/activate
synctl start

Next, register a new matrix user using the following command:

register_new_matrix_user -c homeserver.yaml https://localhost:8448

You will be asked to enter username and password as shown below:

New user localpart [root]:admin
Confirm password:
Make admin [no]: Yes
Sending registration request...

Configure Nginx for Synapse

You can do this by creating /etc/nginx/sites-available/matrix.conf file:

nano /etc/nginx/sites-available/matrix.conf

Add the following lines:

server {
listen 80;
listen [::]:80;
server_name; location /_matrix {
proxy_pass http://localhost:8008;
location ~ /.well-known {
allow all;

Save and close the file, when you are finished. Then enable matrix virtual host file using the following command:

ln -s /etc/nginx/sites-available/matrix.conf /etc/nginx/sites-enabled/

Next, test the Nginx configuration for any syntax error with the following command:

nginx -t

If everything is fine, you should see the following output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Finally, restart Nginx service to apply these changes:

systemctl restart nginx

Access Matrix Synapse Web Interface

Open your web browser and type the URL, you will be redirected to the following page:

Provide your Matrix username, password and server URL, then click on the Login button. You should see the following page:

Install and Use Riot

By default, Riot is not available in Ubuntu 16.04 default repository. So you will need to add Riot repository to the remote system.

On the remote system. Run the following command:

nano /etc/apt/sources.list

Add the following lines:

deb xenial main

Save the file, when you are finished. Then download and add GPG key to APT using the following command:

apt-key add riot.asc

Finally, update the APT repository and install Riot using the following command:

apt-get update -y
apt-get install riot-web -y

Once the installation is completed, open Riot from Unity Dash. You should see the following image:

Here, provide your Matrix server URL, username and password. Then click on the Sign In button. You should see the following image:

Congratulations! You have successfully installed Matrix server and Client to your system. All registered user now easily chats with each other using Riot chat client.

Related Alibaba Cloud Products

Container Registry makes building, running, and maintaining a registry simple. Container Registry allows you to manage images throughout their entire lifecycle by providing secure image hosting, stable image building services as well as convenient image permission features. The product supports image hosting in multiple regions and integrates with other cloud container services, providing a one-stop solution for using Docker in the cloud. Container Registry is available at no cost for Alibaba Cloud account users.


Follow me to keep abreast with the latest technology news, industry insights, and developer trends.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store