How to Configure Matrix Synapse Chat Server and Riot client 10

If you want to understand in more detail the processes of setting up and providing comprehensive security for the local and network infrastructure, built on the basis of the Linux OS, I recommend that you get acquainted with Linux Security Online Course in OTUS. The course is not for beginners, for admission you need to go.


Earlier, I talked about installing and configuring the mattermost corporate messenger, an early fork of the now popular slack. In that article, I listed the pros and cons of this messenger that are relevant to me. I had a chance to see him in the work of a small team. In general, the solution is not bad, but personally I wanted more than there is. In the comments, I was advised to pay attention to matrix, which I do. This article will be my introduction and installation and initial setup guide. I have no practical experience using matrix, since I have not done any real implementations yet, but I have plans.

If you pick up a chat server and check various options, I recommend that you also look at the MyChat server. I tested it and described it in sufficient detail. Perhaps it will suit you more than anything else.

The information on Matrix Synapse is googled without problems, so I won’t tell you in detail what it is. Briefly go over the main:

  1. Matrix is ​​an open protocol for decentralized communication. It can be implemented in various servers and instant messengers.
  2. Synapse – a local server that runs on the matrix protocol, provides the ability to connect and communicate clients.
  3. Riot is a client that can connect to any server running the matrix protocol, including synapse. Presented as a desktop or web version that can be installed on your server.

Next, we will install the local version of Matrix Synapse to connect our clients. We will host the Riot web client on the same server. All this business will provide ssl certificate. In general, the output should be a ready-made free local solution for a corporate chat.

I want to warn you right away that my description does not fit a ready-made guide that will allow you to configure everything with a simple copy-paste. This guide is for matrix and riot, you should at least be able to configure a web server with nginx, install certificates, proxy requests if you need it.

Installing Matrix Synapse home server

I will install the chat server on CentOS 7. If you do not have a server yet, then see my articles on installing and basic configuration of centos.

I immediately draw attention to the fact that selinux will be disabled on my server. How to do this, see the article on configuring the server, the link to which is above.

To work, the synapse server requires Python 2.7, which is installed by default on CentOS 7. You can verify this by typing in the console:

# python -V Python 2.7.5

The synapse chat server can use various databases. By default, it works with SQLite, which is suitable only for the test. In production, using this database is a bad decision. But even for the test I couldn’t manage to configure work with SQLite. By default, CentOS installs a very old version of the database. When using it, an error occurs and the server does not work. I updated the database to the latest version, but as it turned out, there are problems with it too. I read the discussion on this topic and realized that the problem is common, not unique, so I decided not to understand it. Instead, I will immediately use postgresql, which is the most reliable and reasonable choice.

This is where we start. Install postgresql on Centos 7. I have the following version of the system installed:

# cat /etc/redhat-release  CentOS Linux release 7.4.1708 (Core)

I install the repository corresponding to my version:

# rpm -Uvh

We put the latest version of postgresql at the time of writing:

# yum install postgresql10-server postgresql10-contrib

Initialize the database:

# /usr/pgsql-10/bin/postgresql-10-setup initdb

We edit the configuration file to enable MD5 authentication.

# mcedit /var/lib/pgsql/10/data/pg_hba.conf

Change the lines at the very end:

host all all ident host all all ::1/128 ident


host all all md5 host all all ::1/128 md5

We start PostgreSQL and add it to autoload:

# systemctl start postgresql-10 # systemctl enable postgresql-10

We go into the system under the postgres user:

# su - postgres

Create a database user:

$ createuser synapse

We launch the console client to work with the database:

$ psql

Set userpass password for the newly created user:

# ALTER USER synapse WITH ENCRYPTED password 'userpass';

Create a database for the matrix synapse chat server:

# CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER synapse;

Exit the management console and postgres account.

# q # exit

Install a few more packages needed for synapse to interact with postgresql.

# yum install postgresql-devel libpqxx-devel.x86_64

The preparatory steps are completed, now you can install the server itself. To do this, install the necessary dependencies.

# yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel redhat-rpm-config python-virtualenv libffi-devel openssl-devel # yum groupinstall "Development tools"

Install the Python package manager pip.

# wget # python

Create a virtual environment for the synapse application. It is used to isolate a separate python project. The project will use its own directories and libraries, without interacting with the global environment.

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

Install the necessary python packages.

