Matrix: Difference between revisions
imported>Pacien package has been renamed: riot -> element |
Phanirithvij (talk | contribs) m fix config file url |
||
(35 intermediate revisions by 20 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. | ||
This article extends the documentation in [https://nixos.org/manual/nixos/stable/#module-services-matrix NixOS manual]. | |||
== NixOS Matrix channels == | |||
https://matrix.to/#/#community:nixos.org | |||
=== NixOS Matrix accounts for GitHub org members === | |||
https://discourse.nixos.org/t/matrix-account-hosting-for-nix-os-hackers/14036 | |||
== Clients == | == Clients == | ||
Line 8: | Line 17: | ||
A few Matrix desktop clients are packaged for NixOS. | A few Matrix desktop clients are packaged for NixOS. | ||
* [https://search.nixos.org/packages | * [https://search.nixos.org/packages?query=element-desktop Element (formerly Riot, based on Electron)] | ||
* [https://search.nixos.org/packages | * [https://search.nixos.org/packages?query=fractal Fractal] | ||
* [https://search.nixos.org/packages | * [https://search.nixos.org/packages?query=gomuks gomuks] | ||
* [https://search.nixos.org/packages/?query= | * [https://search.nixos.org/packages?query=neochat neochat] | ||
* [https://search.nixos.org/packages | * [https://search.nixos.org/packages?query=mirage-im Mirage] | ||
* [https://search.nixos.org/packages | * [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 | A [https://search.nixos.org/packages?query=purple-matrix Pidgin / libpurple plugin] is also available. | ||
=== Web clients === | === Web clients === | ||
There is also a web version of [https://search.nixos.org/packages | ==== 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; | |||
# 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> | |||
== Servers == | == Servers == | ||
=== Homeservers === | === Homeservers === | ||
==== Conduit ==== | |||
<syntaxhighlight lang="nixos"> | |||
{ | |||
# 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; | |||
# server_name = yourDomainName; | |||
# port = yourPort; | |||
address = "::1"; | |||
database_backend = "rocksdb"; | |||
# See https://www.metered.ca/tools/openrelay | |||
turn_uris = [ | |||
"turn:staticauth.openrelay.metered.ca:80?transport=udp" | |||
"turn:staticauth.openrelay.metered.ca:80?transport=tcp" | |||
]; | |||
turn_secret = "openrelayprojectsecret"; | |||
}; | |||
}; | |||
} | |||
</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. | |||
===== 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 50: | Line 122: | ||
verbose | verbose | ||
# ban private IP ranges | # ban private IP ranges | ||
no-multicast-peers | |||
denied-peer-ip=0.0.0.0-0.255.255.255 | |||
denied-peer-ip=10.0.0.0-10.255.255.255 | denied-peer-ip=10.0.0.0-10.255.255.255 | ||
denied-peer-ip=100.64.0.0-100.127.255.255 | |||
denied-peer-ip=127.0.0.0-127.255.255.255 | denied-peer-ip=127.0.0.0-127.255.255.255 | ||
denied-peer-ip=169.254.0.0-169.254.255.255 | |||
denied-peer-ip=172.16.0.0-172.31.255.255 | denied-peer-ip=172.16.0.0-172.31.255.255 | ||
denied-peer-ip=192.0.0.0-192.0.0.255 | |||
denied-peer-ip=192.0.2.0-192.0.2.255 | |||
denied-peer-ip=192.88.99.0-192.88.99.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=192.168.0.0-192.168.255.255 | ||
denied-peer-ip= | denied-peer-ip=198.18.0.0-198.19.255.255 | ||
denied-peer-ip=255.255.255.255-255.255.255.255 | denied-peer-ip=198.51.100.0-198.51.100.255 | ||
denied-peer-ip=203.0.113.0-203.0.113.255 | |||
denied-peer-ip=240.0.0.0-255.255.255.255 | |||
denied-peer-ip=::1 | |||
denied-peer-ip=64:ff9b::-64:ff9b::ffff:ffff | |||
denied-peer-ip=::ffff:0.0.0.0-::ffff:255.255.255.255 | |||
denied-peer-ip=100::-100::ffff:ffff:ffff:ffff | |||
denied-peer-ip=2001::-2001:1ff:ffff:ffff:ffff:ffff:ffff:ffff | |||
denied-peer-ip=2002::-2002:ffff:ffff:ffff:ffff:ffff:ffff:ffff | |||
denied-peer-ip=fc00::-fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff | |||
denied-peer-ip=fe80::-febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff | |||
''; | ''; | ||
}; | }; | ||
Line 62: | Line 150: | ||
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; | |||
to = max-port; | |||
}; | |||
in | in | ||
{ | { | ||
allowedUDPPortRanges = range; | allowedUDPPortRanges = range; | ||
allowedUDPPorts = [ 3478 ]; | allowedUDPPorts = [ 3478 5349 ]; | ||
allowedTCPPortRanges = | allowedTCPPortRanges = [ ]; | ||
allowedTCPPorts = [ 3478 ]; | allowedTCPPorts = [ 3478 5349 ]; | ||
}; | }; | ||
}; | }; | ||
Line 78: | Line 166: | ||
/* insert here the right configuration to obtain a certificate */ | /* insert here the right configuration to obtain a certificate */ | ||
postRun = "systemctl restart coturn.service"; | postRun = "systemctl restart coturn.service"; | ||
group = "turnserver"; | group = "turnserver"; | ||
}; | }; | ||
# 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 89: | Line 176: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
===== Synapse with Workers ===== | |||
There's an external module to automatically set up synapse and configure nginx with workers: | |||
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. | |||
==== mautrix-telegram ==== | ==== mautrix-telegram ==== | ||
Full configuration reference: https://github.com/tulir/mautrix-telegram/blob/master/mautrix_telegram/example-config.yaml | Full configuration reference: | ||
https://github.com/tulir/mautrix-telegram/blob/master/mautrix_telegram/example-config.yaml | |||
Example NixOS config: | Example NixOS config: | ||
Line 100: | Line 194: | ||
<syntaxhighlight lang="nix"> | <syntaxhighlight lang="nix"> | ||
{ | { | ||
services.matrix-synapse = { | services.matrix-synapse = { | ||
enable = true; | enable = true; | ||
app_service_config_files = [ | settings.app_service_config_files = [ | ||
# The registration file is automatically generated after starting the appservice for the first time. | # The registration file is automatically generated after starting the | ||
# cp /var/lib/mautrix-telegram/telegram-registration.yaml /var/lib/matrix-synapse/ | # appservice for the first time. | ||
# chown matrix-synapse:matrix-synapse /var/lib/matrix-synapse/telegram-registration.yaml | # 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" | "/var/lib/matrix-synapse/telegram-registration.yaml" | ||
]; | ]; | ||
Line 118: | Line 210: | ||
services.mautrix-telegram = { | services.mautrix-telegram = { | ||
enable = true; | enable = true; | ||
environmentFile = /etc/secrets/mautrix-telegram.env; | |||
# The appservice is pre-configured to use SQLite by default. It's also possible to use PostgreSQL. | # file containing the appservice and telegram tokens | ||
environmentFile = "/etc/secrets/mautrix-telegram.env"; | |||
# The appservice is pre-configured to use SQLite by default. | |||
# It's also possible to use PostgreSQL. | |||
settings = { | settings = { | ||
homeserver = { | homeserver = { | ||
Line 134: | Line 230: | ||
}; | }; | ||
# The service uses SQLite by default, but it's also possible to use PostgreSQL instead: | # The service uses SQLite by default, but it's also possible to use | ||
# PostgreSQL instead: | |||
#database = "postgresql:///mautrix-telegram?host=/run/postgresql"; | #database = "postgresql:///mautrix-telegram?host=/run/postgresql"; | ||
}; | }; | ||
Line 141: | Line 238: | ||
permissions = { | permissions = { | ||
"@someadmin:domain.tld" = "admin"; | "@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!) | |||
]; | |||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 151: | Line 269: | ||
==== mautrix-whatsapp ==== | ==== mautrix-whatsapp ==== | ||
Packaged as [https://search.nixos.org/packages | Packaged as [https://search.nixos.org/packages?query=mautrix-whatsapp mautrix-whatsapp]. | ||
[https://github.com/NixOS/nixpkgs/pull/ | 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 | |||
Full configuration reference: https://github.com/matrix-org/matrix-appservice-irc/blob/develop/config.sample.yaml | |||
Upstream documentation: https://matrix-org.github.io/matrix-appservice-irc/latest/introduction.html | |||
Example configuration: | |||
<syntaxhighlight lang="nix"> | |||
services.matrix-appservice-irc = { | |||
enable = true; | |||
registrationUrl = "https://ircbridge.mydomain.com"; # Or localhost | |||
# Everything from here is passed to the appservice | |||
settings = { | |||
homeserver.url = "https://matrix.mydomain.com"; # Or localhost | |||
homeserver.domain = "mydomain.com"; | |||
# Bridge settings for Freenode. You can bridge multiple services. | |||
ircService.servers."chat.freenode.net" = { | |||
name = "freenode"; | |||
port = 6697; | |||
ssl = true; | |||
dynamicChannels = { | |||
enabled = true; | |||
aliasTemplate = "#irc_$CHANNEL"; | |||
groupId = "+irc:localhost"; | |||
}; | |||
matrixClients = { | |||
userTemplate = "@irc_$NICK"; | |||
}; | |||
ircClients = { | |||
nickTemplate = "$LOCALPART[m]"; | |||
allowNickChanges = true; | |||
}; | |||
membershipLists = { | |||
enabled = true; | |||
global = { | |||
ircToMatrix = { | |||
initial = true; | |||
incremental = true; | |||
}; | |||
matrixToIrc = { | |||
initial = true; | |||
incremental = true; | |||
}; | |||
}; | |||
}; | |||
}; | |||
}; | |||
}; | |||
</syntaxhighlight> | |||
This example configuration creates a bridge for only one IRC network, Freenode. Some options are set to make an example, but you absolutely *should* read the whole configuration documentation and set all options you want before starting. The example options show you how to adapt the room/user name space template for the use case where you only have one IRC server bridged, and also enables increased membership sync because it is disabled on the official Freenode bridge. | |||
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: https://github.com/Half-Shot/matrix-appservice-discord/blob/master/config/config.sample.yaml | Full configuration reference: | ||
https://github.com/Half-Shot/matrix-appservice-discord/blob/master/config/config.sample.yaml | |||
Example NixOS config: | Example NixOS config: | ||
Line 166: | Line 341: | ||
<syntaxhighlight lang="nix"> | <syntaxhighlight lang="nix"> | ||
{ | { | ||
services.matrix-synapse = { | services.matrix-synapse = { | ||
enable = true; | enable = true; | ||
app_service_config_files = [ | app_service_config_files = [ | ||
# The registration file is automatically generated after starting the appservice for the first time. | # The registration file is automatically generated after starting the | ||
# cp /var/lib/matrix-appservice-discord/discord-registration.yaml /var/lib/matrix-synapse/ | # appservice for the first time. | ||
# chown matrix-synapse:matrix-synapse /var/lib/matrix-synapse/discord-registration.yaml | # 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" | "/var/lib/matrix-synapse/discord-registration.yaml" | ||
]; | ]; | ||
Line 190: | Line 358: | ||
enable = true; | enable = true; | ||
environmentFile = /etc/keyring/matrix-appservice-discord/tokens.env; | 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. | # The appservice is pre-configured to use SQLite by default. | ||
# It's also possible to use PostgreSQL. | |||
settings = { | settings = { | ||
bridge = { | bridge = { | ||
Line 197: | Line 366: | ||
}; | }; | ||
# The service uses SQLite by default, but it's also possible to use PostgreSQL instead: | # The service uses SQLite by default, but it's also possible to use | ||
# PostgreSQL instead: | |||
#database = { | #database = { | ||
# filename = ""; # empty value to disable sqlite | # filename = ""; # empty value to disable sqlite | ||
Line 206: | Line 376: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== See also == | == See also == | ||
* [[Mjolnir]] - a Matrix moderation tool | |||
* [https://matrix.to/#/!vxTmkuJzhGPsMdkAOc:transformierende-gesellschaft.org?via=transformierende-gesellschaft.org The Nix Matrix Subsystem chat room, on Matrix] | |||
[[Category:Applications]] | |||
[[Category:Server]] | |||
[[Category:NixOS Manual]] |