Matrix is an open standard communication protocol for decentralized real-time communication. It is executed as home servers which are distributed over the internet, due to this, there is no single point of control or failure.

Updated 05 July 2018 v1.0.

Disclaimer: We are not affiliated in any way to these Companies, this article is 100% our findings. There is no affiliate marketing in place through the links provided below, they’re for your convenience.

How we write our reviews: To ensure an unbiased and thorough review, all apps are tested:
• In real time i.e. we use it on real projects.
• Among different team members located in different countries.
• With different devices and operating systems.
• For a minimum of two weeks, four on average.
• The article is peer-reviewed by other team members then sent to the app developers for final review.

Contents of this article.

Matrix server installation guide.
DNS settings.
Installing Synapse.
Adding encryption support.
Configuring nginx.
Fine-tuning Synapse.
Run Synapse.
Register your first Matrix user.
Enabling self-service user registrations.
Running Riot.
Pros of running your own server.
Cons of running your own server.

1. Matrix server installation guide.

Matrix is an open standard communication protocol for decentralized real-time communication. Matrix is executed as home servers which are distributed over the internet, due to this, there is no single point of control or failure. Matrix offers a RESTful HTTP API for generating and managing the distributed chat servers which comprises of receiving and sending messages, inviting and managing members of a chat room, managing user accounts, and it also provides advanced chat features like VoIP and Video calls, etc. Matrix also establishes a secure synchronization between home servers which are distributed across the globe.

Synapse was written by the Matrix team and is the implementation of Matrix home server. The Matrix ecosystem consists of the network of many federated home servers distributed all over the world. A Matrix user uses a chat client to connect to the home server, which in turn connects to the Matrix network. Home server stores the chat history and the login information of that particular user.

In the following section, we’ll show you how to install your Matrix reference server and connect it with your first user(s).

There are two basic things you need to run your private Matrix service:
• Domain name (e.g. ubinodes.org).
• A virtual server running Debian 8 on a cloud service (AWS, DigitalOcean, Vultr, etc.) or a physical server.
• Basic knowledge of the Linux CLI.

For this guide, we will use ubinodes.org.

2. DNS settings.

First, you have to register a domain name and fire up your DNS admin panel. You need to create a DNS record like this:

ubinodes.org 300 IN A 1.2.3.4

3. Installing Synapse.

After completing the above step, the following guide helps you set up Synapse, which is Matrix's reference home server implementation.

3.1 Prepare your server.

• Launch a virtual machine running Debian 8 on your preferred cloud provider and SSH into the host. The instructions below assume that you are root on the server.
• As Matrix/Synapse package lives in a non-standard repository, we are going to add the repo to our machine's package repository:

# echo 'deb http://ftp.debian.org/debian jessie-backports main' >> /etc/apt/sources.list

• And then we need to make sure that Debian knows that the repo is there:

# apt-get update && apt-get dist-upgrade -y

• Next, we need to install a few packages that would be useful later. Our VM's are set to basics by default. So, you need to run the following:

# apt-get install -y apt-transport-https lsof curl python python-pip
# apt-get install -y certbot -t jessie-backports

• At this point, we need to add another software repository. Create /etc/apt/sources.list.d/matrix.list and open this up in your preferred text editor.

• Inside /etc/apt/sources.list.d/matrix.list, add the following two lines:

deb https://matrix.org/packages/debian/ jessie main
deb-src https://matrix.org/packages/debian/ jessie main

3.2 Installing Synapse.

• With that out of the way, it's time to actually install Matrix. Run the following:

# curl https://matrix.org/packages/debian/repo-key.asc | apt-key add -
# apt-get update
# apt-get install matrix-synapse -y

• If the package installs without hiccups along the way move to the next section "Adding encryption support".
• If python-cffi is broken, you might get a python-cffi package conflict error at this point, which will cause the matrix-synapse install to fail.
• Simply run this command to install python-cffi from backports:

# apt install python-cffi/jessie-backports

• Once the backported package is installed, try installing Synapse again:

# apt-get install matrix-synapse -y

• You will be asked to provide a host name for your server, which in this tutorial we used myserver.example.com

4. Adding encryption support.

• Synapse should expose the Matrix service over SSL, so we need to request for a new certificate. You may reuse your existing SSL certificate if you already have one. For myserver.example.com. Otherwise, you can get a new one from Let's Encrypt.
• The next step is to use certbot to generate a Let's Encrypt certificate.

# certbot certonly

