Matrix

Matrix defines a set of open APIs for decentralised communication, suitable for securely publishing, persisting and subscribing to data over a global open federation of servers with no single point of control. Uses include Instant Messaging (IM), Voice over IP (VoIP) signalling, Internet of Things (IoT) communication, and bridging together existing communication silos - providing the basis of a new open real-time communication ecosystem.

Clients

Desktop clients

A few Matrix desktop clients are packaged for NixOS.

• Element (formerly Riot, based on Electron)
• Fractal
• gomuks
• matrique
• nheko
• Quaternion

A Pidgin / libpurple plugin is also available.

Web clients

There is also a web version of Riot which can be served using a web server. See the NixOS manual entry.

Servers

Homeservers

Synapse

Currently, only the reference Matrix homeserver Synapse is packaged for NixOS. It has an associated module exposing the services.matrix-synapse.* options. See the NixOS manual entry for a complete configuration example.

Coturn with Synapse

For WebRTC calls to work when both callers are behind a NAT, you need to provide a turn server for clients to use. Here is an example configuration, inspired from this configuration file.

{config, pkgs, lib, ...}: {
  # enable coturn
  services.coturn = rec {
    enable = true;
    no-cli = true;
    no-tcp-relay = true;
    min-port = 49000;
    max-port = 50000;
    use-auth-secret = true;
    static-auth-secret = "will be world readable for local users :(";
    realm = "turn.example.com";
    cert = "${config.security.acme.certs.${realm}.directory}/full.pem";
    pkey = "${config.security.acme.certs.${realm}.directory}/key.pem";
    extraConfig = ''
      # for debugging
      verbose
      # ban private IP ranges
      denied-peer-ip=10.0.0.0-10.255.255.255
      denied-peer-ip=127.0.0.0-127.255.255.255
      denied-peer-ip=172.16.0.0-172.31.255.255
      denied-peer-ip=192.88.99.0-192.88.99.255
      denied-peer-ip=192.168.0.0-192.168.255.255
      denied-peer-ip=244.0.0.0-224.255.255.255
      denied-peer-ip=255.255.255.255-255.255.255.255
    '';
  };
  # open the firewall
  networking.firewall = {
    interfaces.enp2s0 = let
      range = with config.services.coturn; [ {
      from = min-port;
      to = max-port;
    } ];
    in
    {
      allowedUDPPortRanges = range;
      allowedUDPPorts = [ 3478 ];
      allowedTCPPortRanges = range;
      allowedTCPPorts = [ 3478 ];
    };
  };
  # get a certificate
  security.acme.certs.${config.services.coturn.realm} = {
    /* insert here the right configuration to obtain a certificate */
    postRun = "systemctl restart coturn.service";
    user = "turnserver";
    group = "turnserver";
  };
  # configure synapse to point users to coturn
  services.matrix-synapse = with config.services.coturn; {
    turn_uris = ["turn:${realm}:3478?transport=udp" "turn:${realm}:3478?transport=tcp"];
    turn_shared_secret = static-auth-secret;
    turn_user_lifetime = "1h";
  };
}

Application services (a.k.a. bridges)

mautrix-telegram

Full configuration reference: https://github.com/tulir/mautrix-telegram/blob/master/mautrix_telegram/example-config.yaml

Example NixOS config:

{
  # The module will be available in NixOS 20.09. For now, we need to import it from the unstable channel.
  imports = [
    <nixos-unstable/nixos/modules/services/misc/mautrix-telegram.nix>
  ];

  services.matrix-synapse = {
    enable = true;
    app_service_config_files = [
      # The registration file is automatically generated after starting the appservice for the first time.
      # cp /var/lib/mautrix-telegram/telegram-registration.yaml /var/lib/matrix-synapse/
      # chown matrix-synapse:matrix-synapse /var/lib/matrix-synapse/telegram-registration.yaml
      "/var/lib/matrix-synapse/telegram-registration.yaml"
    ];
    # ...
  };

  services.mautrix-telegram = {
    enable = true;
    environmentFile = /etc/secrets/mautrix-telegram.env; # file containing the appservice and telegram tokens
    # The appservice is pre-configured to use SQLite by default. It's also possible to use PostgreSQL.
    settings = {
      homeserver = {
        address = "http://localhost:8008";
        domain = "domain.tld";
      };
      appservice = {
        provisioning.enabled = false;
        id = "telegram";
        public = {
          enabled = true;
          prefix = "/public";
          external = "http://domain.tld:8080/public";
        };
      };
      bridge = {
        relaybot.authless_portals = false;
        permissions = {
          "@someadmin:domain.tld" = "admin";
        };
      };
    };
  };
}

mautrix-whatsapp

Packaged as mautrix-whatsapp. Module still a WIP.

matrix-appservice-irc

Package and module still a WIP.

matrix-appservice-discord

Full configuration reference: https://github.com/Half-Shot/matrix-appservice-discord/blob/master/config/config.sample.yaml

Example NixOS config:

{
  # The module will be available in NixOS 20.09. For now, we need to import it from the unstable channel.
  imports = [
    <nixos-unstable/nixos/modules/services/misc/matrix-appservice-discord.nix>
  ];

  # The package will be available in NixOS 20.09. For now, we need to import it from the unstable channel.
  nixpkgs.overlays = [(self: super: {
    inherit (import <nixos-unstable> { }) matrix-appservice-discord;
  })];

  services.matrix-synapse = {
    enable = true;
    app_service_config_files = [
      # The registration file is automatically generated after starting the appservice for the first time.
      # cp /var/lib/matrix-appservice-discord/discord-registration.yaml /var/lib/matrix-synapse/
      # chown matrix-synapse:matrix-synapse /var/lib/matrix-synapse/discord-registration.yaml
      "/var/lib/matrix-synapse/discord-registration.yaml"
    ];
    # ...
  };

  services.matrix-appservice-discord = {
    enable = true;
    environmentFile = /etc/keyring/matrix-appservice-discord/tokens.env;
    # The appservice is pre-configured to use SQLite by default. It's also possible to use PostgreSQL.
    settings = {
      bridge = {
        domain = "test.tld";
        homeserverUrl = "https://public.endpoint.test.tld";
      };
    };
  };
}

See also

• The chapter about Matrix in the NixOS manual
• The Nix Matrix Subsystem chat room, on Matrix