NixOS Wiki

Matrix: Difference between revisions

← Older edit
VisualWikitext
imported>Jhvst
clients: add iamb
add instructions to setup livekit for use withe element-call or Element X
 
(21 intermediate revisions by 8 users not shown)
Line 1: Line 1:
[https://matrix.org 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.
[https://matrix.org 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.


== NixOS Matrix channels ==
This article extends the documentation in [https://nixos.org/manual/nixos/stable/#module-services-matrix NixOS manual].


https://matrix.to/#/#community:nixos.org
== Joining the community on Matrix ==


=== NixOS Matrix accounts for GitHub org members ===
You can read more about the different rooms on [[MatrixRooms]] and join them either from https://matrix.to/#/#community:nixos.org or directly from your client.


https://discourse.nixos.org/t/matrix-account-hosting-for-nix-os-hackers/14036
An unofficial service provides Matrix accounts for members of the NixOS organization on GitHub: https://discourse.nixos.org/t/matrix-account-hosting-for-nix-os-hackers/14036


== Clients ==
== Clients ==
Line 13: Line 13:
=== Desktop clients ===
=== Desktop clients ===


A few Matrix desktop clients are packaged for NixOS.
These clients are known to work: <code>element-desktop</code> [https://element.io/] and <code>fractal</code> [https://gitlab.gnome.org/World/fractal]


* [https://search.nixos.org/packages?query=element-desktop Element (formerly Riot, based on Electron)]
Most of the other clients packaged in Nixpkgs, such as <code>matrix-commander</code>, <code>neochat</code>, <code>nheko</code>, rely on the '''insecure''' and '''deprecated''' <code>olm</code> library susceptible to various security vulnerabilities.[https://nvd.nist.gov/vuln/detail/CVE-2024-45191][https://nvd.nist.gov/vuln/detail/CVE-2024-45193][https://nvd.nist.gov/vuln/detail/CVE-2024-45192]
* [https://search.nixos.org/packages?query=fractal Fractal]
* [https://search.nixos.org/packages?query=gomuks gomuks]
* [https://search.nixos.org/packages?query=neochat neochat]
* [https://search.nixos.org/packages?query=mirage-im Mirage]
* [https://search.nixos.org/packages?query=nheko nheko]
* [https://search.nixos.org/packages?query=quaternion Quaternion]
* [https://search.nixos.org/packages?query=iamb iamb]


A [https://search.nixos.org/packages?query=purple-matrix Pidgin / libpurple plugin] is also available.
If this isn't a problem for you, you can install them as usual, and upon evaluation, Nix will helpfully guide you on how to [https://nixos.org/manual/nixpkgs/stable/#sec-allow-insecure install insecure packages].
=== Web clients ===
There is a web version of the client [https://element.io/ Element], <code>element-web</code> on Nixpkgs, which you can use as a regular web application.  See [https://nixos.org/nixos/manual/index.html#module-services-matrix-element-web the NixOS manual entry].<syntaxhighlight lang="nixos">
{
  services.nginx.enable = true;


==== Element ====
  # See https://nixos.org/manual/nixos/stable/index.html#module-services-matrix-element-web
  services.nginx.virtualHosts."localhost" = {
    listen = [{
      addr = "[::1]";
      port = yourPort;
    }];
    root = pkgs.element-web.override {
      # See https://github.com/element-hq/element-web/blob/develop/config.sample.json
      conf = {
        default_theme = "dark";
      };
    };
  };
}
</syntaxhighlight>Alternatively, you can write a script to start the web client on demand.<syntaxhighlight lang="nix">
let
  # port = yourPort;
  web-dir = pkgs.element-web.override {
    conf = {
      default_theme = "dark";
      show_labs_settings = true;
    };
  };
  element-web = pkgs.writeScriptBin "element-web" ''
    #!${pkgs.bash}/bin/bash
    set -e
    ${pkgs.python3}/bin/python3 -m http.server ${port} -b ::1 -d ${web-dir}
  '';
in
{
  home.sessionPath = [ "${element-web}/bin" ];
}
</syntaxhighlight>


The [https://github.com/vector-im/element-web/blob/develop/config.sample.json config.json] file used by Element can be configured as such:
== Homeservers ==


<syntaxhighlight lang="nix">
=== Conduit ===
nixpkgs.config.element-web.conf = {
<syntaxhighlight lang="nixos">
  show_labs_settings = true;
{
  default_theme = "dark";
  # See https://search.nixos.org/options?channel=unstable&query=services.matrix-conduit.
};
  # and https://docs.conduit.rs/configuration.html
  services.matrix-conduit = {
    enable = true;
    settings.global = {
      # allow_registration = true;
      # You will need this token when creating your first account.
      # registration_token = "A S3CR3T TOKEN";
      # server_name = yourDomainName;
      # port = yourPort;
      address = "::1";
      database_backend = "rocksdb";
     
      # See https://docs.conduit.rs/turn.html, and https://github.com/element-hq/synapse/blob/develop/docs/turn-howto.md for more details
      # turn_uris = [
      #  "turn:your.turn.url?transport=udp"
      #  "turn:your.turn.url?transport=tcp"
      # ];
      # turn_secret = "your secret";
    };
  };
}
</syntaxhighlight>
</syntaxhighlight>


=== Web clients ===
=== Synapse ===
 
[https://element-hq.github.io/synapse/latest/welcome_and_overview.html Synapse] has an associated module exposing the [https://search.nixos.org/options?query=services.matrix-synapse services.matrix-synapse.* options]. See [https://nixos.org/nixos/manual/index.html#module-services-matrix-synapse the NixOS manual entry] for a complete configuration example.
There is also a web version of [https://search.nixos.org/packages?query=element-web Element] which can be served using a web server. See [https://nixos.org/nixos/manual/index.html#module-services-matrix-element-web the NixOS manual entry].
 
== Servers ==
 
=== Homeservers ===
 
==== Synapse ====
 
Currently, only the reference Matrix homeserver [https://matrix.org/docs/projects/server/synapse Synapse] is  [https://search.nixos.org/packages?query=matrix-synapse packaged] for NixOS. It has an associated module exposing the [https://search.nixos.org/options?query=services.matrix-synapse services.matrix-synapse.* options]. See [https://nixos.org/nixos/manual/index.html#module-services-matrix-synapse the NixOS manual entry] for a complete configuration example.


===== Coturn with Synapse =====
==== 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 [https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/matrix-coturn/templates/turnserver.conf.j2 this configuration file].
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 [https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/custom/matrix-coturn/templates/turnserver.conf.j2 this configuration file].


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
Line 98: Line 138:
   networking.firewall = {
   networking.firewall = {
     interfaces.enp2s0 = let
     interfaces.enp2s0 = let
       range = with config.services.coturn; [ {
       range = with config.services.coturn; lib.singleton {
      from = min-port;
        from = min-port;
      to = max-port;
        to = max-port;
    } ];
      };
     in
     in
     {
     {
Line 117: Line 157:
   };
   };
   # configure synapse to point users to coturn
   # configure synapse to point users to coturn
   services.matrix-synapse = with config.services.coturn; {
   services.matrix-synapse.settings = with config.services.coturn; {
     turn_uris = ["turn:${realm}:3478?transport=udp" "turn:${realm}:3478?transport=tcp"];
     turn_uris = ["turn:${realm}:3478?transport=udp" "turn:${realm}:3478?transport=tcp"];
     turn_shared_secret = static-auth-secret;
     turn_shared_secret = static-auth-secret;
Line 125: Line 165:
</syntaxhighlight>
</syntaxhighlight>


===== Synapse with Workers =====
==== Livekit ====
In order to set up element call or for calls to work in Element X it is necessary to set up and announce livekit. To set up livekit for matrix in nixos use<syntaxhighlight lang="nix" line="1">
{ config, lib, pkgs, ... }: let
  keyFile = "/run/livekit.key";
in {
  services.livekit = {
    enable = true;
    openFirewall = true;
    inherit keyFile;
  };
  services.lk-jwt-service = {
    enable = true;
    # can be on the same virtualHost as synapse
    livekitUrl = "wss://domain.tld/livekit/sfu";
    inherit keyFile;
  };
  # generate the key when needed
  systemd.services.livekit-key = {
    before = [ "lk-jwt-service.service" "livekit.service" ];
    wantedBy = [ "multi-user.target" ];
    path = with pkgs; [ livekit coreutils gawk ];
    script = ''
      if [ -f ${keyFile} ]; then
        echo "Key exists"
      else
        echo "Key missing, generating key"
        echo "lk-jwt-service: $(livekit-server generate-keys | tail -1 | awk '{print $3}')" > "${keyFile}"
      fi
    '';
    serviceConfig.Type = "oneshot";
  };
  # restrict access to livekit room creation to a homeserver
  systemd.services.lk-jwt-service.environment.LIVEKIT_FULL_ACCESS_HOMESERVERS = "domain.tld";
  services.nginx.virtualHosts."domain.tld".locations = {
    "^~ /livekit/jwt/" = {
      priority = 400;
      proxyPass = "http://[::1]:${toString config.services.lk-jwt-service.port}/";
    };
    "^~ /livekit/sfu/" = {
      extraConfig = ''
        proxy_send_timeout 120;
        proxy_read_timeout 120;
        proxy_buffering off;
 
        proxy_set_header Accept-Encoding gzip;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
      '';
      priority = 400;
      proxyPass = "http://[::1]:${toString config.services.livekit.settings.port}/";
      proxyWebsockets = true;
    };
  };
}
</syntaxhighlight>Furthermore, it is necessary to announce the service with a <code>domain.tld/.well-known/matrix/client</code> which needs to be served as <code>Content-Type application/json</code> (calls in Element X might not work without the content-type) and contain<syntaxhighlight lang="json">
{
  "m.homeserver": {
    "base_url": "https://domain.tld"
  },
  "m.identity_server": {
    "base_url": "https://vector.im"
  },
  "org.matrix.msc3575.proxy": {
    "url": "https://domain.tld"
  },
  "org.matrix.msc4143.rtc_foci": [
    {
      "type": "livekit",    "livekit_service_url": "https://domain.tld/livekit/jwt"
    }
  ]
}
</syntaxhighlight>
 
==== Synapse with Workers ====
There's an external module to automatically set up synapse and configure nginx with workers:
There's an external module to automatically set up synapse and configure nginx with workers:
https://github.com/dali99/nixos-matrix-modules
https://github.com/dali99/nixos-matrix-modules


=== Application services (a.k.a. bridges) ===
== Application services (a.k.a. bridges) ==
 
Bridges allow you to connect Matrix to a third-party platform (like Discord, Telegram, etc.), and interact seamlessly. See [https://matrix.org/ecosystem/bridges/ here] for a list of currently supported bridges.
Bridges allow you to connect Matrix to a third-party platform (like Discord, Telegram, etc.), and interact seamlessly. See [https://matrix.org/ecosystem/bridges/ here] for a list of currently supported bridges.


==== mautrix-telegram ====
=== mautrix-telegram ===
 
Full configuration reference:
Full configuration reference:
https://github.com/tulir/mautrix-telegram/blob/master/mautrix_telegram/example-config.yaml
https://github.com/tulir/mautrix-telegram/blob/master/mautrix_telegram/example-config.yaml
Line 214: Line 325:
</syntaxhighlight>
</syntaxhighlight>


 
=== mautrix-whatsapp ===
==== mautrix-whatsapp ====
 
Packaged as [https://search.nixos.org/packages?query=mautrix-whatsapp mautrix-whatsapp].
Packaged as [https://search.nixos.org/packages?query=mautrix-whatsapp mautrix-whatsapp].
Module implemented in this [https://github.com/NixOS/nixpkgs/pull/246842 PR].
==== matrix-appservice-irc ====


=== matrix-appservice-irc ===
NixOS-specific module options: TODO link to the search results once it's landed
NixOS-specific module options: TODO link to the search results once it's landed


Line 280: Line 387:
The appservice automatically creates a registration file under <code>/var/lib/matrix-appservice-irc/registration.yml</code> and keeps it up to date. If your homeserver is not located on the same machine and NixOS installation, you must absolutely make sure to synchronize that file over to the home server after each modification and keep both in sync.
The appservice automatically creates a registration file under <code>/var/lib/matrix-appservice-irc/registration.yml</code> and keeps it up to date. If your homeserver is not located on the same machine and NixOS installation, you must absolutely make sure to synchronize that file over to the home server after each modification and keep both in sync.


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


== See also ==
== See also ==
 
* [[Mjolnir]] - a Matrix moderation tool
* [https://nixos.org/nixos/manual/index.html#module-services-matrix The chapter about Matrix in the NixOS manual]
* [https://matrix.to/#/!vxTmkuJzhGPsMdkAOc:transformierende-gesellschaft.org?via=transformierende-gesellschaft.org The Nix Matrix Subsystem chat room, on Matrix]
* [https://matrix.to/#/!vxTmkuJzhGPsMdkAOc:transformierende-gesellschaft.org?via=transformierende-gesellschaft.org The Nix Matrix Subsystem chat room, on Matrix]


[[Category:Applications]]
[[Category:Applications]]
[[Category:Server]]
[[Category:NixOS Manual]]
Retrieved from "https://wiki.nixos.org/wiki/Matrix"