pyrox.dev
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> is an open standard for
9 interoperable, decentralised, real-time communication over IP. It can be used
10 to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things
11 communication - or anywhere you need a standard HTTP API for publishing and
12 subscribing to data whilst tracking the conversation history.
13 </para>
14 <para>
15 This chapter will show you how to set up your own, self-hosted Matrix
16 homeserver using the Synapse reference homeserver, and how to serve your own
17 copy of the Element web client. See the
18 <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try
19 Matrix Now!</link> overview page for links to Element Apps for Android and iOS,
20 desktop clients, as well as bridges to other networks and other projects
21 around Matrix.
22 </para>
23 <section xml:id="module-services-matrix-synapse">
24 <title>Synapse Homeserver</title>
25
26 <para>
27 <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> is
28 the reference homeserver implementation of Matrix from the core development
29 team at matrix.org. The following configuration example will set up a
30 synapse server for the <literal>example.org</literal> domain, served from
31 the host <literal>myhostname.example.org</literal>. For more information,
32 please refer to the
33 <link xlink:href="https://matrix-org.github.io/synapse/latest/setup/installation.html">
34 installation instructions of Synapse </link>.
35<programlisting>
36{ pkgs, lib, config, ... }:
37let
38 fqdn = "${config.networking.hostName}.${config.networking.domain}";
39 clientConfig = {
40 "m.homeserver".base_url = "https://${fqdn}";
41 "m.identity_server" = {};
42 };
43 serverConfig."m.server" = "${config.services.matrix-synapse.settings.server_name}:443";
44 mkWellKnown = data: ''
45 add_header Content-Type application/json;
46 add_header Access-Control-Allow-Origin *;
47 return 200 '${builtins.toJSON data}';
48 '';
49in {
50 <xref linkend="opt-networking.hostName" /> = "myhostname";
51 <xref linkend="opt-networking.domain" /> = "example.org";
52 <xref linkend="opt-networking.firewall.allowedTCPPorts" /> = [ 80 443 ];
53
54 <xref linkend="opt-services.postgresql.enable" /> = true;
55 <xref linkend="opt-services.postgresql.initialScript" /> = pkgs.writeText "synapse-init.sql" ''
56 CREATE ROLE "matrix-synapse" WITH LOGIN PASSWORD 'synapse';
57 CREATE DATABASE "matrix-synapse" WITH OWNER "matrix-synapse"
58 TEMPLATE template0
59 LC_COLLATE = "C"
60 LC_CTYPE = "C";
61 '';
62
63 services.nginx = {
64 <link linkend="opt-services.nginx.enable">enable</link> = true;
65 <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
66 <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
67 <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
68 <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
69 <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
70 "${config.networking.domain}" = { <co xml:id='ex-matrix-synapse-dns' />
71 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
72 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
73 <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' />
74 <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' />
75 };
76 "${fqdn}" = {
77 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
78 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
79 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."/".extraConfig</link> = '' <co xml:id='ex-matrix-synapse-rev-default' />
80 return 404;
81 '';
82 <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' />
83 <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' />
84 };
85 };
86 };
87
88 services.matrix-synapse = {
89 <link linkend="opt-services.matrix-synapse.enable">enable</link> = true;
90 <link linkend="opt-services.matrix-synapse.settings.server_name">settings.server_name</link> = config.networking.domain;
91 <link linkend="opt-services.matrix-synapse.settings.listeners">settings.listeners</link> = [
92 { <link linkend="opt-services.matrix-synapse.settings.listeners._.port">port</link> = 8008;
93 <link linkend="opt-services.matrix-synapse.settings.listeners._.bind_addresses">bind_addresses</link> = [ "::1" ];
94 <link linkend="opt-services.matrix-synapse.settings.listeners._.type">type</link> = "http";
95 <link linkend="opt-services.matrix-synapse.settings.listeners._.tls">tls</link> = false;
96 <link linkend="opt-services.matrix-synapse.settings.listeners._.x_forwarded">x_forwarded</link> = true;
97 <link linkend="opt-services.matrix-synapse.settings.listeners._.resources">resources</link> = [ {
98 <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.names">names</link> = [ "client" "federation" ];
99 <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.compress">compress</link> = true;
100 } ];
101 }
102 ];
103 };
104}
105</programlisting>
106 </para>
107 <calloutlist>
108 <callout arearefs='ex-matrix-synapse-dns'>
109 <para>
110 If the <code>A</code> and <code>AAAA</code> DNS records on
111 <literal>example.org</literal> do not point on the same host as the records
112 for <code>myhostname.example.org</code>, you can easily move the
113 <code>/.well-known</code> virtualHost section of the code to the host that
114 is serving <literal>example.org</literal>, while the rest stays on
115 <literal>myhostname.example.org</literal> with no other changes required.
116 This pattern also allows to seamlessly move the homeserver from
117 <literal>myhostname.example.org</literal> to
118 <literal>myotherhost.example.org</literal> by only changing the
119 <code>/.well-known</code> redirection target.
120 </para>
121 </callout>
122 <callout arearefs='ex-matrix-synapse-well-known-server'>
123 <para>
124 This section is not needed if the <link linkend="opt-services.matrix-synapse.settings.server_name">server_name</link>
125 of <package>matrix-synapse</package> is equal to the domain (i.e.
126 <literal>example.org</literal> from <literal>@foo:example.org</literal>)
127 and the federation port is 8448.
128 Further reference can be found in the <link xlink:href="https://matrix-org.github.io/synapse/latest/delegate.html">docs
129 about delegation</link>.
130 </para>
131 </callout>
132 <callout arearefs='ex-matrix-synapse-well-known-client'>
133 <para>
134 This is usually needed for homeserver discovery (from e.g. other Matrix clients).
135 Further reference can be found in the <link xlink:href="https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient">upstream docs</link>
136 </para>
137 </callout>
138 <callout arearefs='ex-matrix-synapse-rev-default'>
139 <para>
140 It's also possible to do a redirect here or something else, this vhost is not
141 needed for Matrix. It's recommended though to <emphasis>not put</emphasis> element
142 here, see also the <link linkend='ex-matrix-synapse-rev-default'>section about Element</link>.
143 </para>
144 </callout>
145 <callout arearefs='ex-matrix-synapse-rev-proxy-pass'>
146 <para>
147 Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash
148 <emphasis>must not</emphasis> be used here.
149 </para>
150 </callout>
151 <callout arearefs='ex-matrix-synapse-rev-client'>
152 <para>
153 Forward requests for e.g. SSO and password-resets.
154 </para>
155 </callout>
156 </calloutlist>
157 </section>
158 <section xml:id="module-services-matrix-register-users">
159 <title>Registering Matrix users</title>
160 <para>
161 If you want to run a server with public registration by anybody, you can
162 then enable <literal><link linkend="opt-services.matrix-synapse.settings.enable_registration">services.matrix-synapse.settings.enable_registration</link> =
163 true;</literal>. Otherwise, or you can generate a registration secret with
164 <command>pwgen -s 64 1</command> and set it with
165 <option><link linkend="opt-services.matrix-synapse.settings.registration_shared_secret">services.matrix-synapse.settings.registration_shared_secret</link></option>.
166 To create a new user or admin, run the following after you have set the secret
167 and have rebuilt NixOS:
168<screen>
169<prompt>$ </prompt>nix-shell -p matrix-synapse
170<prompt>$ </prompt>register_new_matrix_user -k <replaceable>your-registration-shared-secret</replaceable> http://localhost:8008
171<prompt>New user localpart: </prompt><replaceable>your-username</replaceable>
172<prompt>Password:</prompt>
173<prompt>Confirm password:</prompt>
174<prompt>Make admin [no]:</prompt>
175Success!
176</screen>
177 In the example, this would create a user with the Matrix Identifier
178 <literal>@your-username:example.org</literal>.
179 <warning>
180 <para>
181 When using <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />, the secret
182 will end up in the world-readable store. Instead it's recommended to deploy the secret
183 in an additional file like this:
184 <itemizedlist>
185 <listitem>
186 <para>
187 Create a file with the following contents:
188<programlisting>registration_shared_secret: your-very-secret-secret</programlisting>
189 </para>
190 </listitem>
191 <listitem>
192 <para>
193 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>
194 from <citerefentry><refentrytitle>nixops</refentrytitle><manvolnum>1</manvolnum></citerefentry>
195 or <link xlink:href="https://github.com/Mic92/sops-nix/">sops-nix</link> to
196 e.g. <filename>/run/secrets/matrix-shared-secret</filename> and ensure that it's readable
197 by <package>matrix-synapse</package>.
198 </para>
199 </listitem>
200 <listitem>
201 <para>
202 Include the file like this in your configuration:
203<programlisting>
204{
205 <xref linkend="opt-services.matrix-synapse.extraConfigFiles" /> = [
206 "/run/secrets/matrix-shared-secret"
207 ];
208}
209</programlisting>
210 </para>
211 </listitem>
212 </itemizedlist>
213 </para>
214 </warning>
215 </para>
216 <note>
217 <para>
218 It's also possible to user alternative authentication mechanism such as
219 <link xlink:href="https://github.com/matrix-org/matrix-synapse-ldap3">LDAP (via <literal>matrix-synapse-ldap3</literal>)</link>
220 or <link xlink:href="https://matrix-org.github.io/synapse/latest/openid.html">OpenID</link>.
221 </para>
222 </note>
223 </section>
224 <section xml:id="module-services-matrix-element-web">
225 <title>Element (formerly known as Riot) Web Client</title>
226
227 <para>
228 <link xlink:href="https://github.com/vector-im/riot-web/">Element Web</link> is
229 the reference web client for Matrix and developed by the core team at
230 matrix.org. Element was formerly known as Riot.im, see the
231 <link xlink:href="https://element.io/blog/welcome-to-element/">Element introductory blog post</link>
232 for more information. The following snippet can be optionally added to the code before
233 to complete the synapse installation with a web client served at
234 <code>https://element.myhostname.example.org</code> and
235 <code>https://element.example.org</code>. Alternatively, you can use the hosted
236 copy at <link xlink:href="https://app.element.io/">https://app.element.io/</link>,
237 or use other web clients or native client applications. Due to the
238 <literal>/.well-known</literal> urls set up done above, many clients should
239 fill in the required connection details automatically when you enter your
240 Matrix Identifier. See
241 <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try
242 Matrix Now!</link> for a list of existing clients and their supported
243 featureset.
244<programlisting>
245{
246 services.nginx.virtualHosts."element.${fqdn}" = {
247 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
248 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
249 <link linkend="opt-services.nginx.virtualHosts._name_.serverAliases">serverAliases</link> = [
250 "element.${config.networking.domain}"
251 ];
252
253 <link linkend="opt-services.nginx.virtualHosts._name_.root">root</link> = pkgs.element-web.override {
254 conf = {
255 default_server_config = clientConfig; # see `clientConfig` from the snippet above.
256 };
257 };
258 };
259}
260</programlisting>
261 </para>
262
263 <note>
264 <para>
265 The Element developers do not recommend running Element and your Matrix
266 homeserver on the same fully-qualified domain name for security reasons. In
267 the example, this means that you should not reuse the
268 <literal>myhostname.example.org</literal> virtualHost to also serve Element,
269 but instead serve it on a different subdomain, like
270 <literal>element.example.org</literal> in the example. See the
271 <link xlink:href="https://github.com/vector-im/element-web/tree/v1.10.0#important-security-notes">Element
272 Important Security Notes</link> for more information on this subject.
273 </para>
274 </note>
275 </section>
276</chapter>