diff options
Diffstat (limited to 'nixos/modules/services/matrix/synapse.xml')
| -rw-r--r-- | nixos/modules/services/matrix/synapse.xml | 263 |
1 files changed, 0 insertions, 263 deletions
diff --git a/nixos/modules/services/matrix/synapse.xml b/nixos/modules/services/matrix/synapse.xml deleted file mode 100644 index 686aec93ab6..00000000000 --- a/nixos/modules/services/matrix/synapse.xml +++ /dev/null @@ -1,263 +0,0 @@ -<!-- 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> - 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}"; - clientConfig = { - "m.homeserver".base_url = "https://${fqdn}"; - "m.identity_server" = {}; - }; - 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 { - networking.hostName = "myhostname"; - networking.domain = "example.org"; - networking.firewall.allowedTCPPorts = [ 80 443 ]; - - 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"; - ''; - - services.nginx = { - 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}" = { - 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; - ''; - # 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 = { - 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> - </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>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> - <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! -</programlisting> - <para> - 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> -{ - services.matrix-synapse.extraConfigFiles = [ - "/run/secrets/matrix-shared-secret" - ]; -} -</programlisting> - </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> - <programlisting> -{ - services.nginx.virtualHosts."element.${fqdn}" = { - enableACME = true; - forceSSL = true; - serverAliases = [ - "element.${config.networking.domain}" - ]; - - root = pkgs.element-web.override { - conf = { - default_server_config = clientConfig; # see `clientConfig` from the snippet above. - }; - }; - }; -} -</programlisting> - <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> |