Matrix is a modern, decentralized, federated real-time communication protocol and open standard. It has a thriving ecosystem of servers, clients, and applications. Synapse is the reference server and Element is the reference client for the web, desktop and mobile platforms.

Matrix protocol logo

This is something that I have been interested in using and self-hosting for a few years now. I have had an account on the main instance for a while now and wanted to switch to a self-hosted instance.

Since I have been using docker, docker-compose, and Ansible to deploy and run a wide range of self-hosted applications for my personal use, the spantaleev/matrix-docker-ansible-deploy was my choice for setting up my instance. I chose to use Synapse over Dendrite, the second-generation server because though it is lightweight, it is not feature-complete. All the other third-party implementations have a lot of catching up to do as well, at the time of writing this post.

I learned a bit of Terraform in my previous job, but never had a chance to learn it properly or build something from scratch using it. So armed with my little knowledge of Terraform, I created a small Terraform project to automate setting up a new Matrix instance. It provisions the DNS records needed for Matrix on Namecheap — my domain registrar and DNS host, provisions an appropriately sized Hetzner cloud instance with a floating IP address, and runs the deployment playbook in the matrix-docker-ansible-deploy repository with the provided Ansible variables file. I used the hcloud and the namecheap Terraform providers to do this.

With this, I was able to provision and set up my Matrix instance in under 10 minutes by just running

$ terraform plan -out=matrix-plan
$ terraform apply "matrix-plan"

I have released the source code for this project here on GitLab under the GNU Affero General Public License v3.0 (AGPLv3) or later. Since this project contains the matrix-docker-ansible-deploy repository as a git submodule, running git submodule update --init should automatically pull in a known good commit of that repository to use for the deployment. The README file has the instructions for using the project to set Matrix instances from scratch.

I hope it is useful for those who are looking to set up a new Matrix instance.

I have a WireGuard server running on a Raspberry Pi 4B at my home, exposed to the internet via a static IP address and port forwarding. I set it up using the WireGuard docker container, which is straightforward to use and manage.

As I am in a different city now, I had been postponing the updates to the docker container since it is risky to do so remotely. Any issue in the upgrade process could lock me out of my home network till I am physically present in my home.

As I hate deferring updates, I decided to apply the update remotely. To prepare for that, I logged into the Raspberry Pi via the WireGuard VPN and set up a remote forwarding SSH tunnel on a server of mine hosted in the cloud, using a command like,

$ ssh -R 2222: username@remote.server.address -N

This command forwards the 2222 port on the remote server to on the Raspberry Pi, thereby allowing access to it from the remote server. The -N flag prevents the execution of any remote command (like say, starting the user’s shell) and is useful for just forwarding ports.

Then I logged in directly to that server and logged in to the Raspberry Pi using the forwarded port on that server. Now I could destroy and re-create the WireGuard container without the fear of being locked out since I was connected to the device using SSH and not the WireGuard VPN itself. So, I ran the following command.

$ ssh -p2222 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o CheckHostIP=no username@

The UserKnownHostsfile=/dev/null option prevents the saving of the remote host’s SSH key in the ~/.ssh/known_hosts file, the StrictHostKeyChecking=no option prevents the checking of the remote host key, and the CheckHostIP=no option prevents the checking of the remote host’s IP address. These options disable a lot of important security measures that SSH provides by default ⚠️. But since we are connecting to a known host through a forwarded host, and don’t want to save any local data about it, these options are fine to use.

This command my remote SSH session, and I was worried that I had missed something important and was locked out. So, I disconnected the SSH session using the escape sequence (<enter>~.) and reconnected to my cloud server and then to the Raspberry Pi. It worked and I heaved a sigh of relief and was glad to have pulled this off without any issues. I verified that updated WireGuard container was running without any issues and that I was able to connect to the VPN. 😌