git.iko.soy/typeable/nixpkgs
on master help sign in
nixos/matrix: add manual section

about self-hosting a matrix client and server

commitef52869ef1e04bdd080aca4a5af7f56c14b16087 authorFlorian Jacob <projects+git@florianjacob.de> dateTue 12 Mar 2019, 11:01 (8 years ago) parentb60b304
3 files changed+209
nixos/doc/manual/configuration/configuration.xml+1 nixos/doc/manual/configuration/matrix.xml+197 nixos/doc/manual/release-notes/rl-1903.xml+11
nixos/doc/manual/configuration/configuration.xml+1
@@ -21,6 +21,7 @@
2121 <xi:include href="xfce.xml" />
2222 <xi:include href="networking.xml" />
2323 <xi:include href="linux-kernel.xml" />
24+ <xi:include href="matrix.xml" />
2425 <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
2526 <xi:include href="profiles.xml" />
2627<!-- Apache; libvirtd virtualisation -->
nixos/doc/manual/configuration/matrix.xmlnew file+197
@@ -0,0 +1,197 @@
1+<chapter xmlns="http://docbook.org/ns/docbook"
2+ xmlns:xlink="http://www.w3.org/1999/xlink"
3+ xmlns:xi="http://www.w3.org/2001/XInclude"
4+ version="5.0"
5+ xml:id="module-services-matrix">
6+ <title>Matrix</title>
7+ <para>
8+ <link xlink:href="https://matrix.org/">Matrix</link>
9+ is an open standard for interoperable, decentralised, real-time communication over IP.
10+ It can be used to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things communication -
11+ or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.
12+ </para>
13+ <para>
14+ This chapter will show you how to set up your own, self-hosted Matrix homeserver using the Synapse reference homeserver,
15+ and how to serve your own copy of the Riot web client.
16+ See the <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try Matrix Now!</link>
17+ overview page for links to Riot Apps for Android and iOS, desktop clients,
18+ as well as bridges to other networks and other projects around Matrix.
19+ </para>
20+
21+ <section xml:id="module-services-matrix-synapse">
22+ <title>Synapse Homeserver</title>
23+ <para>
24+ <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link>
25+ is the reference homeserver implementation of Matrix from the core development team at matrix.org.
26+ The following configuration example will set up a synapse server for the <literal>example.org</literal>
27+ domain, served from the host <literal>myhostname.example.org</literal>.
28+ For more information, please refer to the
29+ <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation">
30+ installation instructions of Synapse
31+ </link>.
32+ <programlisting>
33+ let
34+ fqdn =
35+ let
36+ join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
37+ in join config.networking.hostName config.networking.domain;
38+ in {
39+ networking = {
40+ hostName = "myhostname";
41+ domain = "example.org";
42+ };
43+ networking.firewall.allowedTCPPorts = [ 80 443 ];
44+
45+ services.nginx = {
46+ enable = true;
47+ # only recommendedProxySettings and recommendedGzipSettings are strictly required,
48+ # but the rest make sense as well
49+ recommendedTlsSettings = true;
50+ recommendedOptimisation = true;
51+ recommendedGzipSettings = true;
52+ recommendedProxySettings = true;
53+
54+ virtualHosts = {
55+ # This host section can be placed on a different host than the rest,
56+ # i.e. to delegate from the host being accessible as ${config.networking.domain}
57+ # to another host actually running the Matrix homeserver.
58+ "${config.networking.domain}" = {
59+ locations."= /.well-known/matrix/server".extraConfig =
60+ let
61+ # use 443 instead of the default 8448 port to unite
62+ # the client-server and server-server port for simplicity
63+ server = { "m.server" = "${fqdn}:443"; };
64+ in ''
65+ add_header Content-Type application/json;
66+ return 200 '${builtins.toJSON server}';
67+ '';
68+ locations."= /.well-known/matrix/client".extraConfig =
69+ let
70+ client = {
71+ "m.homeserver" = { "base_url" = "https://${fqdn}"; };
72+ "m.identity_server" = { "base_url" = "https://vector.im"; };
73+ };
74+ # ACAO required to allow riot-web on any URL to request this json file
75+ in ''
76+ add_header Content-Type application/json;
77+ add_header Access-Control-Allow-Origin *;
78+ return 200 '${builtins.toJSON client}';
79+ '';
80+ };
81+
82+ # Reverse proxy for Matrix client-server and server-server communication
83+ ${fqdn} = {
84+ enableACME = true;
85+ forceSSL = true;
86+
87+ # Or do a redirect instead of the 404, or whatever is appropriate for you.
88+ # But do not put a Matrix Web client here! See the Riot Web section below.
89+ locations."/".extraConfig = ''
90+ return 404;
91+ '';
92+
93+ # forward all Matrix API calls to the synapse Matrix homeserver
94+ locations."/_matrix" = {
95+ proxyPass = "http://[::1]:8008";
96+ };
97+ };
98+ };
99+ };
100+ services.matrix-synapse = {
101+ enable = true;
102+ server_name = config.networking.domain;
103+ listeners = [
104+ {
105+ port = 8008;
106+ bind_address = "::1";
107+ type = "http";
108+ tls = false;
109+ x_forwarded = true;
110+ resources = [
111+ { names = [ "client" "federation" ]; compress = false; }
112+ ];
113+ }
114+ ];
115+ };
116+ };
117+ </programlisting>
118+ </para>
119+ <para>
120+ If the <code>A</code> and <code>AAAA</code> DNS records on <literal>example.org</literal>
121+ do not point on the same host as the records for <code>myhostname.example.org</code>,
122+ you can easily move the <code>/.well-known</code> virtualHost section of the code
123+ to the host that is serving <literal>example.org</literal>,
124+ while the rest stays on <literal>myhostname.example.org</literal>
125+ with no other changes required.
126+ This pattern also allows to seamlessly move the homeserver from <literal>myhostname.example.org</literal>
127+ to <literal>myotherhost.example.org</literal> by only changing the <code>/.well-known</code> redirection target.
128+ </para>
129+
130+ <para>
131+ If you want to run a server with public registration by anybody,
132+ you can then enable
133+ <option>services.matrix-synapse.enable_registration = true;</option>.
134+ Otherwise, or you can generate a registration secret with <command>pwgen -s 64 1</command>
135+ and set it with
136+ <option>services.matrix-synapse.registration_shared_secret</option>.
137+ To create a new user or admin,
138+ run the following after you have set the secret and have rebuilt NixOS:
139+
140+ <programlisting>
141+ $ nix run nixpkgs.matrix-synapse
142+ $ register_new_matrix_user -k &lt;your-registration-shared-secret&gt; http://localhost:8008
143+ New user localpart: &lt;your-username&gt;
144+ Password:
145+ Confirm password:
146+ Make admin [no]:
147+ Success!
148+ </programlisting>
149+ In the example, this would create a user with the Matrix Identifier
150+ <literal>@your-username:example.org</literal>.
151+ Note that the registration secret ends up in the nix store and therefore is world-readable
152+ by any user on your machine, so it makes sense to only temporarily activate the
153+ <option>registration_shared_secret</option> option until a better solution for NixOS is in place.
154+ </para>
155+ </section>
156+
157+ <section xml:id="module-services-matrix-riot-web">
158+ <title>Riot Web Client</title>
159+ <para>
160+ <link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link>
161+ is the reference web client for Matrix and developed by the core team at matrix.org.
162+ The following snippet can be optionally added to the code before to complete the synapse
163+ installation with a web client served at
164+ <code>https://riot.myhostname.example.org</code> and <code>https://riot.example.org</code>.
165+ Alternatively, you can use the hosted copy at
166+ <link xlink:href="https://riot.im/app">https://riot.im/app</link>,
167+ or use other web clients or native client applications.
168+ Due to the <literal>/.well-known</literal> urls set up done above,
169+ many clients should fill in the required connection details automatically
170+ when you enter your Matrix Identifier.
171+ See <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try Matrix Now!</link>
172+ for a list of existing clients and their supported featureset.
173+
174+ <programlisting>
175+ services.nginx.virtualHosts."riot.${fqdn}" = {
176+ enableACME = true;
177+ forceSSL = true;
178+ serverAliases = [
179+ "riot.${config.networking.domain}"
180+ ];
181+
182+ root = pkgs.riot-web;
183+ };
184+ </programlisting>
185+ </para>
186+ <para>
187+ Note that the Riot developers do not recommend running Riot and your Matrix homeserver
188+ on the same fully-qualified domain name for security reasons.
189+ In the example, this means that you should not reuse the <literal>myhostname.example.org</literal>
190+ virtualHost to also serve Riot, but instead serve it on a different subdomain,
191+ like <literal>riot.example.org</literal> in the example.
192+ See the
193+ <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot Important Security Notes</link>
194+ for more information on this subject.
195+ </para>
196+ </section>
197+</chapter>
nixos/doc/manual/release-notes/rl-1903.xml+11
@@ -417,6 +417,8 @@
417417 and will be <link xlink:href="https://matrix.org/blog/2019/02/05/synapse-0-99-0/">the last version to accept self-signed certificates</link>.
418418 As such, it is now recommended to use a proper certificate verified by a
419419 root CA (for example Let's Encrypt).
420+ The new <link linkend="module-services-matrix">manual chapter on Matrix</link> contains a working example of using nginx as a reverse proxy
421+ in front of <literal>matrix-synapse</literal>, using Let's Encrypt certificates.
420422 </para>
421423 </listitem>
422424 <listitem>
@@ -496,6 +498,15 @@
496498 of maintainers.
497499 </para>
498500 </listitem>
501+ <listitem>
502+ <para>
503+ The manual gained a
504+ <link linkend="module-services-matrix">
505+ new chapter on self-hosting <literal>matrix-synapse</literal> and <literal>riot-web</literal>
506+ </link>, the most prevalent server and client implementations for the
507+ <link xlink:href="https://matrix.org/">Matrix</link> federated communication network.
508+ </para>
509+ </listitem>
499510 <listitem>
500511 <para>
501512 The astah-community package was removed from nixpkgs due to it being discontinued and the downloads not being available anymore.