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