nixos/matrix: add manual section
about self-hosting a matrix client and server
This commit is contained in:
parent
b60b304cef
commit
ef52869ef1
|
@ -21,6 +21,7 @@
|
||||||
<xi:include href="xfce.xml" />
|
<xi:include href="xfce.xml" />
|
||||||
<xi:include href="networking.xml" />
|
<xi:include href="networking.xml" />
|
||||||
<xi:include href="linux-kernel.xml" />
|
<xi:include href="linux-kernel.xml" />
|
||||||
|
<xi:include href="matrix.xml" />
|
||||||
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
||||||
<xi:include href="profiles.xml" />
|
<xi:include href="profiles.xml" />
|
||||||
<!-- Apache; libvirtd virtualisation -->
|
<!-- Apache; libvirtd virtualisation -->
|
||||||
|
|
197
nixos/doc/manual/configuration/matrix.xml
Normal file
197
nixos/doc/manual/configuration/matrix.xml
Normal file
|
@ -0,0 +1,197 @@
|
||||||
|
<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 Riot 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 Riot 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://github.com/matrix-org/synapse#synapse-installation">
|
||||||
|
installation instructions of Synapse
|
||||||
|
</link>.
|
||||||
|
<programlisting>
|
||||||
|
let
|
||||||
|
fqdn =
|
||||||
|
let
|
||||||
|
join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
|
||||||
|
in join config.networking.hostName config.networking.domain;
|
||||||
|
in {
|
||||||
|
networking = {
|
||||||
|
hostName = "myhostname";
|
||||||
|
domain = "example.org";
|
||||||
|
};
|
||||||
|
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
||||||
|
|
||||||
|
services.nginx = {
|
||||||
|
enable = true;
|
||||||
|
# only recommendedProxySettings and recommendedGzipSettings are strictly required,
|
||||||
|
# but the rest make sense as well
|
||||||
|
recommendedTlsSettings = true;
|
||||||
|
recommendedOptimisation = true;
|
||||||
|
recommendedGzipSettings = true;
|
||||||
|
recommendedProxySettings = true;
|
||||||
|
|
||||||
|
virtualHosts = {
|
||||||
|
# This host section can be placed on a different host than the rest,
|
||||||
|
# i.e. to delegate from the host being accessible as ${config.networking.domain}
|
||||||
|
# to another host actually running the Matrix homeserver.
|
||||||
|
"${config.networking.domain}" = {
|
||||||
|
locations."= /.well-known/matrix/server".extraConfig =
|
||||||
|
let
|
||||||
|
# use 443 instead of the default 8448 port to unite
|
||||||
|
# the client-server and server-server port for simplicity
|
||||||
|
server = { "m.server" = "${fqdn}:443"; };
|
||||||
|
in ''
|
||||||
|
add_header Content-Type application/json;
|
||||||
|
return 200 '${builtins.toJSON server}';
|
||||||
|
'';
|
||||||
|
locations."= /.well-known/matrix/client".extraConfig =
|
||||||
|
let
|
||||||
|
client = {
|
||||||
|
"m.homeserver" = { "base_url" = "https://${fqdn}"; };
|
||||||
|
"m.identity_server" = { "base_url" = "https://vector.im"; };
|
||||||
|
};
|
||||||
|
# ACAO required to allow riot-web on any URL to request this json file
|
||||||
|
in ''
|
||||||
|
add_header Content-Type application/json;
|
||||||
|
add_header Access-Control-Allow-Origin *;
|
||||||
|
return 200 '${builtins.toJSON client}';
|
||||||
|
'';
|
||||||
|
};
|
||||||
|
|
||||||
|
# Reverse proxy for Matrix client-server and server-server communication
|
||||||
|
${fqdn} = {
|
||||||
|
enableACME = true;
|
||||||
|
forceSSL = true;
|
||||||
|
|
||||||
|
# Or do a redirect instead of the 404, or whatever is appropriate for you.
|
||||||
|
# But do not put a Matrix Web client here! See the Riot Web section below.
|
||||||
|
locations."/".extraConfig = ''
|
||||||
|
return 404;
|
||||||
|
'';
|
||||||
|
|
||||||
|
# forward all Matrix API calls to the synapse Matrix homeserver
|
||||||
|
locations."/_matrix" = {
|
||||||
|
proxyPass = "http://[::1]:8008";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
services.matrix-synapse = {
|
||||||
|
enable = true;
|
||||||
|
server_name = config.networking.domain;
|
||||||
|
listeners = [
|
||||||
|
{
|
||||||
|
port = 8008;
|
||||||
|
bind_address = "::1";
|
||||||
|
type = "http";
|
||||||
|
tls = false;
|
||||||
|
x_forwarded = true;
|
||||||
|
resources = [
|
||||||
|
{ names = [ "client" "federation" ]; compress = false; }
|
||||||
|
];
|
||||||
|
}
|
||||||
|
];
|
||||||
|
};
|
||||||
|
};
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If the <code>A</code> and <code>AAAA</code> DNS records on <literal>example.org</literal>
|
||||||
|
do not point on the same host as the records for <code>myhostname.example.org</code>,
|
||||||
|
you can easily move the <code>/.well-known</code> virtualHost section of the code
|
||||||
|
to the host that is serving <literal>example.org</literal>,
|
||||||
|
while the rest stays on <literal>myhostname.example.org</literal>
|
||||||
|
with no other changes required.
|
||||||
|
This pattern also allows to seamlessly move the homeserver from <literal>myhostname.example.org</literal>
|
||||||
|
to <literal>myotherhost.example.org</literal> by only changing the <code>/.well-known</code> redirection target.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you want to run a server with public registration by anybody,
|
||||||
|
you can then enable
|
||||||
|
<option>services.matrix-synapse.enable_registration = true;</option>.
|
||||||
|
Otherwise, or you can generate a registration secret with <command>pwgen -s 64 1</command>
|
||||||
|
and set it with
|
||||||
|
<option>services.matrix-synapse.registration_shared_secret</option>.
|
||||||
|
To create a new user or admin,
|
||||||
|
run the following after you have set the secret and have rebuilt NixOS:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
$ nix run nixpkgs.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>
|
||||||
|
In the example, this would create a user with the Matrix Identifier
|
||||||
|
<literal>@your-username:example.org</literal>.
|
||||||
|
Note that the registration secret ends up in the nix store and therefore is world-readable
|
||||||
|
by any user on your machine, so it makes sense to only temporarily activate the
|
||||||
|
<option>registration_shared_secret</option> option until a better solution for NixOS is in place.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="module-services-matrix-riot-web">
|
||||||
|
<title>Riot Web Client</title>
|
||||||
|
<para>
|
||||||
|
<link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link>
|
||||||
|
is the reference web client for Matrix and developed by the core team at matrix.org.
|
||||||
|
The following snippet can be optionally added to the code before to complete the synapse
|
||||||
|
installation with a web client served at
|
||||||
|
<code>https://riot.myhostname.example.org</code> and <code>https://riot.example.org</code>.
|
||||||
|
Alternatively, you can use the hosted copy at
|
||||||
|
<link xlink:href="https://riot.im/app">https://riot.im/app</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>
|
||||||
|
services.nginx.virtualHosts."riot.${fqdn}" = {
|
||||||
|
enableACME = true;
|
||||||
|
forceSSL = true;
|
||||||
|
serverAliases = [
|
||||||
|
"riot.${config.networking.domain}"
|
||||||
|
];
|
||||||
|
|
||||||
|
root = pkgs.riot-web;
|
||||||
|
};
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Note that the Riot developers do not recommend running Riot 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 Riot, but instead serve it on a different subdomain,
|
||||||
|
like <literal>riot.example.org</literal> in the example.
|
||||||
|
See the
|
||||||
|
<link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot Important Security Notes</link>
|
||||||
|
for more information on this subject.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</chapter>
|
|
@ -417,6 +417,8 @@
|
||||||
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>.
|
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>.
|
||||||
As such, it is now recommended to use a proper certificate verified by a
|
As such, it is now recommended to use a proper certificate verified by a
|
||||||
root CA (for example Let's Encrypt).
|
root CA (for example Let's Encrypt).
|
||||||
|
The new <link linkend="module-services-matrix">manual chapter on Matrix</link> contains a working example of using nginx as a reverse proxy
|
||||||
|
in front of <literal>matrix-synapse</literal>, using Let's Encrypt certificates.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
|
@ -496,6 +498,15 @@
|
||||||
of maintainers.
|
of maintainers.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The manual gained a
|
||||||
|
<link linkend="module-services-matrix">
|
||||||
|
new chapter on self-hosting <literal>matrix-synapse</literal> and <literal>riot-web</literal>
|
||||||
|
</link>, the most prevalent server and client implementations for the
|
||||||
|
<link xlink:href="https://matrix.org/">Matrix</link> federated communication network.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The astah-community package was removed from nixpkgs due to it being discontinued and the downloads not being available anymore.
|
The astah-community package was removed from nixpkgs due to it being discontinued and the downloads not being available anymore.
|
||||||
|
|
Loading…
Reference in a new issue