Matrix is a modern, open standard for decentralized communications. Matrix boasts a production-ready specification maintained by The Matrix.org Foundation and it’s being used by anyone from small hobbyist collectives to national governments. Essentially, it’s an instant messaging service, but one that can be under your complete control: Your data won’t be snooped through by Big Tech organizations, and it won’t stop existing because one company decides they want to shut it down.
At the heart of Matrix are “homeservers”, individual servers running some software that connects to the Matrix network via federation. You may have heard of and use another federated platform: Email. Much like how email allows users of gmail.com, hotmail.com, or your-own-domain.com to all email each other, you can use Matrix by signing up for a big service like matrix.org, or run one yourself. You can message anyone on Matrix regardless of which homeserver your user and your data is hosted on.
What You’ll Need
To get started, you will need a server running Debian 9 or newer, Ubuntu 16.04 or newer, Arch Linux, or CentOS 7 (CentOS 8 has some unresolved issues with this script at the time of writing). For single-user instances Synapse is fairly lightweight, and you can run it for as little as $5/month from any major VPS provider.
You’ll also need a domain name which you are able to change the DNS records for. You’ll want to create two
A records (subdomains):
element, both pointing to your VPS’s IP address.
Getting the Playbook
You can follow these steps on your own computer or on the server itself. We’re going to download a set of open-source scripts (the Playbook) from GitHub that will automatically install Synapse (the reference Matrix homeserver software) on your VPS. Using Git, download the script repo from GitHub:
git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
This is going to create a folder called
matrix-docker-ansible-deploy , and the rest of these commands are going to be run from within this folder, so you can switch to it now:
Configuring the Playbook
First you’ll want to create a folder to hold your server’s configuration we’ll be setting up in a second. Replace
<your-domain> in these commands with your own domain name, of course:
Next, we’ll want to copy the sample configuration to that new folder:
cp examples/vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml
We’ve created a
vars.yml file in the folder you created which has some basic configuration already included. Open up that file in your favorite text editor to configure your server, it really only takes a few simple changes.
matrix_domainshould be your domain name, without the
matrixsubdomain. This domain is going to be a part of your username, which will look like
@jane:example.com. You wouldn’t want to include the
matrixsubdomain here for the same reason it’d look a bit silly if your email was
matrix_ssl_lets_encrypt_support_emailshould point to any email address of yours. This email address is needed to obtain the SSL certificate for your homeserver, and you likely won’t receive any emails at all, but in case that process fails you’ll get a notification at this address.
matrix_postgres_connection_passwordshould all be set to long, random strings.
You can use
pwgen to generate those long, random strings. They won’t need to be memorable at all, so let’s generate some random data:
❯ pwgen -s 64 1
Run it three times to generate different strings for all of them, just to be safe.
Once you’ve filled out the configuration file, we’re going to create one more file to tell Ansible what your server’s IP address actually is, and then we’ll be set!
Create the file
inventory/hosts and edit it with your favorite text editor. In it, you should add the following:
matrix.<your_domain> ansible_host=<your_VPS_EXTERNAL_IP> ansible_ssh_user=root
If you’re setting up all this configuration on the server you’re actually installing this on rather than your own computer, add
ansible_connection=local to the end of that last line as well.
We’ve finished all the configuration we need! To get the installation started, we’ll need Ansible installed on the computer we made these configuration files on. You can install Ansible via most package managers or manually. For example, on macOS you can install Ansible with:
brew install ansible
Then inside that
matrix-docker-ansible-deploy folder, all you need to run is:
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
This command gets everything installed and ready to go on your server! The fantastic thing about Ansible is that any time you think something’s off with your server, you can just re-run this command. Ansible will automatically check your installation and fix anything that doesn’t match the configuration we’re installing now.
Once it finishes up, everything should be installed! Not everything will be started yet, however. Running this next command will turn everything on and make sure everything starts automatically after a reboot:
ansible-playbook -i inventory/hosts setup.yml --tags=start
And that’s it! For federation to work however, there is one final step.
We’ve created a homeserver at matrix.your-domain.com, but you want your username to just have your-domain.com at the end. To do this, we need to serve two delegation files on your main domain via HTTP. There are two ways to do this:
- Point your main domain name to the Matrix server we just created, or
- Create these files on your existing webserver.
Option 1: Dedicating your entire domain to Matrix
If you aren’t going to use your domain name for a website or anything other than Matrix, this is the simplest option: Just point your root domain name to the Matrix homeserver as well, and have the webserver we created with Ansible serve the delegation files.
First, edit your DNS configuration and add an
A record to your base domain pointing to the IP address of your Matrix server.
Next, we’ll make one simple modification to the configuration files we created earlier. Edit
inventory/host_vars/matrix.<your_domain>/vars.yml and add the following line to the end of the file:
Then, re-run this command to add this new configuration to your homeserver:
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
Option 2: Add two files to your existing webserver
Maybe you’re already using your domain name for something else, like a website or blog. You’ll just have to create two files on whatever server hosts your existing site.
Creating a User
The last step in this getting started guide is creating your user account. You can run the following command to create a user, just fill in everything between
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user
Alternatively, you can connect to your homeserver via SSH and run:
/usr/local/bin/matrix-synapse-register-user <your-username> <your-password>
There’s lots of configuration changes that will let you do things like share a registration page with other people, or launch an Admin Web GUI for managing your server, but this should get us started as a single-user instance for now.
And that’s it!
Once you have Matrix installed and the delegation files setup so that other homeservers can federate with yours, you should be all set!
matrix-docker-ansible-deploy project on GitHub has an extensive collection of documentation if you’re looking for additional features, or for upgrading your services as new versions are released.
If installing and maintaining a Matrix homeserver is a bit over your head, but you still want to take control of your instant messaging platform, NABLA HOST has a range of affordable Synapse homeserver hosting options starting at $10/month, as well as Matrix installation and maintenance services where we get everything set up on the server of your choice, you could even run a homeserver from your own home! We specialize in services for individuals and small businesses, but we can work with groups of any size to help find the right Matrix solution for your needs.