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://github.com/matrix-org/synapse#synapse-installation">
34 installation instructions of Synapse </link>.
35<programlisting>
36{ pkgs, lib, ... }:
37let
38 fqdn =
39 let
40 join = hostName: domain: hostName + lib.optionalString (domain != null) ".${domain}";
41 in join config.networking.hostName config.networking.domain;
42in {
43 networking = {
44 <link linkend="opt-networking.hostName">hostName</link> = "myhostname";
45 <link linkend="opt-networking.domain">domain</link> = "example.org";
46 };
47 <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ];
48
49 <link linkend="opt-services.postgresql.enable">services.postgresql.enable</link> = true;
50 <link linkend="opt-services.postgresql.initialScript">services.postgresql.initialScript</link> = pkgs.writeText "synapse-init.sql" ''
51 CREATE ROLE "matrix-synapse" WITH LOGIN PASSWORD 'synapse';
52 CREATE DATABASE "matrix-synapse" WITH OWNER "matrix-synapse"
53 TEMPLATE template0
54 LC_COLLATE = "C"
55 LC_CTYPE = "C";
56 '';
57
58 services.nginx = {
59 <link linkend="opt-services.nginx.enable">enable</link> = true;
60 # only recommendedProxySettings and recommendedGzipSettings are strictly required,
61 # but the rest make sense as well
62 <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
63 <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
64 <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
65 <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
66
67 <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
68 # This host section can be placed on a different host than the rest,
69 # i.e. to delegate from the host being accessible as ${config.networking.domain}
70 # to another host actually running the Matrix homeserver.
71 "${config.networking.domain}" = {
72 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
73 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
74
75 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/server".extraConfig</link> =
76 let
77 # use 443 instead of the default 8448 port to unite
78 # the client-server and server-server port for simplicity
79 server = { "m.server" = "${fqdn}:443"; };
80 in ''
81 add_header Content-Type application/json;
82 return 200 '${builtins.toJSON server}';
83 '';
84 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/client".extraConfig</link> =
85 let
86 client = {
87 "m.homeserver" = { "base_url" = "https://${fqdn}"; };
88 "m.identity_server" = { "base_url" = "https://vector.im"; };
89 };
90 # ACAO required to allow element-web on any URL to request this json file
91 in ''
92 add_header Content-Type application/json;
93 add_header Access-Control-Allow-Origin *;
94 return 200 '${builtins.toJSON client}';
95 '';
96 };
97
98 # Reverse proxy for Matrix client-server and server-server communication
99 ${fqdn} = {
100 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
101 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
102
103 # Or do a redirect instead of the 404, or whatever is appropriate for you.
104 # But do not put a Matrix Web client here! See the Element web section below.
105 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."/".extraConfig</link> = ''
106 return 404;
107 '';
108
109 # forward all Matrix API calls to the synapse Matrix homeserver
110 locations."/_matrix" = {
111 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">proxyPass</link> = "http://[::1]:8008"; # without a trailing /
112 };
113 };
114 };
115 };
116 services.matrix-synapse = {
117 <link linkend="opt-services.matrix-synapse.enable">enable</link> = true;
118 <link linkend="opt-services.matrix-synapse.server_name">server_name</link> = config.networking.domain;
119 <link linkend="opt-services.matrix-synapse.listeners">listeners</link> = [
120 {
121 <link linkend="opt-services.matrix-synapse.listeners._.port">port</link> = 8008;
122 <link linkend="opt-services.matrix-synapse.listeners._.bind_address">bind_address</link> = "::1";
123 <link linkend="opt-services.matrix-synapse.listeners._.type">type</link> = "http";
124 <link linkend="opt-services.matrix-synapse.listeners._.tls">tls</link> = false;
125 <link linkend="opt-services.matrix-synapse.listeners._.x_forwarded">x_forwarded</link> = true;
126 <link linkend="opt-services.matrix-synapse.listeners._.resources">resources</link> = [
127 {
128 <link linkend="opt-services.matrix-synapse.listeners._.resources._.names">names</link> = [ "client" "federation" ];
129 <link linkend="opt-services.matrix-synapse.listeners._.resources._.compress">compress</link> = false;
130 }
131 ];
132 }
133 ];
134 };
135}
136</programlisting>
137 </para>
138
139 <para>
140 If the <code>A</code> and <code>AAAA</code> DNS records on
141 <literal>example.org</literal> do not point on the same host as the records
142 for <code>myhostname.example.org</code>, you can easily move the
143 <code>/.well-known</code> virtualHost section of the code to the host that
144 is serving <literal>example.org</literal>, while the rest stays on
145 <literal>myhostname.example.org</literal> with no other changes required.
146 This pattern also allows to seamlessly move the homeserver from
147 <literal>myhostname.example.org</literal> to
148 <literal>myotherhost.example.org</literal> by only changing the
149 <code>/.well-known</code> redirection target.
150 </para>
151
152 <para>
153 If you want to run a server with public registration by anybody, you can
154 then enable <literal><link linkend="opt-services.matrix-synapse.enable_registration">services.matrix-synapse.enable_registration</link> =
155 true;</literal>. Otherwise, or you can generate a registration secret with
156 <command>pwgen -s 64 1</command> and set it with
157 <option><link linkend="opt-services.matrix-synapse.registration_shared_secret">services.matrix-synapse.registration_shared_secret</link></option>. To
158 create a new user or admin, run the following after you have set the secret
159 and have rebuilt NixOS:
160<screen>
161<prompt>$ </prompt>nix run nixpkgs.matrix-synapse
162<prompt>$ </prompt>register_new_matrix_user -k <replaceable>your-registration-shared-secret</replaceable> http://localhost:8008
163<prompt>New user localpart: </prompt><replaceable>your-username</replaceable>
164<prompt>Password:</prompt>
165<prompt>Confirm password:</prompt>
166<prompt>Make admin [no]:</prompt>
167Success!
168</screen>
169 In the example, this would create a user with the Matrix Identifier
170 <literal>@your-username:example.org</literal>. Note that the registration
171 secret ends up in the nix store and therefore is world-readable by any user
172 on your machine, so it makes sense to only temporarily activate the
173 <link linkend="opt-services.matrix-synapse.registration_shared_secret">registration_shared_secret</link>
174 option until a better solution for NixOS is in place.
175 </para>
176 </section>
177 <section xml:id="module-services-matrix-element-web">
178 <title>Element (formerly known as Riot) Web Client</title>
179
180 <para>
181 <link xlink:href="https://github.com/vector-im/riot-web/">Element Web</link> is
182 the reference web client for Matrix and developed by the core team at
183 matrix.org. Element was formerly known as Riot.im, see the
184 <link xlink:href="https://element.io/blog/welcome-to-element/">Element introductory blog post</link>
185 for more information. The following snippet can be optionally added to the code before
186 to complete the synapse installation with a web client served at
187 <code>https://element.myhostname.example.org</code> and
188 <code>https://element.example.org</code>. Alternatively, you can use the hosted
189 copy at <link xlink:href="https://app.element.io/">https://app.element.io/</link>,
190 or use other web clients or native client applications. Due to the
191 <literal>/.well-known</literal> urls set up done above, many clients should
192 fill in the required connection details automatically when you enter your
193 Matrix Identifier. See
194 <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try
195 Matrix Now!</link> for a list of existing clients and their supported
196 featureset.
197<programlisting>
198{
199 services.nginx.virtualHosts."element.${fqdn}" = {
200 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
201 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
202 <link linkend="opt-services.nginx.virtualHosts._name_.serverAliases">serverAliases</link> = [
203 "element.${config.networking.domain}"
204 ];
205
206 <link linkend="opt-services.nginx.virtualHosts._name_.root">root</link> = pkgs.element-web.override {
207 conf = {
208 default_server_config."m.homeserver" = {
209 "base_url" = "https://${fqdn}";
210 "server_name" = "${fqdn}";
211 };
212 };
213 };
214 };
215}
216</programlisting>
217 </para>
218
219 <para>
220 Note that the Element developers do not recommend running Element and your Matrix
221 homeserver on the same fully-qualified domain name for security reasons. In
222 the example, this means that you should not reuse the
223 <literal>myhostname.example.org</literal> virtualHost to also serve Element,
224 but instead serve it on a different subdomain, like
225 <literal>element.example.org</literal> in the example. See the
226 <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Element
227 Important Security Notes</link> for more information on this subject.
228 </para>
229 </section>
230</chapter>