mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-16 14:54:29 +01:00
nixos/prosody: convert manual chapter to MD
This commit is contained in:
pennae
parent
5917123885
commit
963c6f54aa
3 changed files with 143 additions and 67 deletions
72
nixos/modules/services/networking/prosody.md
Normal file
72
nixos/modules/services/networking/prosody.md
Normal 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" ];
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
|
@ -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;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,89 +1,90 @@
|
|||
<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>
|
||||
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-prosody">
|
||||
<title>Prosody</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!
|
||||
<link xlink:href="https://prosody.im/">Prosody</link> is an
|
||||
open-source, modern XMPP server.
|
||||
</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:
|
||||
<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 = [ "root@example.org" ];
|
||||
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
|
||||
ssl.key = "/var/lib/acme/example.org/key.pem";
|
||||
virtualHosts."example.org" = {
|
||||
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";
|
||||
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";
|
||||
domain = "conference.example.org";
|
||||
} ];
|
||||
uploadHttp = {
|
||||
domain = "upload.example.org";
|
||||
domain = "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:
|
||||
</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 = "root@example.org";
|
||||
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" ];
|
||||
"example.org" = {
|
||||
webroot = "/var/www/example.org";
|
||||
email = "root@example.org";
|
||||
extraDomainNames = [ "conference.example.org" "upload.example.org" ];
|
||||
};
|
||||
};
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue