diff options
Diffstat (limited to 'nixos/modules/services/matrix/synapse.xml')
| -rw-r--r-- | nixos/modules/services/matrix/synapse.xml | 439 |
1 files changed, 213 insertions, 226 deletions
diff --git a/nixos/modules/services/matrix/synapse.xml b/nixos/modules/services/matrix/synapse.xml index 40ad72173a53..686aec93ab67 100644 --- a/nixos/modules/services/matrix/synapse.xml +++ b/nixos/modules/services/matrix/synapse.xml @@ -1,256 +1,243 @@ -<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> - +<!-- Do not edit this file directly, edit its companion .md instead + and regenerate this file using nixos/doc/manual/md-to-db.sh --> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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> - <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://matrix-org.github.io/synapse/latest/setup/installation.html"> - installation instructions of Synapse </link>. -<programlisting> + 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://matrix-org.github.io/synapse/latest/setup/installation.html">installation + instructions of Synapse</link> . + </para> + <programlisting> { pkgs, lib, config, ... }: let - fqdn = "${config.networking.hostName}.${config.networking.domain}"; + fqdn = "${config.networking.hostName}.${config.networking.domain}"; clientConfig = { - "m.homeserver".base_url = "https://${fqdn}"; - "m.identity_server" = {}; + "m.homeserver".base_url = "https://${fqdn}"; + "m.identity_server" = {}; }; - serverConfig."m.server" = "${config.services.matrix-synapse.settings.server_name}:443"; + serverConfig."m.server" = "${config.services.matrix-synapse.settings.server_name}:443"; mkWellKnown = data: '' add_header Content-Type application/json; add_header Access-Control-Allow-Origin *; return 200 '${builtins.toJSON data}'; ''; in { - <xref linkend="opt-networking.hostName" /> = "myhostname"; - <xref linkend="opt-networking.domain" /> = "example.org"; - <xref linkend="opt-networking.firewall.allowedTCPPorts" /> = [ 80 443 ]; + networking.hostName = "myhostname"; + networking.domain = "example.org"; + networking.firewall.allowedTCPPorts = [ 80 443 ]; - <xref linkend="opt-services.postgresql.enable" /> = true; - <xref linkend="opt-services.postgresql.initialScript" /> = pkgs.writeText "synapse-init.sql" '' - CREATE ROLE "matrix-synapse" WITH LOGIN PASSWORD 'synapse'; - CREATE DATABASE "matrix-synapse" WITH OWNER "matrix-synapse" + services.postgresql.enable = true; + services.postgresql.initialScript = 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"; + LC_COLLATE = "C" + LC_CTYPE = "C"; ''; services.nginx = { - <link linkend="opt-services.nginx.enable">enable</link> = true; - <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> = { - "${config.networking.domain}" = { <co xml:id='ex-matrix-synapse-dns' /> - <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> = mkWellKnown serverConfig; <co xml:id='ex-matrix-synapse-well-known-server' /> - <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/client".extraConfig</link> = mkWellKnown clientConfig; <co xml:id='ex-matrix-synapse-well-known-client' /> + enable = true; + recommendedTlsSettings = true; + recommendedOptimisation = true; + recommendedGzipSettings = true; + recommendedProxySettings = true; + virtualHosts = { + # If the A and AAAA DNS records on example.org do not point on the same host as the + # records for myhostname.example.org, you can easily move the /.well-known + # virtualHost section of the code to the host that is serving example.org, while + # the rest stays on myhostname.example.org with no other changes required. + # This pattern also allows to seamlessly move the homeserver from + # myhostname.example.org to myotherhost.example.org by only changing the + # /.well-known redirection target. + "${config.networking.domain}" = { + enableACME = true; + forceSSL = true; + # This section is not needed if the server_name of matrix-synapse is equal to + # the domain (i.e. example.org from @foo:example.org) and the federation port + # is 8448. + # Further reference can be found in the docs about delegation under + # https://matrix-org.github.io/synapse/latest/delegate.html + locations."= /.well-known/matrix/server".extraConfig = mkWellKnown serverConfig; + # This is usually needed for homeserver discovery (from e.g. other Matrix clients). + # Further reference can be found in the upstream docs at + # https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient + locations."= /.well-known/matrix/client".extraConfig = mkWellKnown clientConfig; }; - "${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_.locations._name_.extraConfig">locations."/".extraConfig</link> = '' <co xml:id='ex-matrix-synapse-rev-default' /> + "${fqdn}" = { + enableACME = true; + forceSSL = true; + # It's also possible to do a redirect here or something else, this vhost is not + # needed for Matrix. It's recommended though to *not put* element + # here, see also the section about Element. + locations."/".extraConfig = '' return 404; ''; - <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/_matrix".proxyPass</link> = "http://[::1]:8008"; <co xml:id='ex-matrix-synapse-rev-proxy-pass' /> - <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/_synapse/client".proxyPass</link> = "http://[::1]:8008"; <co xml:id='ex-matrix-synapse-rev-client' /> + # Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash + # *must not* be used here. + locations."/_matrix".proxyPass = "http://[::1]:8008"; + # Forward requests for e.g. SSO and password-resets. + locations."/_synapse/client".proxyPass = "http://[::1]:8008"; }; }; }; services.matrix-synapse = { - <link linkend="opt-services.matrix-synapse.enable">enable</link> = true; - <link linkend="opt-services.matrix-synapse.settings.server_name">settings.server_name</link> = config.networking.domain; - <link linkend="opt-services.matrix-synapse.settings.listeners">settings.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" "federation" ]; - <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.compress">compress</link> = true; + enable = true; + settings.server_name = config.networking.domain; + settings.listeners = [ + { port = 8008; + bind_addresses = [ "::1" ]; + type = "http"; + tls = false; + x_forwarded = true; + resources = [ { + names = [ "client" "federation" ]; + compress = true; } ]; } ]; }; } </programlisting> - </para> - <calloutlist> - <callout arearefs='ex-matrix-synapse-dns'> + </section> + <section xml:id="module-services-matrix-register-users"> + <title>Registering Matrix users</title> <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. + If you want to run a server with public registration by anybody, + you can then enable + <literal>services.matrix-synapse.settings.enable_registration = true;</literal>. + Otherwise, or you can generate a registration secret with + <command>pwgen -s 64 1</command> and set it with + <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />. + To create a new user or admin, run the following after you have + set the secret and have rebuilt NixOS: </para> - </callout> - <callout arearefs='ex-matrix-synapse-well-known-server'> - <para> - This section is not needed if the <link linkend="opt-services.matrix-synapse.settings.server_name">server_name</link> - of <package>matrix-synapse</package> is equal to the domain (i.e. - <literal>example.org</literal> from <literal>@foo:example.org</literal>) - and the federation port is 8448. - Further reference can be found in the <link xlink:href="https://matrix-org.github.io/synapse/latest/delegate.html">docs - about delegation</link>. - </para> - </callout> - <callout arearefs='ex-matrix-synapse-well-known-client'> - <para> - This is usually needed for homeserver discovery (from e.g. other Matrix clients). - Further reference can be found in the <link xlink:href="https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient">upstream docs</link> - </para> - </callout> - <callout arearefs='ex-matrix-synapse-rev-default'> - <para> - It's also possible to do a redirect here or something else, this vhost is not - needed for Matrix. It's recommended though to <emphasis>not put</emphasis> element - here, see also the <link linkend='ex-matrix-synapse-rev-default'>section about Element</link>. - </para> - </callout> - <callout arearefs='ex-matrix-synapse-rev-proxy-pass'> - <para> - Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash - <emphasis>must not</emphasis> be used here. - </para> - </callout> - <callout arearefs='ex-matrix-synapse-rev-client'> - <para> - Forward requests for e.g. SSO and password-resets. - </para> - </callout> - </calloutlist> - </section> - <section xml:id="module-services-matrix-register-users"> - <title>Registering Matrix users</title> - <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-shell -p 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> + <programlisting> +$ nix-shell -p matrix-synapse +$ register_new_matrix_user -k your-registration-shared-secret http://localhost:8008 +New user localpart: your-username +Password: +Confirm password: +Make admin [no]: Success! -</screen> - In the example, this would create a user with the Matrix Identifier - <literal>@your-username:example.org</literal>. - <warning> +</programlisting> <para> - When using <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />, the secret - will end up in the world-readable store. Instead it's recommended to deploy the secret - in an additional file like this: - <itemizedlist> - <listitem> - <para> - Create a file with the following contents: -<programlisting>registration_shared_secret: your-very-secret-secret</programlisting> - </para> - </listitem> - <listitem> - <para> - Deploy the file with a secret-manager such as <link xlink:href="https://nixops.readthedocs.io/en/latest/overview.html#managing-keys"><option>deployment.keys</option></link> - from <citerefentry><refentrytitle>nixops</refentrytitle><manvolnum>1</manvolnum></citerefentry> - or <link xlink:href="https://github.com/Mic92/sops-nix/">sops-nix</link> to - e.g. <filename>/run/secrets/matrix-shared-secret</filename> and ensure that it's readable - by <package>matrix-synapse</package>. - </para> - </listitem> - <listitem> - <para> - Include the file like this in your configuration: -<programlisting> + In the example, this would create a user with the Matrix + Identifier <literal>@your-username:example.org</literal>. + </para> + <warning> + <para> + When using + <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />, + the secret will end up in the world-readable store. Instead it’s + recommended to deploy the secret in an additional file like + this: + </para> + <itemizedlist> + <listitem> + <para> + Create a file with the following contents: + </para> + <programlisting> +registration_shared_secret: your-very-secret-secret +</programlisting> + </listitem> + <listitem> + <para> + Deploy the file with a secret-manager such as + <link xlink:href="https://nixops.readthedocs.io/en/latest/overview.html#managing-keys"><option>deployment.keys</option></link> + from + <citerefentry><refentrytitle>nixops</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or + <link xlink:href="https://github.com/Mic92/sops-nix/">sops-nix</link> + to e.g. + <filename>/run/secrets/matrix-shared-secret</filename> and + ensure that it’s readable by + <literal>matrix-synapse</literal>. + </para> + </listitem> + <listitem> + <para> + Include the file like this in your configuration: + </para> + <programlisting> { - <xref linkend="opt-services.matrix-synapse.extraConfigFiles" /> = [ - "/run/secrets/matrix-shared-secret" + services.matrix-synapse.extraConfigFiles = [ + "/run/secrets/matrix-shared-secret" ]; } </programlisting> - </para> - </listitem> - </itemizedlist> + </listitem> + </itemizedlist> + </warning> + <note> + <para> + It’s also possible to user alternative authentication mechanism + such as + <link xlink:href="https://github.com/matrix-org/matrix-synapse-ldap3">LDAP + (via <literal>matrix-synapse-ldap3</literal>)</link> or + <link xlink:href="https://matrix-org.github.io/synapse/latest/openid.html">OpenID</link>. + </para> + </note> + </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 + <literal>https://element.myhostname.example.org</literal> and + <literal>https://element.example.org</literal>. 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. </para> - </warning> - </para> - <note> - <para> - It's also possible to user alternative authentication mechanism such as - <link xlink:href="https://github.com/matrix-org/matrix-synapse-ldap3">LDAP (via <literal>matrix-synapse-ldap3</literal>)</link> - or <link xlink:href="https://matrix-org.github.io/synapse/latest/openid.html">OpenID</link>. - </para> - </note> - </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> + <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}" + services.nginx.virtualHosts."element.${fqdn}" = { + enableACME = true; + forceSSL = true; + serverAliases = [ + "element.${config.networking.domain}" ]; - <link linkend="opt-services.nginx.virtualHosts._name_.root">root</link> = pkgs.element-web.override { + root = pkgs.element-web.override { conf = { default_server_config = clientConfig; # see `clientConfig` from the snippet above. }; @@ -258,19 +245,19 @@ Success! }; } </programlisting> - </para> - - <note> - <para> - 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/element-web/tree/v1.10.0#important-security-notes">Element - Important Security Notes</link> for more information on this subject. - </para> - </note> - </section> + <note> + <para> + 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/element-web/tree/v1.10.0#important-security-notes">Element + Important Security Notes</link> for more information on this + subject. + </para> + </note> + </section> </chapter> |