Self-hosting Matrix with an IRC bridge on NixOS

conduit-heisenberg-caddy-nixos.md

Self-hosting Matrix with an IRC bridge on NixOS

Introduction

There are two main free and open-source technologies today for real-time internet chat: IRC and Matrix. The former is old and stable, while the latter is newer and still developing. Most communities I want to keep in touch with are on Matrix, like Nix, while a few are on IRC, like Guix. One advantage of Matrix is that it allows for bridging to and from other platforms, like IRC.

But not all is well with the world. The most popular Matrix server, Synapse, is notoriously resource-hungry. The public bridges between the primary public IRC and Matrix providers were closed for lack of agreement on how to handle certain problems they caused due to their heavy use. And so I decided to set up my own Matrix server with the more efficient Conduit server and my own IRC bridge using Heisenbridge, both running on a low-end NixOS server. I also use the Caddy webserver as a reverse proxy in this setup for managing transport layer security.

This project had three main goals:

1. Improve my own digital autonomy by self-hosting my own services
2. Increase the federation of these networks by running my own node
3. Avoid running both IRC and Matrix clients, having multiple accounts, etc.

NixOS, Conduit, Heisenbrdige, and Caddy all have their own technical merits, but most importantly on the human level they allow me to manage complexity and allow me to successfully run my own communications platform.

Setup Matrix

To replicate my setup, you will need a few things:

1. Register a domain name
2. Get a VPS (Gandi offers NixOS out-of-the-box, and DNS too)
3. Copy the contents of my configuration.nix file below to your VPS.
4. Modify the variables defined in the let block to match your domain, etc.
5. Run $ nixos-rebuild switch
6. Register a Matrix user with your new Conduit server (this will be the administrator)
7. Disable open registration in the configuration.nix (see the comment)
8. Run $ nixos-rebuild switch

Now your Matrix server should be fully operational. You should automatically be invited to an admin chat room with a @conduit:$YOUR-DOMAIN bot which will allow you to further create users, rooms, etc. For more information, see the Conduit manual.

Setup Heisenbridge

Heisenbridge is setup in the configuration.nix file, but it is disabled. Before we enable it, we need to generate a config.yml file that specifies how Heisenbridge can interoperate with Conduit. To do this requires a few steps:

1. Generate the config file:

$ nix-shell --packages heisenbridge \
            --command "heisenbridge --generate-compat --config config.yml"

You can look at this file and see that it sets up access tokens, etc.

2. Copy the contents of that file to your clipboard.
3. Put the file in the directory specified in configuration.nix:

$ mkdir -p /var/lib/heisenbridge
$ mv config.yml /var/lib/heisenbridge/config.yml

4. Go to your admin chatroom and paste the config in a message to the conduit bot like this to register the bridge:

@conduit:$YOUR-DOMAIN register-appservice ```
$CONTENTS_OF_YOUR_CONFIG.YML
```

If this works, the conduit bot should respond with something like Appservices (1): ....

5. Edit your configuration.nix and enable Heisenbridge by changing config.heisenbridge.enable = false; to ... = true;.
6. Run $ nixos-rebuild switch

Heisenbridge should now be up and running, with a @heisenbridge:$YOUR-DOMAIN bot created that you can message to join various IRC servers, register your Nick, etc. A simple help message to this bot will list out all the relevant commands. In my experience, it works pretty well: it feels like your Matrix client is directly connected to IRC.

Conclusion

This combination of technologies allows me to keep in touch with dozens of communities with minimal resource usage: currently, I am running it all on a 1 CPU, 1 GB of RAM virtual machine (although I did do the initial install and testing on a 2 CPU, 4 GB of RAM VM). By owning my own Matrix server, I can maintain whatever logs I wish, federate with whomever I like, and bridge to wherever I want. This seems a much more sustainable and maintainable model than everyone joining one big public instance like matrix.org. If I wanted, I could add a few friends to my server to reduce costs and improve resource efficency further, as the VM still has plenty of headroom.

configuration.nix

{ pkgs, ... }:

let # Change these values
  domain_name = "example.com";
  user_name = "alice";
  secure_token = "opensesame";
in

{
  config = {
    networking = {
      firewall = {
        enable = true;
        allowedTCPPorts = [ 22 80 443 8448 ];
        allowedUDPPorts = [ 53 ];
      };
    };
    services = {
      caddy = {
        enable = true;
        virtualHosts = {
          "${domain_name}" = {
            extraConfig = ''
            reverse_proxy /_matrix/* 127.0.0.1:6167
            '';
          };
        };
      };
      matrix-conduit = {
        enable = true;
        settings.global = {
          address = "127.0.0.1"; 
          # Change this to `false` after the first user (admin) is registered,
          # and then run `$ nixos-rebuild switch`.
          allow_registration = true;
          registration_token = "${secure_token}";
          database_backend = "rocksdb";
          port = 6167;
          server_name = "${domain_name}";
        };
      };
      heisenbridge = {
        enable = true;
        extraArgs = ["--config" "/var/lib/heisenbridge/config.yml"];
        debug = true;
        homeserver = "https://${domain_name}";
        owner = "@${user_name}:${domain_name}";
      };
    };
  };
}