# pip install --upgrade pip virtualenv six packaging appdirs psycopg2

Updating setuptools:

# pip install --upgrade setuptools

Install the matrix synapse server itself.

# pip install

Before starting the server, you must create a configuration file. We do it.

# cd ~/.synapse # python -m --server-name --config-path homeserver.yaml --generate-config --report-stats=yes

I am using the domain name for my chat server I draw attention to this parameter. It is important if you want to use a full ssl certificate and https connections. Use a real domain name, for which you will then receive a certificate. After executing the command, you will get something like this:

Creating a configuration for synapse server

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

By default, in the configuration file homeserver.yaml will be instructed to use the SQLite database. We comment on the lines responsible for this setting and add parameters for connecting the previously created postgresql database.

#database:  # The database engine name  #name: "sqlite3"  # Arguments to pass to the engine  #args:  # Path to the database  #database: "/root/.synapse/homeserver.db"  database:  name: psycopg2  args:    user: synapse    password: userpass    database: synapse    host: localhost    cp_min: 5    cp_max: 10

I draw attention to the indentation in the configuration file. They are fundamentally important. It should be exactly as shown – database without indentation, name, args one space from the beginning of the line. Everything else is two spaces.

This completes the installation of the server, move on.

Using SSL’s Let’s Encrypt Certificate

Before starting the server setup, install a full ssl certificate on it. If you do not need this, you can skip this item. You can just look at the chat with the self-signed certificate that we received earlier. But there is one caveat. The Riot client that I will use to connect to the server will not work with a self-signed certificate. He will swear at him during the connection. So if you want to fully test the work of the Riot messenger in conjunction with matrix synapse, you will have to install a normal certificate.

My chat server does not directly look on the Internet. I will proxy all connections to it through the web server on which nginx is installed. Therefore, obtaining a certificate must be performed on it. If your matrix server will look directly on the Internet, then you need to configure the receipt of the ssl certificate on it.

Before receiving the certificate, I drew about such a virtual domain config for nginx.

server {  listen 80;  server_name;  location /.well-known {  root /web/sites/;  } }

I talked in detail about obtaining Let’s Encrypt certificates in an article on setting up a web server. For all the details you can look there. Here, without detailed explanations, we carry out the necessary actions.

Install certbot.

# yum install certbot

We start the certificate request.

# certbot certonly

When you first start on the server, you will need to register a new account on the server and specify the mailbox. I have already done all this before, so just select the type of domain confirmation:

2: Place files in webroot directory (webroot)

Next I indicate the domain name:

Please enter in your domain name(s) (comma and/or space separated) (Enter 'c' to cancel):

I specify the directory of the web server:

Input the webroot for (Enter 'c' to cancel): /web/sites/

Received a certificate. Further I draw the following config for the nginx virtual host already for work on https.

