diff options
Diffstat (limited to 'nixos/doc/manual/configuration/matrix.xml')
| -rw-r--r-- | nixos/doc/manual/configuration/matrix.xml | 134 |
1 files changed, 70 insertions, 64 deletions
diff --git a/nixos/doc/manual/configuration/matrix.xml b/nixos/doc/manual/configuration/matrix.xml index a9a5d6de1f1d..66965460a15d 100644 --- a/nixos/doc/manual/configuration/matrix.xml +++ b/nixos/doc/manual/configuration/matrix.xml @@ -5,31 +5,34 @@ 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. + <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. + 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</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> + installation instructions of Synapse </link>. +<programlisting> let fqdn = let @@ -116,28 +119,29 @@ }; </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. + 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> + 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> @@ -147,31 +151,32 @@ 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. + <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> + <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; @@ -183,15 +188,16 @@ }; </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. + 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> |