Instantly share code, notes, and snippets.

What would you like to do?
Create your own encrypted chat server with Riot and Matrix - CryptoAus 5 July workshop

Running your own encrypted chat service with Matrix and Riot

CryptoAus Sydney Workshop -- 5 July, 2017

What are we doing here?

The goal of this workshop is to teach you how to configure and run your own Matrix/Riot service. By the end of the workshop, you should be able to log into secure chat rooms and invite others to the same server.

Don't panic if you don't finish all of these steps today. You can take these instructions with you and continue/start again at home any time you like.

What are Matrix and Riot?

Matrix and Riot work together to provide a chat service which behaves in a similar way to popular services like Slack. Unlike Slack, however, this tech stack is free and open source. This means you, your team, or your company can easily host your own Matrix servers so that all information that passes through there can remain within the control of your organisation instead of a third party.

With Matrix and Riot, you can run chatbots, integrate Giphy, create new channels for different topics, or start one-to-one conversations. You can also configure audio and video calling. The stack features Slack and IRC integration for those who don’t want to move.

Matrix also provides native support for encrypted chat rooms. If you set it up, chat channels on your server can be end-to-end encrypted. Anyone on your server can verify their fingerprints with each other out-of-channel to make sure that the people in the room are the ones you want there.

Please remember that, as with any encrypted messaging service, the room is only as secure as the people in it. Encryption isn't magic. Don't write anything you wouldn't want to see your name against publicly.


  • A computer
  • Internet connection
  • Basic knowledge of the command-line terminal
  • Putty SSH client (Windows only)
  • Riot client installed on your laptop or phone (get it from or the app store)

Optional pre-requisites

