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 Element 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:

{
  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";
        };

        # The service uses SQLite by default, but it's also possible to use PostgreSQL instead:
        #database = "postgresql:///mautrix-telegram?host=/run/postgresql";
      };
      bridge = {
        relaybot.authless_portals = false;
        permissions = {
          "@someadmin:domain.tld" = "admin";
        };

	# Animated stickers conversion requires additional packages in the service's path.
	# If this isn't a fresh installation, clearing the bridge's uploaded
	# file cache might be necessary (make a database backup first!):
	# `delete from telegram_file where
	#    mime_type in ('application/gzip', 'application/octet-stream')`
	animated_sticker = {
          target = "gif";
          args = {
            width = 256;
            height = 256;
            fps = 30;               # only for webm
            background = "020202";  # only for gif, transparency not supported
          };
        };
      };
    };
  };

  systemd.services.mautrix-telegram.path = with pkgs; [
    lottieconverter  # for animated stickers conversion, unfree package
    ffmpeg           # if converting animated stickers to webm (very slow!)
  ];

}

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:

{
  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";
      };

      # The service uses SQLite by default, but it's also possible to use PostgreSQL instead:
      #database = {
      #  filename = ""; # empty value to disable sqlite
      #  connString = "socket:/run/postgresql?db=matrix-appservice-discord";
      #};
    };
  };
}

See also

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