nixos/synapse: convert manual chapter to MD
This commit is contained in:
parent
078707524e
commit
ad540ad4a5
216
nixos/modules/services/matrix/synapse.md
Normal file
216
nixos/modules/services/matrix/synapse.md
Normal file
@ -0,0 +1,216 @@
|
||||
# Matrix {#module-services-matrix}
|
||||
|
||||
[Matrix](https://matrix.org/) 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.
|
||||
|
||||
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
|
||||
[Try Matrix Now!](https://matrix.org/docs/projects/try-matrix-now.html)
|
||||
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.
|
||||
|
||||
## Synapse Homeserver {#module-services-matrix-synapse}
|
||||
|
||||
[Synapse](https://github.com/matrix-org/synapse) 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 `example.org` domain, served from
|
||||
the host `myhostname.example.org`. For more information,
|
||||
please refer to the
|
||||
[installation instructions of Synapse](https://matrix-org.github.io/synapse/latest/setup/installation.html) .
|
||||
```
|
||||
{ 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;
|
||||
} ];
|
||||
}
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Registering Matrix users {#module-services-matrix-register-users}
|
||||
|
||||
If you want to run a server with public registration by anybody, you can
|
||||
then enable `services.matrix-synapse.settings.enable_registration = true;`.
|
||||
Otherwise, or you can generate a registration secret with
|
||||
{command}`pwgen -s 64 1` and set it with
|
||||
[](#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:
|
||||
```ShellSession
|
||||
$ 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!
|
||||
```
|
||||
In the example, this would create a user with the Matrix Identifier
|
||||
`@your-username:example.org`.
|
||||
|
||||
::: {.warning}
|
||||
When using [](#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:
|
||||
|
||||
- Create a file with the following contents:
|
||||
|
||||
```
|
||||
registration_shared_secret: your-very-secret-secret
|
||||
```
|
||||
- Deploy the file with a secret-manager such as
|
||||
[{option}`deployment.keys`](https://nixops.readthedocs.io/en/latest/overview.html#managing-keys)
|
||||
from {manpage}`nixops(1)` or [sops-nix](https://github.com/Mic92/sops-nix/) to
|
||||
e.g. {file}`/run/secrets/matrix-shared-secret` and ensure that it's readable
|
||||
by `matrix-synapse`.
|
||||
- Include the file like this in your configuration:
|
||||
|
||||
```
|
||||
{
|
||||
services.matrix-synapse.extraConfigFiles = [
|
||||
"/run/secrets/matrix-shared-secret"
|
||||
];
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
::: {.note}
|
||||
It's also possible to user alternative authentication mechanism such as
|
||||
[LDAP (via `matrix-synapse-ldap3`)](https://github.com/matrix-org/matrix-synapse-ldap3)
|
||||
or [OpenID](https://matrix-org.github.io/synapse/latest/openid.html).
|
||||
:::
|
||||
|
||||
## Element (formerly known as Riot) Web Client {#module-services-matrix-element-web}
|
||||
|
||||
[Element Web](https://github.com/vector-im/riot-web/) 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
|
||||
[Element introductory blog post](https://element.io/blog/welcome-to-element/)
|
||||
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
|
||||
`https://element.myhostname.example.org` and
|
||||
`https://element.example.org`. Alternatively, you can use the hosted
|
||||
copy at <https://app.element.io/>,
|
||||
or use other web clients or native client applications. Due to the
|
||||
`/.well-known` urls set up done above, many clients should
|
||||
fill in the required connection details automatically when you enter your
|
||||
Matrix Identifier. See
|
||||
[Try Matrix Now!](https://matrix.org/docs/projects/try-matrix-now.html)
|
||||
for a list of existing clients and their supported featureset.
|
||||
```
|
||||
{
|
||||
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.
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
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
|
||||
`myhostname.example.org` virtualHost to also serve Element,
|
||||
but instead serve it on a different subdomain, like
|
||||
`element.example.org` in the example. See the
|
||||
[Element Important Security Notes](https://github.com/vector-im/element-web/tree/v1.10.0#important-security-notes)
|
||||
for more information on this subject.
|
||||
:::
|
@ -801,6 +801,8 @@ in {
|
||||
|
||||
meta = {
|
||||
buildDocsInSandbox = false;
|
||||
# Don't edit the docbook xml directly, edit the md and generate it:
|
||||
# `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`
|
||||
doc = ./synapse.xml;
|
||||
maintainers = teams.matrix.members;
|
||||
};
|
||||
|
@ -1,63 +1,61 @@
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
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>
|
||||
|
||||
<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://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>.
|
||||
<programlisting>
|
||||
<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}";
|
||||
fqdn = "${config.networking.hostName}.${config.networking.domain}";
|
||||
clientConfig = {
|
||||
"m.homeserver".base_url = "https://${fqdn}";
|
||||
"m.identity_server" = {};
|
||||
"m.homeserver".base_url = "https://${fqdn}";
|
||||
"m.identity_server" = {};
|
||||
};
|
||||
serverConfig."m.server" = "${config.services.matrix-synapse.settings.server_name}:443";
|
||||
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.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"
|
||||
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";
|
||||
LC_COLLATE = "C"
|
||||
LC_CTYPE = "C";
|
||||
'';
|
||||
|
||||
services.nginx = {
|
||||
@ -74,7 +72,7 @@ in {
|
||||
# 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}" = {
|
||||
"${config.networking.domain}" = {
|
||||
enableACME = true;
|
||||
forceSSL = true;
|
||||
# This section is not needed if the server_name of matrix-synapse is equal to
|
||||
@ -82,26 +80,26 @@ in {
|
||||
# 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;
|
||||
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;
|
||||
locations."= /.well-known/matrix/client".extraConfig = mkWellKnown clientConfig;
|
||||
};
|
||||
"${fqdn}" = {
|
||||
"${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 = ''
|
||||
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";
|
||||
locations."/_matrix".proxyPass = "http://[::1]:8008";
|
||||
# Forward requests for e.g. SSO and password-resets.
|
||||
locations."/_synapse/client".proxyPass = "http://[::1]:8008";
|
||||
locations."/_synapse/client".proxyPass = "http://[::1]:8008";
|
||||
};
|
||||
};
|
||||
};
|
||||
@ -111,12 +109,12 @@ in {
|
||||
settings.server_name = config.networking.domain;
|
||||
settings.listeners = [
|
||||
{ port = 8008;
|
||||
bind_addresses = [ "::1" ];
|
||||
type = "http";
|
||||
bind_addresses = [ "::1" ];
|
||||
type = "http";
|
||||
tls = false;
|
||||
x_forwarded = true;
|
||||
resources = [ {
|
||||
names = [ "client" "federation" ];
|
||||
names = [ "client" "federation" ];
|
||||
compress = true;
|
||||
} ];
|
||||
}
|
||||
@ -124,103 +122,117 @@ in {
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</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
|
||||
<option><link linkend="opt-services.matrix-synapse.settings.registration_shared_secret">services.matrix-synapse.settings.registration_shared_secret</link></option>.
|
||||
To create a new user or admin, run the following after you have set the secret
|
||||
and have rebuilt NixOS:
|
||||
<screen>
|
||||
<prompt>$ </prompt>nix-shell -p matrix-synapse
|
||||
<prompt>$ </prompt>register_new_matrix_user -k your-registration-shared-secret http://localhost:8008
|
||||
<prompt>New user localpart: </prompt>your-username
|
||||
<prompt>Password:</prompt>
|
||||
<prompt>Confirm password:</prompt>
|
||||
<prompt>Make admin [no]:</prompt>
|
||||
Success!
|
||||
</screen>
|
||||
In the example, this would create a user with the Matrix Identifier
|
||||
<literal>@your-username:example.org</literal>.
|
||||
<warning>
|
||||
</section>
|
||||
<section xml:id="module-services-matrix-register-users">
|
||||
<title>Registering Matrix users</title>
|
||||
<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:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Create a file with the following contents:
|
||||
<programlisting>
|
||||
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"></xref>.
|
||||
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"></xref>,
|
||||
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>
|
||||
</para>
|
||||
</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:
|
||||
<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"
|
||||
"/run/secrets/matrix-shared-secret"
|
||||
];
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</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/" role="uri">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>
|
||||
</warning>
|
||||
</para>
|
||||
<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.
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
{
|
||||
services.nginx.virtualHosts."element.${fqdn}" = {
|
||||
services.nginx.virtualHosts."element.${fqdn}" = {
|
||||
enableACME = true;
|
||||
forceSSL = true;
|
||||
serverAliases = [
|
||||
"element.${config.networking.domain}"
|
||||
"element.${config.networking.domain}"
|
||||
];
|
||||
|
||||
root = pkgs.element-web.override {
|
||||
@ -231,19 +243,19 @@ registration_shared_secret: your-very-secret-secret
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
Loading…
Reference in New Issue
Block a user