• Choose the "spin up a temporary web server" option.
• The certificate is valid for three months. To configure auto-renewal, we need to add certbot to the system crontab file:

# crontab -e

• Insert the following line:

@daily certbot renew --quiet --post-hook "systemctl reload nginx"

5. Configuring nginx.

• To make this HTTPS-ready, we need to configure a reverse proxy. We will use nginx for this, so install it:

# apt-get install nginx -y

• Then add the following configuration to /etc/nginx/conf.d/matrix.conf:

 server {
    listen 443 ssl;
    server_name love4aviation.fr;

    ssl_certificate     /etc/letsencrypt/live/love4aviation.fr/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/love4aviation.fr/privkey.pem;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    location /_matrix {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

• Make sure you replace ubinodes.org with the relevant server name.
• Once that's saved, restart nginx by running:

# systemctl restart nginx

6. Fine-tuning Synapse.

• Add a shared secret to the config file at /etc/matrix-synapse/homeserver.yaml:

Registration_shared_secret: <add random characters here, whatever you want your secret to be>

• Synapse caches conversation information in RAM where possible, and will use as much as you allow. For small implementations, (>50 users), you probably need about 512MB of RAM.
• You can configure this by adding the SYNAPSE_CACHE_FACTOR environment variable to /etc/default/matrix-synapse

`SYNAPSE_CACHE_FACTOR 0.02``

7. Run Synapse.

• Apply the settings by enabling and restarting the Synapse service:

# systemctl restart matrix-synapse
# systemctl enable matrix-synapse

8. Register your first Matrix user.

One of the major things you probably want this chat server for is a secure means of communication for your business. To do that, we need some user accounts, let’s start by creating your own.
• Create a new user by running the following, and answering the prompts:

# register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml https://localhost

- New user localpart [root]: {add your name/handle here}
- Password:
- Confirm password:
- Make admin [no]: yes
- Sending registration request…
- Success.

9. Enabling self-service user registrations.

Optional: to avoid having to register new users via CLI on your server every time, you can enable GUI user registration through the Riot client by editing /etc/matrix-synapse/homeserver.yaml and changing the following setting:

enable_registration: true

Otherwise, to register additional users, run register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml https://localhost again to manually configure more accounts. Make sure you don’t set them all as admins.

Run your end-to-end encrypted chat server using Matrix and Riot.

10. Running Riot.

Riot may try to auto-connect you to their default servers. If this happens, log out. We want the Riot login screen for the next part.Riot is the front-end client for the server we just set up. If you don't have it already, you can download the app for your OS of choice at https://riot.im/

Let's connect Riot to the server we just configured.
Add your hostname (either your BYO hostname or the here's-what-we-prepared-earlier hostname on your handout):

Home server URL: https://ubinodes.org Identity server URL: https://ubinodes.org

You can now join any room on the Matrix network. Here is our public room: #foo:Ubinodes.org.

11. Pros of running your own server.

• You own your data. You can run a script to clean up deleted rooms whenever you want.
• Increased settings for privacy, compared to vector.im users, you can decide what you wish to share and what not to.
• You can have your own personal server for identity rather than using vector.im’s server. This allows you to use your own domain name to ID your team members or use LDAP etc. One of such identity service is mxisd:
• Noticeably faster than using the Matrix’s free server.
• Gives business the opportunity to use their own domain for authentication. In various public rooms, there are different people from everywhere, if only team members are able to register for their account by using the organization’s domain, it shows that the users are onto the main organization itself thus, it helps fight social engineering.

12. Cons of running your own server.

• Difficult to setup, the firewall must be carefully configured. The organization must have a skilled system admin for server maintenance.
• They say it is decentralized but it’s not, it is actually federated. To achieve redundancy you must run at two servers least, one for hosting the rooms, while the other one serves as the gateway for users, that way data from mother room is pushed to the edge rooms, hence creating redundancy. However, if the mother room is down, other rooms will be affected.
• When running your own identity server it must connect with vector.im otherwise if the server goes down, users won’t be able to reuse their ID to reconnect to Matrix.
• When running your own ID server, you have to set up and maintain your own plugin instead of just using Vector.im, which isn’t worthwhile.

13. Conclusion.

It is highly recommended to run Matrix home servers on a dedicated domain name, to limit any malicious user-generated content served to web browsers a Matrix API from being able to attack web apps hosted on the same domain. This is particularly true of sharing a Matrix web client and server on the same domain.

How to run an end-to-end encrypted chat server using Matrix and Riot.