MirrorHub/nixpkgs
0
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2024-11-16 14:54:29 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

nixos/prosody: convert manual chapter to MD

Browse source
This commit is contained in:
pennae 2023-01-03 06:23:17 +01:00
parent 5917123885
commit 963c6f54aa
3 changed files with 143 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
nixos/modules/services/networking/prosody.md Normal file
View file

@ -0,0 +1,72 @@
# Prosody {#module-services-prosody}
[Prosody](https://prosody.im/) is an open-source, modern XMPP server.
## Basic usage {#module-services-prosody-basic-usage}
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!
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
[XEP-0423](https://xmpp.org/extensions/xep-0423.html).
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
[Multi User Chat (MUC)](https://xmpp.org/extensions/xep-0045.html)
and the [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html) ones.
You'll need to create a DNS subdomain for each of those. The current convention is to name your
MUC endpoint `conference.example.org` and your HTTP upload domain `upload.example.org`.
A good configuration to start with, including a
[Multi User Chat (MUC)](https://xmpp.org/extensions/xep-0045.html)
endpoint as well as a [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html)
endpoint will look like this:
```
services.prosody = {
enable = true;
admins = [ "root@example.org" ];
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
ssl.key = "/var/lib/acme/example.org/key.pem";
virtualHosts."example.org" = {
enabled = true;
domain = "example.org";
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
ssl.key = "/var/lib/acme/example.org/key.pem";
};
muc = [ {
domain = "conference.example.org";
} ];
uploadHttp = {
domain = "upload.example.org";
};
};
```
## Let's Encrypt Configuration {#module-services-prosody-letsencrypt}
As you can see in the code snippet from the
[previous section](#module-services-prosody-basic-usage),
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
[extraDomainNames](#opt-security.acme.certs._name_.extraDomainNames) module option.
Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
a TLS certificate for the three endponits:
```
security.acme = {
email = "root@example.org";
acceptTerms = true;
certs = {
"example.org" = {
webroot = "/var/www/example.org";
email = "root@example.org";
extraDomainNames = [ "conference.example.org" "upload.example.org" ];
};
};
};
```

3
nixos/modules/services/networking/prosody.nix
View file

@ -904,5 +904,8 @@ in
}; };
}; };
# Don't edit the docbook xml directly, edit the md and generate it:
# `pandoc prosody.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 > prosody.xml`
meta.doc = ./prosody.xml; meta.doc = ./prosody.xml;
} }

135
nixos/modules/services/networking/prosody.xml
View file

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