NixOS Wiki

Matrix: Difference between revisions

← Older edit
VisualWikitext
Luflosi (talk | contribs)
3 edits
m Simplify code slightly
Dander (talk | contribs)
35 edits
m don't link to personal blogs (see MoS)
 
(15 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.


=== NixOS Matrix accounts for GitHub org members ===
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
 
https://discourse.nixos.org/t/matrix-account-hosting-for-nix-os-hackers/14036


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


A few Matrix desktop clients are packaged for NixOS.
These clients are know 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 ====
==== 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].
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 =====
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].


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
Line 119: 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 127: Line 165:
</syntaxhighlight>
</syntaxhighlight>


===== Synapse with Workers =====
==== 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 216: Line 252:
</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].
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 282: Line 315:
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"