<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-prosody"> <title>Prosody</title> <para> <link xlink:href="https://prosody.im/">Prosody</link> is an open-source, modern XMPP server. </para> <section xml:id="module-services-prosody-basic-usage"> <title>Basic usage</title> <para> A common struggle for most XMPP newcomers is to find the right set of XMPP Extensions (XEPs) to setup. Forget to activate a few of those and your XMPP experience might turn into a nightmare! </para> <para> The XMPP community tackles this problem by creating a meta-XEP listing a decent set of XEPs you should implement. This meta-XEP is issued every year, the 2020 edition being <link xlink:href="https://xmpp.org/extensions/xep-0423.html">XEP-0423</link>. </para> <para> The NixOS Prosody module will implement most of these recommendend XEPs out of the box. That being said, two components still require some manual configuration: the <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link> and the <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link> ones. You'll need to create a DNS subdomain for each of those. The current convention is to name your MUC endpoint <literal>conference.example.org</literal> and your HTTP upload domain <literal>upload.example.org</literal>. </para> <para> A good configuration to start with, including a <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link> endpoint as well as a <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link> endpoint will look like this: <programlisting> services.prosody = { <link linkend="opt-services.prosody.enable">enable</link> = true; <link linkend="opt-services.prosody.admins">admins</link> = [ "root@example.org" ]; <link linkend="opt-services.prosody.ssl.cert">ssl.cert</link> = "/var/lib/acme/example.org/fullchain.pem"; <link linkend="opt-services.prosody.ssl.key">ssl.key</link> = "/var/lib/acme/example.org/key.pem"; <link linkend="opt-services.prosody.virtualHosts">virtualHosts</link>."example.org" = { <link linkend="opt-services.prosody.virtualHosts._name_.enabled">enabled</link> = true; <link linkend="opt-services.prosody.virtualHosts._name_.domain">domain</link> = "example.org"; <link linkend="opt-services.prosody.virtualHosts._name_.ssl.cert">ssl.cert</link> = "/var/lib/acme/example.org/fullchain.pem"; <link linkend="opt-services.prosody.virtualHosts._name_.ssl.key">ssl.key</link> = "/var/lib/acme/example.org/key.pem"; }; <link linkend="opt-services.prosody.muc">muc</link> = [ { <link linkend="opt-services.prosody.muc">domain</link> = "conference.example.org"; } ]; <link linkend="opt-services.prosody.uploadHttp">uploadHttp</link> = { <link linkend="opt-services.prosody.uploadHttp.domain">domain</link> = "upload.example.org"; }; };</programlisting> </para> </section> <section xml:id="module-services-prosody-letsencrypt"> <title>Let's Encrypt Configuration</title> <para> As you can see in the code snippet from the <link linkend="module-services-prosody-basic-usage">previous section</link>, you'll need a single TLS certificate covering your main endpoint, the MUC one as well as the HTTP Upload one. We can generate such a certificate by leveraging the ACME <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> module option. </para> <para> Provided the setup detailed in the previous section, you'll need the following acme configuration to generate a TLS certificate for the three endponits: <programlisting> security.acme = { <link linkend="opt-security.acme.email">email</link> = "root@example.org"; <link linkend="opt-security.acme.acceptTerms">acceptTerms</link> = true; <link linkend="opt-security.acme.certs">certs</link> = { "example.org" = { <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/example.org"; <link linkend="opt-security.acme.certs._name_.email">email</link> = "root@example.org"; <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> = [ "conference.example.org" "upload.example.org" ]; }; }; };</programlisting> </para> </section> </chapter>