NixOS Wiki

Matrix: Difference between revisions

← Older edit
VisualWikitext
Dander (talk | contribs)
35 edits
rework the desktop clients section
m livekit: simplify key creation unit with ConditionPathExists
 
(8 intermediate revisions by 5 users not shown)
Line 3: Line 3:
This article extends the documentation in [https://nixos.org/manual/nixos/stable/#module-services-matrix NixOS manual].
This article extends the documentation in [https://nixos.org/manual/nixos/stable/#module-services-matrix NixOS manual].


== NixOS Matrix channels ==
== Joining the community on Matrix ==


https://matrix.to/#/#community:nixos.org
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.


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
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
Line 13: Line 13:
=== Desktop clients ===
=== Desktop clients ===


These clients are know to work: <code>element-desktop</code> [https://element.io/] and <code>fractal</code> [https://gitlab.gnome.org/World/fractal]
These clients are known to work: <code>element-desktop</code> [https://element.io/] and <code>fractal</code> [https://gitlab.gnome.org/World/fractal]


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 [https://soatok.blog/2024/08/14/security-issues-in-matrixs-olm-library/ various security vulnerabilities].
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]


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].  
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 ===
=== 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">
==== element-web ====
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].<syntaxhighlight lang="nixos">
{
{
   services.nginx.enable = true;
   services.nginx.enable = true;
Line 59: Line 57:
</syntaxhighlight>
</syntaxhighlight>


== Servers ==
== Homeservers ==
 
=== Homeservers ===


==== Conduit ====
=== Conduit ===
<syntaxhighlight lang="nixos">
<syntaxhighlight lang="nixos">
{
{
Line 72: Line 68:
     settings.global = {
     settings.global = {
       # allow_registration = true;
       # allow_registration = true;
      # You will need this token when creating your first account.
      # registration_token = "A S3CR3T TOKEN";
       # server_name = yourDomainName;
       # server_name = yourDomainName;
       # port = yourPort;
       # port = yourPort;
       address = "::1";
       address = "::1";
       database_backend = "rocksdb";
       database_backend = "rocksdb";
       # See https://www.metered.ca/tools/openrelay
     
       turn_uris = [
       # See https://docs.conduit.rs/turn.html, and https://github.com/element-hq/synapse/blob/develop/docs/turn-howto.md for more details
        "turn:staticauth.openrelay.metered.ca:80?transport=udp"
       # turn_uris = [
        "turn:staticauth.openrelay.metered.ca:80?transport=tcp"
      #  "turn:your.turn.url?transport=udp"
       ];
      #  "turn:your.turn.url?transport=tcp"
       turn_secret = "openrelayprojectsecret";
       # ];
       # turn_secret = "your secret";
     };
     };
   };
   };
Line 87: Line 86:
</syntaxhighlight>
</syntaxhighlight>


==== Synapse ====
=== 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.
[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.


===== 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/custom/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].


Line 167: 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;
    settings.room.auto_create = false;
    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 = ''
        echo "Key missing, generating key"
        echo "lk-jwt-service: $(livekit-server generate-keys | tail -1 | awk '{print $3}')" > "${keyFile}"
    '';
    serviceConfig.Type = "oneshot";
    unitConfig.ConditionPathExists = "!${keyFile}";
  };
  # 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 256: Line 323:
</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 322: Line 385:
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
Retrieved from "https://wiki.nixos.org/wiki/Matrix"