Workshop Instructor:
- Lilly Ryan @attacus_au
This workshop is distributed under a CC BY-SA 4.0 license.
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.
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. If you are frequently sharing sensitive things like passwords, internal URLs, or business information as part of your work - this workshop is for you!
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 (there’s always at least one: https://xkcd.com/1782/).
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 (BYO or the venue wifi. If you're using the venue wifi, please be considerate.)
- Basic knowledge of the Linux terminal, SSH, and command line text editors
- Riot client installed on your laptop or phone (get it at https://riot.im/)
e.g.:
server01.securechatworkshop.com. | 300 IN | A | 1.2.3.4
_matrix._tcp.server01.securechatworkshop.com. | 300 IN | SRV | 10 0 443 server01.securechatworkshop.com.
The following guide will set up Synapse, which is Matrix's homeserver implementation.
First: launch your Debian 9 VM, and SSH in.
You'll need to be a privileged user to run most of these commands. You can do this by running sudo -i.
Installing prerequisites:
apt-get install apt-transport-https build-essential python3-dev libffi-dev \
python-pip python-setuptools sqlite3 \
libssl-dev python-virtualenv libjpeg-dev libxslt1-dev
Install Matrix. Run the following:
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/matrix-org.list
apt-get update
apt install matrix-synapse-py3
The installation process requires some basic config.
You will be asked to provide a hostname for your server.
(e.g. server01.securechatworkshop.com)
If asked for reporting anonymous stats, choose ‘no’. Nobody wants that.
Then, start your server:
systemctl start matrix-synapse
Install certbot:
echo 'deb http://ftp.debian.org/debian stretch-backports main' >> /etc/apt/sources.list
apt-get update && apt-get dist-upgrade -y
apt-get install -y certbot -t stretch-backports
Run: certbot certonly (add the --register-unsafely-without-email flag if you want. Don't use this flag in prod - but this is only a temporary server...)
Choose the "spin up a temporary webserver" option.
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;
server_name matrix.mydomain.com;
ssl_certificate /etc/letsencrypt/live/matrix.mydomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/matrix.mydomain.com/privkey.pem;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
Make sure you replace matrix.mydomain.com with the relevant server name.
Once that's saved, restart nginx by running:
systemctl restart nginx
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>
In that same config file, we also need to comment out the following if we want to allow any Matrix user:
#trusted_third_party_id_servers:
# - matrix.org
# - vector.im
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:
SYNAPSE_CACHE_FACTOR 0.02
And to make sure it all takes, restart the service:
systemctl restart matrix-synapse
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.
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!
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 https://riot.im/
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. server01.securechatworkshop.com)
Identity server URL: (e.g. server01.securechatworkshop.com)
Now log in with the user you configured in your server in the previous section of this doc.
- Click on the gear icon and turn on end-to-end encryption by ticking ‘Enable encryption’
- Click ‘Save’
- 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
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
- Enable voice and video calling
- Try the mobile client
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): https://github.com/matrix-org/synapse/blob/master/docs/postgres.rst
- Configure email notifications (
enable_notifs) - beware, may leak sensitive data! - Add room integrations
- GitHub bot
- RSS bot
- Giphy
- Add TURN support for audio/video calls (this is also not 100% secure, use with caution)
- Set up certificate auto-renewal for Let's Encrypt by running
crontab -eand inserting the following line:@daily certbot renew --quiet --post-hook "systemctl reload nginx"
You can find all of the docs you could ever need (and the Matrix community itself) right here: https://matrix.org/docs/guides/faq.html#servers
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!
This workshop was originally developed for the B-Sides Canberra 2017 conference by Lilly Ryan and Gabor Szathmari.