upstream matrix {  server; }  server {  listen 80;  server_name;  return 301 https://$server_name$request_uri; }  server {  listen 443 ssl http2;  server_name;  ssl on;  ssl_certificate /etc/letsencrypt/live/;  ssl_certificate_key /etc/letsencrypt/live/;  ssl_session_timeout 5m;  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;  ssl_dhparam /etc/ssl/certs/dhparam.pem;  ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';  ssl_prefer_server_ciphers on;  ssl_session_cache shared:SSL:10m;  location /.well-known {  root /web/sites/; }   location / {  client_max_body_size 50M;  proxy_set_header Connection "";  proxy_set_header Host $http_host;  proxy_set_header X-Real-IP $remote_addr;  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  proxy_set_header X-Forwarded-Proto $scheme;  proxy_set_header X-Frame-Options SAMEORIGIN;  proxy_pass http://matrix;  } }

On server, the external port 22991 was forwarded to the local 8008. Synapse over an insecure connection works on this port. You need to redirect it to this port, because if you redirect to a secure port that works with its certificate, there will be problems when this local certificate works together with the external Let’s Encrypt.

With a certificate and the server itself synapse figured out. Next, I suggest first installing and configuring a free web client for chat – Riot. If you do not need it, you can immediately proceed to configure the server itself.

Riot Client Installation

You do not have to install your own riot web client version. You can use the public web client, and use it to connect to your server. To do this, specify the address of your server during the connection.

To connect via riot, you must have configured https connection. It won’t succeed in connecting using the usual protocol, there will be an error.

Can't connect to homeserver - please check your connectivity and ensure your homeserver's SSL certificate is trusted.

or like this:

Can't connect; check your SSL settings and trust the server

I tried this way and that, but it turned out to be easier and faster to make an SSL certificate from Let’s Encrypt than to deal with errors. In general, get a certificate in any way convenient for you.

In order to install riot’s own web client, it is enough to download its sources and place them on a web server. The latest version can be downloaded from here – Next, I use the latest version at the time of writing.

# wget # tar -xzvf riot-v0.13.3.tar.gz

Next, copy the contents of the unpacked directory to the root folder of the web server for the domain that you have assigned. In my example, this is /web/sites/

We draw approximately such a config for publishing riot on the web.

# cat /etc/nginx/conf.d/riot.conf
server {  listen 80;  server_name;  return 301 https://$server_name$request_uri; }  server {  listen 443 ssl http2;  server_name;  root /web/sites/;  index index.php index.html index.htm;  access_log /web/sites/ main;  error_log /web/sites/;   ssl on;  ssl_certificate /etc/letsencrypt/live/;  ssl_certificate_key /etc/letsencrypt/live/;  ssl_session_timeout 5m;  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;  ssl_dhparam /etc/ssl/certs/dhparam.pem;  ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';  ssl_prefer_server_ciphers on;  ssl_session_cache shared:SSL:10m;  location /.well-known {  root /web/sites/;  }  }

We re-read the nginx config and you can go to the specified web address to use your riot client. There is a configuration file in the client directory config.sample.json. Rename it to config.json and change the default connection server setting. Indicate your.

"default_hs_url": "",

This is enough to use your own riot web client at the configured address.

Setting up matrix synapse server

We launch the installed server.

# source ~/.synapse/bin/activate # synctl start

If you saw the same conclusion, then everything is in order.

Starting matrix synapse server

Let’s check on which ports the chat service started.

# netstat -tulnp | grep python tcp        0      0  *               LISTEN      26827/python2.7      tcp        0      0  *               LISTEN      26827/python2.7

Port 8448 for encrypted connections, 8008 for regular.

Create Administrator Account

Create the first administrator account.

# register_new_matrix_user -c homeserver.yaml http://localhost:8008 New user localpart (root): admin Password:  Confirm password:  Make admin (no): yes Sending registration request... Success.

Now you can go to the address and log in to the system under the administrator created by the user.

If you have not configured proxying via nginx, then you can go directly to the server with a chat at its ip address – In my case, I see the same page.

There are practically no settings in the web interface. You can only create the necessary rooms and change some user settings. You can also go in and chat in chats, but the standard server interface for this is poor and uninteresting. Later we will connect to the server with a more convenient Riot client, but for now we’ll change some server settings.

Enabling Free Registration

The first thing you need to decide is whether you will have open free user registration, or whether you will create each manually. The parameter in the configuration file is responsible for this. homeserver.yaml

enable_registration: True

I allowed free registration in my example. By default, it is prohibited. If you have a public chat server, then you must configure captcha. Google sync reCAPTCHA is already integrated in synapse. To make it work, you need to register your site in Google –, then specify the following parameters in the config:

recaptcha_public_key: PUBLIC_KEY recaptcha_private_key: PRIVATE_KEY enable_registration_captcha: true

You receive Public and Private keys after registering captcha for your Google domain name.

Set up email notifications

Synapse matrix corporate chat server can send email notifications to various events. These events are configured in user preferences. But in order for the server to be able to send alerts, they must be configured in the configuration of the server itself. To do this, in the config we draw such parameters for sending mail through the local server.

email:  enable_notifs: true  smtp_host: "localhost"  smtp_port: 25  notif_from: "Your Friendly %(app)s Home Server <[email protected]>"  app_name: Matrix  template_dir: res/templates  notif_template_html: notif_mail.html  notif_template_text: notif_mail.txt  notif_for_new_users: True  riot_base_url: ""

We restart the server and check.

# source ~/.synapse/bin/activate # synctl restart

I immediately got an error saying that the file notif_mail.html not found. For a long time I figured out what could be the problem. Then, after all, I realized when I manually downloaded the full source of the server from github that I did not have enough directories res / templates. Looks like they just forgot to put them in an assembly that swings through pip. So you will need to do the same if this bug is not fixed by the time you try to configure your chat server. I did this:

# cd /usr/src # git clone # mv /usr/src/synapse/res ~/.synapse

After that, restart the server again and check.

I spent a lot of time debugging alerts. I did not understand how to clearly configure them and when they will work. It seems that I turn everything on in the profile, I leave the user offline, I send him a chat message. Sometimes an alert arrives after 10 minutes, sometimes not. Where this interval of 10 minutes is configured – did not understand. It seems that in the main config there are some hints at this interval, but it is not explicitly indicated that it affects the time after which the notification will be sent to the mail. Logically, it should be sent immediately if the user is not there, and not wait 10 minutes.

There is probably some kind of mechanism for accumulating alerts, maybe it has some kind of logic of its own, which I did not understand, so it’s not entirely clear to me how alerts work. The template of the messages themselves, by default, is very clumsy; according to it, it’s not really clear where and in what chat the event occurred. Here is an example:

I somehow restored the sequence of events according to chat messages, but in general, everything is not obvious. You can modify this moment yourself, templates can be customized. But it is necessary to understand and spend time. At this point, the product is clearly not ready in its current form for product use.

Also, I could not configure alerts through external mail services. In particular, I tried through a mailbox on Yandex, but nothing came to me. Either the problem with the mail settings, or with the notifications themselves, did not figure it out. Debugging these moments is inconvenient. The log of the server itself is littered with spam requests from web clients. In general, the topic is ambiguous and non-obvious. There is no documentation on it. To understand, in principle, it is possible, in theory it works, but you need to spend time.

Startup chat server with system start

Out of the box, no solution for auto start service is offered after the system boots, if you use the centos system. There is a ready-made package for debian that can be easily installed on the system via apt. Included will be a config for systemd. Our server starts from the root home directory in virtualenv, which is not very convenient for setting up startup. But everything is solved. We draw such a config for systemd along the following path – /etc/systemd/system/synapse.service.

(Unit) Description=Synapse Matrix homeserver  (Service) Type=simple User=root Group=root WorkingDirectory=/root/.synapse ExecStart=/root/.synapse/bin/python -B -u -m -c /root/.synapse/homeserver.yaml ExecStop=/root/.synapse/bin/synctl stop /root/.synapse/homeserver.yaml  (Install)

In general, it is not very correct that the server is running as root for us. But since I have this test, I did not bother and create a separate user and do everything under it. Yes, and remembered this only at the very end, when this config was drawing. Add the server to startup and run:

# systemctl enable synapse # systemctl start synapse

Check if everything is in order.

# systemctl status synapse

Starting the chat server as a service through systemd

It is not very convenient that the server will duplicate its logs to the system log / var / log / messagesbut it’s already trifles. If it really gets in the way, you can fix this thing.


Then you can create rooms, register users, change settings. I will not describe it, everyone can do it in order to understand the product and get to know it better. In general, my impression was ambiguous. The product is not bad, especially in terms of declared functionality. I have not seen the same functionality anywhere for free. If you have a lot of time and desire, then you can finish it to a suitable level when everything that interests you will work normally. But minor bugs and errors that I encountered during the setup process do not inspire me with confidence that all this will work stably for a long time.

I always put stability and reliability in the first place, even to the detriment of functionality. I do not like decisions that require a lot of strength in their support. As a result, they may be more expensive than commercial products. Already now I can imagine how many errors will come out during the next update. Here is my brief summary of the pros and cons of the synapse matrix based on what I managed to try and verify.


  • Extensive free functionality.
  • Own local server
  • Flexible settings for email alerts. Although not very clear settings, but I think, if you look, it will eventually work.
  • Control typing and reading messages. You see when the user reads the message sent to him. This is an important and convenient feature. The same mattermost or do not offer this in the free version.
  • Good customer choice. The same riot is there as a desktop application, for a smartphone and a web version through a browser.
  • Calls between customers. No settings are needed, they work right away.


  • A lot of bugs that you encounter immediately during installation. Forgetting to put the template files in the distribution kit and not fix it. I do not understand this approach.
  • There is no documentation except a little help on github.
  • A lot of questions on the github, mostly with errors. Messages, rooms, users disappear, doesn’t let someone in, etc. I think all this will have to be faced after a large-scale implementation.

Understanding Proxying Requests in Nginx Using ProxyPass

Previous article

Installing Ruby on Rails on Ubuntu 18.04

Next article

You may also like


Leave a Reply

More in centos