pyrox.dev
lol
nixos/prosody: convert manual chapter to MD
+143
-67
+72
nixos/modules/services/networking/prosody.md
+72
nixos/modules/services/networking/prosody.md
···
1
+
# Prosody {#module-services-prosody}
2
+
3
+
[Prosody](https://prosody.im/) is an open-source, modern XMPP server.
4
+
5
+
## Basic usage {#module-services-prosody-basic-usage}
6
+
7
+
A common struggle for most XMPP newcomers is to find the right set
8
+
of XMPP Extensions (XEPs) to setup. Forget to activate a few of
9
+
those and your XMPP experience might turn into a nightmare!
10
+
11
+
The XMPP community tackles this problem by creating a meta-XEP
12
+
listing a decent set of XEPs you should implement. This meta-XEP
13
+
is issued every year, the 2020 edition being
14
+
[XEP-0423](https://xmpp.org/extensions/xep-0423.html).
15
+
16
+
The NixOS Prosody module will implement most of these recommendend XEPs out of
17
+
the box. That being said, two components still require some
18
+
manual configuration: the
19
+
[Multi User Chat (MUC)](https://xmpp.org/extensions/xep-0045.html)
20
+
and the [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html) ones.
21
+
You'll need to create a DNS subdomain for each of those. The current convention is to name your
22
+
MUC endpoint `conference.example.org` and your HTTP upload domain `upload.example.org`.
23
+
24
+
A good configuration to start with, including a
25
+
[Multi User Chat (MUC)](https://xmpp.org/extensions/xep-0045.html)
26
+
endpoint as well as a [HTTP File Upload](https://xmpp.org/extensions/xep-0363.html)
27
+
endpoint will look like this:
28
+
```
29
+
services.prosody = {
30
+
enable = true;
31
+
admins = [ "root@example.org" ];
32
+
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
33
+
ssl.key = "/var/lib/acme/example.org/key.pem";
34
+
virtualHosts."example.org" = {
35
+
enabled = true;
36
+
domain = "example.org";
37
+
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
38
+
ssl.key = "/var/lib/acme/example.org/key.pem";
39
+
};
40
+
muc = [ {
41
+
domain = "conference.example.org";
42
+
} ];
43
+
uploadHttp = {
44
+
domain = "upload.example.org";
45
+
};
46
+
};
47
+
```
48
+
49
+
## Let's Encrypt Configuration {#module-services-prosody-letsencrypt}
50
+
51
+
As you can see in the code snippet from the
52
+
[previous section](#module-services-prosody-basic-usage),
53
+
you'll need a single TLS certificate covering your main endpoint,
54
+
the MUC one as well as the HTTP Upload one. We can generate such a
55
+
certificate by leveraging the ACME
56
+
[extraDomainNames](#opt-security.acme.certs._name_.extraDomainNames) module option.
57
+
58
+
Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
59
+
a TLS certificate for the three endponits:
60
+
```
61
+
security.acme = {
62
+
email = "root@example.org";
63
+
acceptTerms = true;
64
+
certs = {
65
+
"example.org" = {
66
+
webroot = "/var/www/example.org";
67
+
email = "root@example.org";
68
+
extraDomainNames = [ "conference.example.org" "upload.example.org" ];
69
+
};
70
+
};
71
+
};
72
+
```
+3
nixos/modules/services/networking/prosody.nix
+3
nixos/modules/services/networking/prosody.nix
···
904
904
};
905
905
906
906
};
907
+
908
+
# Don't edit the docbook xml directly, edit the md and generate it:
909
+
# `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`
907
910
meta.doc = ./prosody.xml;
908
911
}
+68
-67
nixos/modules/services/networking/prosody.xml
+68
-67
nixos/modules/services/networking/prosody.xml
···
1
-
<chapter xmlns="http://docbook.org/ns/docbook"
2
-
xmlns:xlink="http://www.w3.org/1999/xlink"
3
-
xmlns:xi="http://www.w3.org/2001/XInclude"
4
-
version="5.0"
5
-
xml:id="module-services-prosody">
6
-
<title>Prosody</title>
7
-
<para>
8
-
<link xlink:href="https://prosody.im/">Prosody</link> is an open-source, modern XMPP server.
9
-
</para>
10
-
<section xml:id="module-services-prosody-basic-usage">
11
-
<title>Basic usage</title>
12
-
13
-
<para>
14
-
A common struggle for most XMPP newcomers is to find the right set
15
-
of XMPP Extensions (XEPs) to setup. Forget to activate a few of
16
-
those and your XMPP experience might turn into a nightmare!
17
-
</para>
18
-
1
+
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-prosody">
2
+
<title>Prosody</title>
19
3
<para>
20
-
The XMPP community tackles this problem by creating a meta-XEP
21
-
listing a decent set of XEPs you should implement. This meta-XEP
22
-
is issued every year, the 2020 edition being
23
-
<link xlink:href="https://xmpp.org/extensions/xep-0423.html">XEP-0423</link>.
24
-
</para>
25
-
<para>
26
-
The NixOS Prosody module will implement most of these recommendend XEPs out of
27
-
the box. That being said, two components still require some
28
-
manual configuration: the
29
-
<link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link>
30
-
and the <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link> ones.
31
-
You'll need to create a DNS subdomain for each of those. The current convention is to name your
32
-
MUC endpoint <literal>conference.example.org</literal> and your HTTP upload domain <literal>upload.example.org</literal>.
4
+
<link xlink:href="https://prosody.im/">Prosody</link> is an
5
+
open-source, modern XMPP server.
33
6
</para>
34
-
<para>
35
-
A good configuration to start with, including a
36
-
<link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link>
37
-
endpoint as well as a <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link>
38
-
endpoint will look like this:
7
+
<section xml:id="module-services-prosody-basic-usage">
8
+
<title>Basic usage</title>
9
+
<para>
10
+
A common struggle for most XMPP newcomers is to find the right set
11
+
of XMPP Extensions (XEPs) to setup. Forget to activate a few of
12
+
those and your XMPP experience might turn into a nightmare!
13
+
</para>
14
+
<para>
15
+
The XMPP community tackles this problem by creating a meta-XEP
16
+
listing a decent set of XEPs you should implement. This meta-XEP
17
+
is issued every year, the 2020 edition being
18
+
<link xlink:href="https://xmpp.org/extensions/xep-0423.html">XEP-0423</link>.
19
+
</para>
20
+
<para>
21
+
The NixOS Prosody module will implement most of these recommendend
22
+
XEPs out of the box. That being said, two components still require
23
+
some manual configuration: the
24
+
<link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi
25
+
User Chat (MUC)</link> and the
26
+
<link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP
27
+
File Upload</link> ones. You'll need to create a DNS subdomain for
28
+
each of those. The current convention is to name your MUC endpoint
29
+
<literal>conference.example.org</literal> and your HTTP upload
30
+
domain <literal>upload.example.org</literal>.
31
+
</para>
32
+
<para>
33
+
A good configuration to start with, including a
34
+
<link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi
35
+
User Chat (MUC)</link> endpoint as well as a
36
+
<link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP
37
+
File Upload</link> endpoint will look like this:
38
+
</para>
39
39
<programlisting>
40
40
services.prosody = {
41
41
enable = true;
42
-
admins = [ "root@example.org" ];
43
-
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
44
-
ssl.key = "/var/lib/acme/example.org/key.pem";
45
-
virtualHosts."example.org" = {
42
+
admins = [ "root@example.org" ];
43
+
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
44
+
ssl.key = "/var/lib/acme/example.org/key.pem";
45
+
virtualHosts."example.org" = {
46
46
enabled = true;
47
-
domain = "example.org";
48
-
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
49
-
ssl.key = "/var/lib/acme/example.org/key.pem";
47
+
domain = "example.org";
48
+
ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
49
+
ssl.key = "/var/lib/acme/example.org/key.pem";
50
50
};
51
51
muc = [ {
52
-
domain = "conference.example.org";
52
+
domain = "conference.example.org";
53
53
} ];
54
54
uploadHttp = {
55
-
domain = "upload.example.org";
55
+
domain = "upload.example.org";
56
56
};
57
57
};
58
58
</programlisting>
59
-
</para>
60
-
</section>
61
-
<section xml:id="module-services-prosody-letsencrypt">
62
-
<title>Let's Encrypt Configuration</title>
63
-
<para>
64
-
As you can see in the code snippet from the
65
-
<link linkend="module-services-prosody-basic-usage">previous section</link>,
66
-
you'll need a single TLS certificate covering your main endpoint,
67
-
the MUC one as well as the HTTP Upload one. We can generate such a
68
-
certificate by leveraging the ACME
69
-
<link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> module option.
70
-
</para>
71
-
<para>
72
-
Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
73
-
a TLS certificate for the three endponits:
59
+
</section>
60
+
<section xml:id="module-services-prosody-letsencrypt">
61
+
<title>Let's Encrypt Configuration</title>
62
+
<para>
63
+
As you can see in the code snippet from the
64
+
<link linkend="module-services-prosody-basic-usage">previous
65
+
section</link>, you'll need a single TLS certificate covering your
66
+
main endpoint, the MUC one as well as the HTTP Upload one. We can
67
+
generate such a certificate by leveraging the ACME
68
+
<link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link>
69
+
module option.
70
+
</para>
71
+
<para>
72
+
Provided the setup detailed in the previous section, you'll need
73
+
the following acme configuration to generate a TLS certificate for
74
+
the three endponits:
75
+
</para>
74
76
<programlisting>
75
77
security.acme = {
76
-
email = "root@example.org";
78
+
email = "root@example.org";
77
79
acceptTerms = true;
78
80
certs = {
79
-
"example.org" = {
80
-
webroot = "/var/www/example.org";
81
-
email = "root@example.org";
82
-
extraDomainNames = [ "conference.example.org" "upload.example.org" ];
81
+
"example.org" = {
82
+
webroot = "/var/www/example.org";
83
+
email = "root@example.org";
84
+
extraDomainNames = [ "conference.example.org" "upload.example.org" ];
83
85
};
84
86
};
85
87
};
86
88
</programlisting>
87
-
</para>
88
-
</section>
89
+
</section>
89
90
</chapter>