depot/third_party/nixpkgs/nixos/modules/services/networking/prosody.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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:
    </para>
    <programlisting>
services.prosody = {
  enable = true;
  admins = [ &quot;root@example.org&quot; ];
  ssl.cert = &quot;/var/lib/acme/example.org/fullchain.pem&quot;;
  ssl.key = &quot;/var/lib/acme/example.org/key.pem&quot;;
  virtualHosts.&quot;example.org&quot; = {
      enabled = true;
      domain = &quot;example.org&quot;;
      ssl.cert = &quot;/var/lib/acme/example.org/fullchain.pem&quot;;
      ssl.key = &quot;/var/lib/acme/example.org/key.pem&quot;;
  };
  muc = [ {
      domain = &quot;conference.example.org&quot;;
  } ];
  uploadHttp = {
      domain = &quot;upload.example.org&quot;;
  };
};
</programlisting>
  </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:
    </para>
    <programlisting>
security.acme = {
  email = &quot;root@example.org&quot;;
  acceptTerms = true;
  certs = {
    &quot;example.org&quot; = {
      webroot = &quot;/var/www/example.org&quot;;
      email = &quot;root@example.org&quot;;
      extraDomainNames = [ &quot;conference.example.org&quot; &quot;upload.example.org&quot; ];
    };
  };
};
</programlisting>
  </section>
</chapter>