diff options
Diffstat (limited to 'nixos/modules/services/matrix/matrix-synapse.xml')
-rw-r--r-- | nixos/modules/services/matrix/matrix-synapse.xml | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/nixos/modules/services/matrix/matrix-synapse.xml b/nixos/modules/services/matrix/matrix-synapse.xml new file mode 100644 index 00000000000..cf33957d58e --- /dev/null +++ b/nixos/modules/services/matrix/matrix-synapse.xml @@ -0,0 +1,231 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="module-services-matrix"> + <title>Matrix</title> + <para> + <link xlink:href="https://matrix.org/">Matrix</link> is an open standard for + interoperable, decentralised, real-time communication over IP. It can be used + to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things + communication - or anywhere you need a standard HTTP API for publishing and + subscribing to data whilst tracking the conversation history. + </para> + <para> + This chapter will show you how to set up your own, self-hosted Matrix + homeserver using the Synapse reference homeserver, and how to serve your own + copy of the Element web client. See the + <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try + Matrix Now!</link> overview page for links to Element Apps for Android and iOS, + desktop clients, as well as bridges to other networks and other projects + around Matrix. + </para> + <section xml:id="module-services-matrix-synapse"> + <title>Synapse Homeserver</title> + + <para> + <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> is + the reference homeserver implementation of Matrix from the core development + team at matrix.org. The following configuration example will set up a + synapse server for the <literal>example.org</literal> domain, served from + the host <literal>myhostname.example.org</literal>. For more information, + please refer to the + <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation"> + installation instructions of Synapse </link>. +<programlisting> +{ pkgs, lib, ... }: +let + fqdn = + let + join = hostName: domain: hostName + lib.optionalString (domain != null) ".${domain}"; + in join config.networking.hostName config.networking.domain; +in { + networking = { + <link linkend="opt-networking.hostName">hostName</link> = "myhostname"; + <link linkend="opt-networking.domain">domain</link> = "example.org"; + }; + <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ]; + + <link linkend="opt-services.postgresql.enable">services.postgresql.enable</link> = true; + <link linkend="opt-services.postgresql.initialScript">services.postgresql.initialScript</link> = pkgs.writeText "synapse-init.sql" '' + CREATE ROLE "matrix-synapse" WITH LOGIN PASSWORD 'synapse'; + CREATE DATABASE "matrix-synapse" WITH OWNER "matrix-synapse" + TEMPLATE template0 + LC_COLLATE = "C" + LC_CTYPE = "C"; + ''; + + services.nginx = { + <link linkend="opt-services.nginx.enable">enable</link> = true; + # only recommendedProxySettings and recommendedGzipSettings are strictly required, + # but the rest make sense as well + <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true; + <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true; + <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true; + <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true; + + <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = { + # This host section can be placed on a different host than the rest, + # i.e. to delegate from the host being accessible as ${config.networking.domain} + # to another host actually running the Matrix homeserver. + "${config.networking.domain}" = { + <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true; + <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; + + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/server".extraConfig</link> = + let + # use 443 instead of the default 8448 port to unite + # the client-server and server-server port for simplicity + server = { "m.server" = "${fqdn}:443"; }; + in '' + add_header Content-Type application/json; + return 200 '${builtins.toJSON server}'; + ''; + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/client".extraConfig</link> = + let + client = { + "m.homeserver" = { "base_url" = "https://${fqdn}"; }; + "m.identity_server" = { "base_url" = "https://vector.im"; }; + }; + # ACAO required to allow element-web on any URL to request this json file + in '' + add_header Content-Type application/json; + add_header Access-Control-Allow-Origin *; + return 200 '${builtins.toJSON client}'; + ''; + }; + + # Reverse proxy for Matrix client-server and server-server communication + ${fqdn} = { + <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true; + <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; + + # Or do a redirect instead of the 404, or whatever is appropriate for you. + # But do not put a Matrix Web client here! See the Element web section below. + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."/".extraConfig</link> = '' + return 404; + ''; + + # forward all Matrix API calls to the synapse Matrix homeserver + locations."/_matrix" = { + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">proxyPass</link> = "http://[::1]:8008"; # without a trailing / + }; + }; + }; + }; + services.matrix-synapse = { + <link linkend="opt-services.matrix-synapse.enable">enable</link> = true; + <link linkend="opt-services.matrix-synapse.settings.server_name">server_name</link> = config.networking.domain; + <link linkend="opt-services.matrix-synapse.settings.listeners">listeners</link> = [ + { + <link linkend="opt-services.matrix-synapse.settings.listeners._.port">port</link> = 8008; + <link linkend="opt-services.matrix-synapse.settings.listeners._.bind_addresses">bind_addresses</link> = [ "::1" ]; + <link linkend="opt-services.matrix-synapse.settings.listeners._.type">type</link> = "http"; + <link linkend="opt-services.matrix-synapse.settings.listeners._.tls">tls</link> = false; + <link linkend="opt-services.matrix-synapse.settings.listeners._.x_forwarded">x_forwarded</link> = true; + <link linkend="opt-services.matrix-synapse.settings.listeners._.resources">resources</link> = [ { + <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.names">names</link> = [ "client" ]; + <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.compress">compress</link> = true; + } { + <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.names">names</link> = [ "federation" ]; + <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.compress">compress</link> = false; + } ]; + } + ]; + }; +} +</programlisting> + </para> + + <para> + If the <code>A</code> and <code>AAAA</code> DNS records on + <literal>example.org</literal> do not point on the same host as the records + for <code>myhostname.example.org</code>, you can easily move the + <code>/.well-known</code> virtualHost section of the code to the host that + is serving <literal>example.org</literal>, while the rest stays on + <literal>myhostname.example.org</literal> with no other changes required. + This pattern also allows to seamlessly move the homeserver from + <literal>myhostname.example.org</literal> to + <literal>myotherhost.example.org</literal> by only changing the + <code>/.well-known</code> redirection target. + </para> + + <para> + If you want to run a server with public registration by anybody, you can + then enable <literal><link linkend="opt-services.matrix-synapse.settings.enable_registration">services.matrix-synapse.settings.enable_registration</link> = + true;</literal>. Otherwise, or you can generate a registration secret with + <command>pwgen -s 64 1</command> and set it with + <option><link linkend="opt-services.matrix-synapse.settings.registration_shared_secret">services.matrix-synapse.settings.registration_shared_secret</link></option>. + To create a new user or admin, run the following after you have set the secret + and have rebuilt NixOS: +<screen> +<prompt>$ </prompt>nix run nixpkgs.matrix-synapse +<prompt>$ </prompt>register_new_matrix_user -k <replaceable>your-registration-shared-secret</replaceable> http://localhost:8008 +<prompt>New user localpart: </prompt><replaceable>your-username</replaceable> +<prompt>Password:</prompt> +<prompt>Confirm password:</prompt> +<prompt>Make admin [no]:</prompt> +Success! +</screen> + In the example, this would create a user with the Matrix Identifier + <literal>@your-username:example.org</literal>. Note that the registration + secret ends up in the nix store and therefore is world-readable by any user + on your machine, so it makes sense to only temporarily activate the + <link linkend="opt-services.matrix-synapse.settings.registration_shared_secret">registration_shared_secret</link> + option until a better solution for NixOS is in place. + </para> + </section> + <section xml:id="module-services-matrix-element-web"> + <title>Element (formerly known as Riot) Web Client</title> + + <para> + <link xlink:href="https://github.com/vector-im/riot-web/">Element Web</link> is + the reference web client for Matrix and developed by the core team at + matrix.org. Element was formerly known as Riot.im, see the + <link xlink:href="https://element.io/blog/welcome-to-element/">Element introductory blog post</link> + for more information. The following snippet can be optionally added to the code before + to complete the synapse installation with a web client served at + <code>https://element.myhostname.example.org</code> and + <code>https://element.example.org</code>. Alternatively, you can use the hosted + copy at <link xlink:href="https://app.element.io/">https://app.element.io/</link>, + or use other web clients or native client applications. Due to the + <literal>/.well-known</literal> urls set up done above, many clients should + fill in the required connection details automatically when you enter your + Matrix Identifier. See + <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try + Matrix Now!</link> for a list of existing clients and their supported + featureset. +<programlisting> +{ + services.nginx.virtualHosts."element.${fqdn}" = { + <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true; + <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; + <link linkend="opt-services.nginx.virtualHosts._name_.serverAliases">serverAliases</link> = [ + "element.${config.networking.domain}" + ]; + + <link linkend="opt-services.nginx.virtualHosts._name_.root">root</link> = pkgs.element-web.override { + conf = { + default_server_config."m.homeserver" = { + "base_url" = "https://${fqdn}"; + "server_name" = "${fqdn}"; + }; + }; + }; + }; +} +</programlisting> + </para> + + <para> + Note that the Element developers do not recommend running Element and your Matrix + homeserver on the same fully-qualified domain name for security reasons. In + the example, this means that you should not reuse the + <literal>myhostname.example.org</literal> virtualHost to also serve Element, + but instead serve it on a different subdomain, like + <literal>element.example.org</literal> in the example. See the + <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Element + Important Security Notes</link> for more information on this subject. + </para> + </section> +</chapter> |