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

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

In this tutorial, we will be learning how to install and configure Matrix Synapse on an Alibaba Cloud ECS with 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 fresh Alibaba Cloud ECS instance with Ubuntu 16.04 server installed.
  • A static IP address is configured on the instance
  • A Root password is setup on the instance.

Launch Alibaba Cloud ECS Instance

First, log in to your https://ecs.console.aliyun.com">Alibaba Cloud ECS Console. Create a new ECS instance, choosing Ubuntu 16.04 as the operating system with at least 2GB RAM. Connect to your ECS instance and log in as the root user.

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

Before starting, you will need to install Nginx web server to your system. You can install Nginx easily by running the following command:

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

Synapse is written in python but some of the libraries it uses are written in C. So you will need to install C compiler and other dependencies to your system. You can install all of them using the following command:

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

By default, Matrix Synapse is not available in Ubuntu 16.04 default repository. So you will need to install it from source.

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 https://github.com/matrix-org/synapse/tarball/master

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 synapse.app.homeserver --server-name example1.com --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 'example1.com' 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

Matrix Synapse is now up and listening on port 8448. Now, you will need to configure Nginx to listen for these requests and pass them on to 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 example1.com www.example1.com;

    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

Matrix Synapse and Nginx is now installed and configured, it's time to access Matrix Synapse web interface.

Open your web browser and type the URL http://example1.com:8008, 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

Riot is a glossy Matrix client built on top of matrix-react-sdk with an emphasis on performance and usability. Riot is very convenient to use chat applications from the desktop.

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 https://riot.im/packages/debian/ xenial main

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

wget https://riot.im/packages/keys/riot.asc
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

Alibaba Cloud Container Service can be integrated with Server Load Balancer, VPC, and other cloud services, allowing you to manage container applications from the console or terminal. The product maintains compatibility with native Kubernetes and provides security, high availability, and stable upgrading services. It is a fully managed cloud container management service that supports native Kubernetes and integrates with other Alibaba Cloud products. It replaces the need to install, operate and scale your container cluster infrastructure. Being a fully-managed service, Container Service for Kubernetes helps you to focus on your applications rather than managing container infrastructure.

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.

0 0 0
Share on

Alibaba Clouder

881 posts | 133 followers

You may also like