Matrix is a new, open-source protocol for decentralized chat networks. Being a protocol, meaning that it requires a server (we will use Synapse) and a client (we will use Element) to function the way you expect chat programs, like Slack, to work.
Matrix is designed with decentralization in mind, meaning it is designed to function as a network of servers, of which your installation is just one node. This is great for a lot of purposes but can be confusing for people who are less tech-savvy, and it’s not designed with the same ideas in mind as corporate-focused Slack replacements like Rocket Chat and Mattermost. Matrix is an excellent option for activists and non-profit organizations that want a secure, collaborative, easy-to-use alternative to Slack.
This guide will explain everything you need to know to get Matrix installed and configured with Cloudron. It’s going to heavily mirror the official Cloudron documentation, so if something seems wrong or out of date please compare with their docs or head to the Cloudron forums. To get started, install Matrix Synapse from the Cloudron app store. I strongly recommend using matrix.yourdomain.com as the location. This isn’t required but it makes later steps easier and many guides online (including this one) will assume this.
Let’s quickly detour into a quick explanation of why this is important, and go into a little more detail on how Matrix works.
Meeting Morpheus (What is Matrix?)
As mentioned earlier, Matrix is a protocol. A protocol is not a computer program; it’s like a written specification that tells computers how to talk to each other. To turn a protocol into something we can use to chat with, we need a server and a client.
The server is the main component of what you will install with this guide; it allows Matrix clients (for example, their Android app) to talk to the server. There are multiple servers and clients for the Matrix protocol. We’re going to install Synapse, which is the most popular server program that implements the Matrix protocol. (Matrix calls the server a homeserver and we will use that word going forward to refer to what we will install)
A server/client model may sound familiar – nearly all apps use this model to communicate. But Matrix adds an additional feature uncommon for chat apps like Slack or Hangouts – servers can also talk to other servers (imagine email, but better). This means you can message someone on a totally different homeserver than you seamlessly as long as your servers are connected (in Matrix terms – federated).
Let’s look at a quick example with two DSA chapters, Springfield and Riverdale. The Springfield and Riverdale DSA chapters each have their own Synapse installation, and each member can only talk with other members of their own chapter. One day, they decide to federate their servers – this allows both members to join a Room and chat with each other. Rooms (called Channels or Groups by some other chat apps) allow members from both chapters to chat without either chapter giving up control or security access to the other. User in the Springfield server can chat with Riverdale users only in shared Rooms. The admins of each server can only see messages the other server’s users send in shared Rooms as well.
Your name in Matrix reflects this two-tier nature – your username will reflect your homeserver. For example, if mine is @joe:socialism.tools and I chat with @joe:neoliberalism.fail in a shared room, we can still tell each other apart.
Let’s compare this with Slack. Slack is the one major chat app with federation, but it’s limited to paying customers. What activist orgs will do in this case is someone will spin up a new Slack instance, and then invite members from any related Slacks to make a new account and join. This is cumbersome and obscures the source of the members (Rooms for introductions are used to help people identify where they came from, but again, this is cumbersome). This process needs to be repeated for each new working group, action, etc that needs to be spun up. As some of you may know, that’s a lot of Slack workspaces! Matrix makes it easier to collaborate securely with many different organizations / Matrix servers.
Enter the Matrix (Installation)
Ensure you’ve installed Synapse from the Cloudron app store at matrix.yourdomain.com. You now have a homeserver! But we need to perform a few additional steps. To make your homeserver available for federation, you’ll need to configure a few other things. We’ll set up the well-known URI first. This is a special URL that makes it easier for other computers where to find a program (in this case, your Matrix server). Click the gear (config) icon that appears when you hover over the Matrix app in Cloudron, then Console, then Terminal. Copy the following two lines of script into Notepad or another app where you can edit them.
mkdir -p /home/yellowtent/boxdata/well-known/example.com/matrix echo '{ "m.server": "matrix-homeserver.example.com:443" }' > /home/yellowtent/boxdata/well-known/example.com/matrix/server
Replace example.com with your regular domain name, for example springfield-dsa.org. Put your Matrix server location in the matrix-homeserver.example.com seciton. Then, copy it and paste it into the web terminal and press enter. Keep the Terminal tab open and go back to your Cloudron tab. Click the Location menu item and click Save without hitting anything else. Wait until it’s done processing, then go back to your Terminal tab and wait a few moments.
Type curl and then paste your well-known URL and press enter. Here’s what happens when I print mine (I pressed enter after the word “server” and the line with curly braces was returned)
You should get something very similar to the above. If not, check the Cloudron docs to see if you missed a step. You should also type your domain name (without matrix-) intro the Federation Tester to confirm everything is working as expected. There’s just one step left – make yourself an admin!
Again, copy the following line and edit @user:example.com to match your information (your Matrix username will match your Cloudron username. If you don’t know what it is, go back to the Cloudron dashboard look in the top right corner):
PGPASSWORD=${CLOUDRON_POSTGRESQL_PASSWORD} psql -h ${CLOUDRON_POSTGRESQL_HOST} -p ${CLOUDRON_POSTGRESQL_PORT} -U ${CLOUDRON_POSTGRESQL_USERNAME} -d ${CLOUDRON_POSTGRESQL_DATABASE} -c "UPDATE users SET admin=1 WHERE name='@user:example.com'" UPDATE 1
Congratulations, Neo – you are now fully plugged into the Matrix! You can now connect with a Matrix client – Element, for example. Test that you can connect, and then come back for some additional configuration features you can use.
Change your Matix (Configuration)
Matrix has a ton of configuration options and plugins, but we’ll go over just a few important tweaks here you may need. First, if a user types your Matrix URL into their browser, they get the default Matrix page:
Boring! Let’s add some pop. I copied the file that’s there (you can open it via the Terminal and select all > copy) and then added my own little touches:
While you’ll need to know HTML to create a fancy landing page, you can work with the building blocks that are there to add links (like element.yourdomain.com to join the web server).
The other file you can edit to make Synapse fit your needs in the config file at /app/data/configs/homeserver.yaml. Type nano and then that path to edit the file when you have the Terminal open. The config file tries to describe what it does inside of it for most functions. A pound/hash/octothorpe (#) at the start of a line means the line is commented out and will be ignored by Synapse.
For example, if you run on a very resource-constrained server, you may want to look at changing the limit_remote_rooms setting to block users from joining very large remote rooms. Please be careful when editing the config file – the spacing of lines matters, and saving the config file when it isn’t formatted correctly will likely cause issues with your server. You will also need to reboot the Synapse app after any settings changes.