If you want to take your work home with you, you'll also need to supply:

  • Your own domain name (e.g.
  • Virtual Machine (VM) running Debian 8 on a public cloud service (AWS, DigitalOcean etc.) - RAM: 1 Gb RAM (strongly recommended), 512 Mb (minimum)

Installation Guide

In the following sections, we show how you can install your Matrix reference server and connect to it with the first users. By the end of the workshop, (1.) you will have your server running and (2.) a chat client will be connected to the server from one of your devices.

DNS settings

Note: if you just want to learn how Matrix and Riot work today and don't want to mess around with DNS config just yet, ask one of the instructors for temporary domain details, and skip straight to "Installing the Matrix server".

Please remember that all temporary workshop domains and VMs will not live long after the workshop; to run your own service in the real world, you'll need to set up your own permanent infrastructure.

Register a domain

If you don't already have a domain you want to use for this, you can buy one through any domain registrar. If you didn’t set one up before the workshop, it’s going to take too much setup time right now to work with it in this session, so go ahead and ask for one of our temporary hostnames and come back to this later.

Add DNS records to your DNS panel

Add a similar DNS record on your DNS admin panel, where is the public IP address of your designated server: | 300    IN    | A    |

Installing the Matrix server

The following guide will set up Synapse, which is Matrix's reference implementation.

Preparing the machine

First: launch your Debian 8 VM on a public cloud and SSH into the new server.

Note: If you didn't bring your own, you can use one of our temp VMs. Ask our friendly instructors for the login details.

The Matrix/Synapse package lives in a non-standard repository. We're going to add this repository to our machine's list of sources:

echo 'deb jessie-backports main' >> /etc/apt/sources.list

And then we're going to make sure the machine knows that the repo is there:

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

Next, we need to install a few packages that will help us later. Our VMs are very barebones by default. 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 a configuration file to ensure that Matrix knows where to read from. The file needs to be called /etc/apt/sources.list.d/matrix.list

Open this up in your favourite text editor. We are an equal opportunity workshop and take no sides in the text editor wars. If you don't have an editor of choice and want some guidance, ask one of the instructors (or the person next to you) for a recommendation.

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

deb jessie main
deb-src jessie main

Installing Matrix

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

curl | apt-key add -
apt-get update
apt-get install matrix-synapse -y


You might get a python-cffi package conflict error at this point which will cause the matrix-synapse install to fail. If this is the case, run this one-liner to install python-cffi from backports:

apt install python-cffi/jessie-backports

Once that's done, let's try the Matrix install again:

apt-get install matrix-synapse -y

If it's still not working, we suggest a sacrifice to the apt-get gods, or asking an instructor or the person next to you for help.

Configuring the Matrix server

The installation process requires some basic config.

You will be asked to provide a hostname for your server. If you didn't configure your own hostname earlier, use the hostname from the handouts. (e.g.

If asked for reporting anonymous stats, choose ‘no’. Nobody wants that.

Then, start your server:

systemctl start matrix-synapse

Adding encryption support

It's time to encrypt this sucker. Use certbot to generate a Let's Encrypt certificate:

certbot certonly

Choose the "spin up a temporary webserver" option.

And, so you don't have to worry about this every three months or whatever, we can set up certificate auto-renewal.

Run: crontab -e

Insert the following line: @daily certbot renew --quiet --post-hook "systemctl reload nginx"

Configuring nginx

To make this thing truly HTTPS-ready, we need to configure a reverse proxy. We'll 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;

    ssl_certificate     /etc/letsencrypt/live/;
    ssl_certificate_key /etc/letsencrypt/live/;
    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 with the relevant server name of yours.

Once that's saved, restart nginx by running: systemctl restart nginx

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 give it. For small implementations, (>50 users), you probably only need about 512MB of RAM. You can configure this by adding an environment variable to the following file: /etc/default/matrix-synapse:


And to make sure it all takes, restart the service:

systemctl restart matrix-synapse

Register the first Matrix user

One of the things you probably want out of this chat server is to, y'know, chat with people. To do that, we need some user accounts, starting with 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.

Enable user registration with the GUI (optional)

To save 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.

Don't make them all admins, yeah?

Time to Riot

Riot is the fancypants 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

One you have it, run it.

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.

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: (e.g.

Identity server URL: (e.g.

Now log in with the user you configured in your server in the previous section of this doc.

Create a new secure room

  • Create a new room
  • Once in the room, click on the gear icon and turn on end-to-end encryption by ticking ‘Enable encryption’
  • Click ‘Save’

Security checkup

  • Who can access this room? -> Only people who have been invited (default)
  • Who can read history? -> Members only (since they joined)
  • URL previews -> Disable URL previews
  • To invite users in the room -> Moderator

More config

There's a bunch of stuff you can do with the Riot client. Explore the interface.

Here are some things to try:

  • Invite your friends to the room you just created
    • compare key fingerprints before chatting in encrypted rooms
  • Have someone else create a room (or prevent someone else from creating a room)
  • Integrate Giphy for maximum lulz
  • Add a GitHub bot

Additional things to do after the workshop

There's server config we skipped over because this is a pretty short workshop.

We'd recommend going back to your server and doing some of these things later if you actually want to use Matrix/Riot properly.

  • Deploy a firewall with iptables
  • Configure auto-update (unattended-upgrades)
  • Protect your Debian server with two-factor authentication
  • Replace sqlite database with psql (if you expect lots of users):
  • Configure email notifications (enable_notifs)
  • Add room integrations
    • GitHub bot
    • RSS bot
    • Giphy
  • Add TURN support for audio/video calls

You can find all of the docs you could ever need (and the Matrix community itself) right here:

Post-event infra

To set up a Matrix server on your own infrastructure, you will need to provide your own domain name and your own server. We used AWS EC2 t2.micro instances as the servers for our workshop today - you may need something bigger if you have a large organisation to host.

After you buy a domain, configure your DNS settings as outlined in the "Add DNS records" section above, and then add these into your server's config in place of our temporary ones in the guide. Don't forget to generate another SSL cert through Let's Encrypt for your new hostname.

Make sure to restart Matrix after you're done making config changes, or they won't work properly.

Happy chatting!


If you are interested more workshops like this, subscribe to our Meetup groups:

Calling for volunteers! If you'd like to help us to make more workshops like this, get in touch with us:

Original authors of this howto:

Earlier versions of this howto is available on:

This workshop is distributed under a CC BY-SA 4.0 license

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment