pyrox.dev
lol
nixos/pleroma: convert manual chapter to MD
+322
-85
+180
nixos/modules/services/networking/pleroma.md
+180
nixos/modules/services/networking/pleroma.md
···
1
+
# Pleroma {#module-services-pleroma}
2
+
3
+
[Pleroma](https://pleroma.social/) is a lightweight activity pub server.
4
+
5
+
## Generating the Pleroma config {#module-services-pleroma-generate-config}
6
+
7
+
The `pleroma_ctl` CLI utility will prompt you some questions and it will generate an initial config file. This is an example of usage
8
+
```ShellSession
9
+
$ mkdir tmp-pleroma
10
+
$ cd tmp-pleroma
11
+
$ nix-shell -p pleroma-otp
12
+
$ pleroma_ctl instance gen --output config.exs --output-psql setup.psql
13
+
```
14
+
15
+
The `config.exs` file can be further customized following the instructions on the [upstream documentation](https://docs-develop.pleroma.social/backend/configuration/cheatsheet/). Many refinements can be applied also after the service is running.
16
+
17
+
## Initializing the database {#module-services-pleroma-initialize-db}
18
+
19
+
First, the Postgresql service must be enabled in the NixOS configuration
20
+
```
21
+
services.postgresql = {
22
+
enable = true;
23
+
package = pkgs.postgresql_13;
24
+
};
25
+
```
26
+
and activated with the usual
27
+
```ShellSession
28
+
$ nixos-rebuild switch
29
+
```
30
+
31
+
Then you can create and seed the database, using the `setup.psql` file that you generated in the previous section, by running
32
+
```ShellSession
33
+
$ sudo -u postgres psql -f setup.psql
34
+
```
35
+
36
+
## Enabling the Pleroma service locally {#module-services-pleroma-enable}
37
+
38
+
In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.
39
+
40
+
This is an example of configuration, where [](#opt-services.pleroma.configs) option contains the content of the file `config.exs`, generated [in the first section](#module-services-pleroma-generate-config), but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is important, because otherwise they will be stored publicly in the Nix store.
41
+
```
42
+
services.pleroma = {
43
+
enable = true;
44
+
secretConfigFile = "/var/lib/pleroma/secrets.exs";
45
+
configs = [
46
+
''
47
+
import Config
48
+
49
+
config :pleroma, Pleroma.Web.Endpoint,
50
+
url: [host: "pleroma.example.net", scheme: "https", port: 443],
51
+
http: [ip: {127, 0, 0, 1}, port: 4000]
52
+
53
+
config :pleroma, :instance,
54
+
name: "Test",
55
+
email: "admin@example.net",
56
+
notify_email: "admin@example.net",
57
+
limit: 5000,
58
+
registrations_open: true
59
+
60
+
config :pleroma, :media_proxy,
61
+
enabled: false,
62
+
redirect_on_failure: true
63
+
64
+
config :pleroma, Pleroma.Repo,
65
+
adapter: Ecto.Adapters.Postgres,
66
+
username: "pleroma",
67
+
database: "pleroma",
68
+
hostname: "localhost"
69
+
70
+
# Configure web push notifications
71
+
config :web_push_encryption, :vapid_details,
72
+
subject: "mailto:admin@example.net"
73
+
74
+
# ... TO CONTINUE ...
75
+
''
76
+
];
77
+
};
78
+
```
79
+
80
+
Secrets must be moved into a file pointed by [](#opt-services.pleroma.secretConfigFile), in our case `/var/lib/pleroma/secrets.exs`. This file can be created copying the previously generated `config.exs` file and then removing all the settings, except the secrets. This is an example
81
+
```
82
+
# Pleroma instance passwords
83
+
84
+
import Config
85
+
86
+
config :pleroma, Pleroma.Web.Endpoint,
87
+
secret_key_base: "<the secret generated by pleroma_ctl>",
88
+
signing_salt: "<the secret generated by pleroma_ctl>"
89
+
90
+
config :pleroma, Pleroma.Repo,
91
+
password: "<the secret generated by pleroma_ctl>"
92
+
93
+
# Configure web push notifications
94
+
config :web_push_encryption, :vapid_details,
95
+
public_key: "<the secret generated by pleroma_ctl>",
96
+
private_key: "<the secret generated by pleroma_ctl>"
97
+
98
+
# ... TO CONTINUE ...
99
+
```
100
+
Note that the lines of the same configuration group are comma separated (i.e. all the lines end with a comma, except the last one), so when the lines with passwords are added or removed, commas must be adjusted accordingly.
101
+
102
+
The service can be enabled with the usual
103
+
```ShellSession
104
+
$ nixos-rebuild switch
105
+
```
106
+
107
+
The service is accessible only from the local `127.0.0.1:4000` port. It can be tested using a port forwarding like this
108
+
```ShellSession
109
+
$ ssh -L 4000:localhost:4000 myuser@example.net
110
+
```
111
+
and then accessing <http://localhost:4000> from a web browser.
112
+
113
+
## Creating the admin user {#module-services-pleroma-admin-user}
114
+
115
+
After Pleroma service is running, all [Pleroma administration utilities](https://docs-develop.pleroma.social/) can be used. In particular an admin user can be created with
116
+
```ShellSession
117
+
$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>
118
+
```
119
+
120
+
## Configuring Nginx {#module-services-pleroma-nginx}
121
+
122
+
In this configuration, Pleroma is listening only on the local port 4000. Nginx can be configured as a Reverse Proxy, for forwarding requests from public ports to the Pleroma service. This is an example of configuration, using
123
+
[Let's Encrypt](https://letsencrypt.org/) for the TLS certificates
124
+
```
125
+
security.acme = {
126
+
email = "root@example.net";
127
+
acceptTerms = true;
128
+
};
129
+
130
+
services.nginx = {
131
+
enable = true;
132
+
addSSL = true;
133
+
134
+
recommendedTlsSettings = true;
135
+
recommendedOptimisation = true;
136
+
recommendedGzipSettings = true;
137
+
138
+
recommendedProxySettings = false;
139
+
# NOTE: if enabled, the NixOS proxy optimizations will override the Pleroma
140
+
# specific settings, and they will enter in conflict.
141
+
142
+
virtualHosts = {
143
+
"pleroma.example.net" = {
144
+
http2 = true;
145
+
enableACME = true;
146
+
forceSSL = true;
147
+
148
+
locations."/" = {
149
+
proxyPass = "http://127.0.0.1:4000";
150
+
151
+
extraConfig = ''
152
+
etag on;
153
+
gzip on;
154
+
155
+
add_header 'Access-Control-Allow-Origin' '*' always;
156
+
add_header 'Access-Control-Allow-Methods' 'POST, PUT, DELETE, GET, PATCH, OPTIONS' always;
157
+
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Idempotency-Key' always;
158
+
add_header 'Access-Control-Expose-Headers' 'Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id' always;
159
+
if ($request_method = OPTIONS) {
160
+
return 204;
161
+
}
162
+
add_header X-XSS-Protection "1; mode=block";
163
+
add_header X-Permitted-Cross-Domain-Policies none;
164
+
add_header X-Frame-Options DENY;
165
+
add_header X-Content-Type-Options nosniff;
166
+
add_header Referrer-Policy same-origin;
167
+
add_header X-Download-Options noopen;
168
+
proxy_http_version 1.1;
169
+
proxy_set_header Upgrade $http_upgrade;
170
+
proxy_set_header Connection "upgrade";
171
+
proxy_set_header Host $host;
172
+
173
+
client_max_body_size 16m;
174
+
# NOTE: increase if users need to upload very big files
175
+
'';
176
+
};
177
+
};
178
+
};
179
+
};
180
+
```
+2
nixos/modules/services/networking/pleroma.nix
+2
nixos/modules/services/networking/pleroma.nix
···
147
147
148
148
};
149
149
meta.maintainers = with lib.maintainers; [ ninjatrappeur ];
150
+
# Don't edit the docbook xml directly, edit the md and generate it:
151
+
# `pandoc pleroma.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 > pleroma.xml`
150
152
meta.doc = ./pleroma.xml;
151
153
}
+140
-85
nixos/modules/services/networking/pleroma.xml
+140
-85
nixos/modules/services/networking/pleroma.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-pleroma">
6
-
<title>Pleroma</title>
7
-
<para>
8
-
<link xlink:href="https://pleroma.social/">Pleroma</link> is a lightweight activity pub server.</para>
9
-
<section xml:id="module-services-pleroma-generate-config">
10
-
<title>Generating the Pleroma config</title>
11
-
<para>The <literal>pleroma_ctl</literal> CLI utility will prompt you some questions and it will generate an initial config file. This is an example of usage
12
-
<programlisting>
13
-
<prompt>$ </prompt>mkdir tmp-pleroma
14
-
<prompt>$ </prompt>cd tmp-pleroma
15
-
<prompt>$ </prompt>nix-shell -p pleroma-otp
16
-
<prompt>$ </prompt>pleroma_ctl instance gen --output config.exs --output-psql setup.psql
1
+
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pleroma">
2
+
<title>Pleroma</title>
3
+
<para>
4
+
<link xlink:href="https://pleroma.social/">Pleroma</link> is a
5
+
lightweight activity pub server.
6
+
</para>
7
+
<section xml:id="module-services-pleroma-generate-config">
8
+
<title>Generating the Pleroma config</title>
9
+
<para>
10
+
The <literal>pleroma_ctl</literal> CLI utility will prompt you
11
+
some questions and it will generate an initial config file. This
12
+
is an example of usage
13
+
</para>
14
+
<programlisting>
15
+
$ mkdir tmp-pleroma
16
+
$ cd tmp-pleroma
17
+
$ nix-shell -p pleroma-otp
18
+
$ pleroma_ctl instance gen --output config.exs --output-psql setup.psql
17
19
</programlisting>
18
-
</para>
19
-
<para>The <literal>config.exs</literal> file can be further customized following the instructions on the <link xlink:href="https://docs-develop.pleroma.social/backend/configuration/cheatsheet/">upstream documentation</link>. Many refinements can be applied also after the service is running.</para>
20
-
</section>
21
-
<section xml:id="module-services-pleroma-initialize-db">
22
-
<title>Initializing the database</title>
23
-
<para>First, the Postgresql service must be enabled in the NixOS configuration
24
-
<programlisting>
20
+
<para>
21
+
The <literal>config.exs</literal> file can be further customized
22
+
following the instructions on the
23
+
<link xlink:href="https://docs-develop.pleroma.social/backend/configuration/cheatsheet/">upstream
24
+
documentation</link>. Many refinements can be applied also after
25
+
the service is running.
26
+
</para>
27
+
</section>
28
+
<section xml:id="module-services-pleroma-initialize-db">
29
+
<title>Initializing the database</title>
30
+
<para>
31
+
First, the Postgresql service must be enabled in the NixOS
32
+
configuration
33
+
</para>
34
+
<programlisting>
25
35
services.postgresql = {
26
36
enable = true;
27
37
package = pkgs.postgresql_13;
28
38
};
29
39
</programlisting>
30
-
and activated with the usual
31
-
<programlisting>
32
-
<prompt>$ </prompt>nixos-rebuild switch
40
+
<para>
41
+
and activated with the usual
42
+
</para>
43
+
<programlisting>
44
+
$ nixos-rebuild switch
33
45
</programlisting>
34
-
</para>
35
-
<para>Then you can create and seed the database, using the <literal>setup.psql</literal> file that you generated in the previous section, by running
36
-
<programlisting>
37
-
<prompt>$ </prompt>sudo -u postgres psql -f setup.psql
46
+
<para>
47
+
Then you can create and seed the database, using the
48
+
<literal>setup.psql</literal> file that you generated in the
49
+
previous section, by running
50
+
</para>
51
+
<programlisting>
52
+
$ sudo -u postgres psql -f setup.psql
38
53
</programlisting>
39
-
</para>
40
-
</section>
41
-
<section xml:id="module-services-pleroma-enable">
42
-
<title>Enabling the Pleroma service locally</title>
43
-
<para>In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.</para>
44
-
<para>This is an example of configuration, where <link linkend="opt-services.pleroma.configs">services.pleroma.configs</link> option contains the content of the file <literal>config.exs</literal>, generated <link linkend="module-services-pleroma-generate-config">in the first section</link>, but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is important, because otherwise they will be stored publicly in the Nix store.
45
-
<programlisting>
54
+
</section>
55
+
<section xml:id="module-services-pleroma-enable">
56
+
<title>Enabling the Pleroma service locally</title>
57
+
<para>
58
+
In this section we will enable the Pleroma service only locally,
59
+
so its configurations can be improved incrementally.
60
+
</para>
61
+
<para>
62
+
This is an example of configuration, where
63
+
<xref linkend="opt-services.pleroma.configs"></xref> option
64
+
contains the content of the file <literal>config.exs</literal>,
65
+
generated
66
+
<link linkend="module-services-pleroma-generate-config">in the
67
+
first section</link>, but with the secrets (database password,
68
+
endpoint secret key, salts, etc.) removed. Removing secrets is
69
+
important, because otherwise they will be stored publicly in the
70
+
Nix store.
71
+
</para>
72
+
<programlisting>
46
73
services.pleroma = {
47
74
enable = true;
48
-
secretConfigFile = "/var/lib/pleroma/secrets.exs";
75
+
secretConfigFile = "/var/lib/pleroma/secrets.exs";
49
76
configs = [
50
77
''
51
78
import Config
52
79
53
80
config :pleroma, Pleroma.Web.Endpoint,
54
-
url: [host: "pleroma.example.net", scheme: "https", port: 443],
81
+
url: [host: "pleroma.example.net", scheme: "https", port: 443],
55
82
http: [ip: {127, 0, 0, 1}, port: 4000]
56
83
57
84
config :pleroma, :instance,
58
-
name: "Test",
59
-
email: "admin@example.net",
60
-
notify_email: "admin@example.net",
85
+
name: "Test",
86
+
email: "admin@example.net",
87
+
notify_email: "admin@example.net",
61
88
limit: 5000,
62
89
registrations_open: true
63
90
···
67
94
68
95
config :pleroma, Pleroma.Repo,
69
96
adapter: Ecto.Adapters.Postgres,
70
-
username: "pleroma",
71
-
database: "pleroma",
72
-
hostname: "localhost"
97
+
username: "pleroma",
98
+
database: "pleroma",
99
+
hostname: "localhost"
73
100
74
101
# Configure web push notifications
75
102
config :web_push_encryption, :vapid_details,
76
-
subject: "mailto:admin@example.net"
103
+
subject: "mailto:admin@example.net"
77
104
78
105
# ... TO CONTINUE ...
79
106
''
80
107
];
81
108
};
82
109
</programlisting>
83
-
</para>
84
-
<para>Secrets must be moved into a file pointed by <link linkend="opt-services.pleroma.secretConfigFile">services.pleroma.secretConfigFile</link>, in our case <literal>/var/lib/pleroma/secrets.exs</literal>. This file can be created copying the previously generated <literal>config.exs</literal> file and then removing all the settings, except the secrets. This is an example
85
-
<programlisting>
110
+
<para>
111
+
Secrets must be moved into a file pointed by
112
+
<xref linkend="opt-services.pleroma.secretConfigFile"></xref>, in
113
+
our case <literal>/var/lib/pleroma/secrets.exs</literal>. This
114
+
file can be created copying the previously generated
115
+
<literal>config.exs</literal> file and then removing all the
116
+
settings, except the secrets. This is an example
117
+
</para>
118
+
<programlisting>
86
119
# Pleroma instance passwords
87
120
88
121
import Config
89
122
90
123
config :pleroma, Pleroma.Web.Endpoint,
91
-
secret_key_base: "<the secret generated by pleroma_ctl>",
92
-
signing_salt: "<the secret generated by pleroma_ctl>"
124
+
secret_key_base: "<the secret generated by pleroma_ctl>",
125
+
signing_salt: "<the secret generated by pleroma_ctl>"
93
126
94
127
config :pleroma, Pleroma.Repo,
95
-
password: "<the secret generated by pleroma_ctl>"
128
+
password: "<the secret generated by pleroma_ctl>"
96
129
97
130
# Configure web push notifications
98
131
config :web_push_encryption, :vapid_details,
99
-
public_key: "<the secret generated by pleroma_ctl>",
100
-
private_key: "<the secret generated by pleroma_ctl>"
132
+
public_key: "<the secret generated by pleroma_ctl>",
133
+
private_key: "<the secret generated by pleroma_ctl>"
101
134
102
135
# ... TO CONTINUE ...
103
136
</programlisting>
104
-
Note that the lines of the same configuration group are comma separated (i.e. all the lines end with a comma, except the last one), so when the lines with passwords are added or removed, commas must be adjusted accordingly.</para>
105
-
106
-
<para>The service can be enabled with the usual
107
-
<programlisting>
108
-
<prompt>$ </prompt>nixos-rebuild switch
137
+
<para>
138
+
Note that the lines of the same configuration group are comma
139
+
separated (i.e. all the lines end with a comma, except the last
140
+
one), so when the lines with passwords are added or removed,
141
+
commas must be adjusted accordingly.
142
+
</para>
143
+
<para>
144
+
The service can be enabled with the usual
145
+
</para>
146
+
<programlisting>
147
+
$ nixos-rebuild switch
109
148
</programlisting>
110
-
</para>
111
-
<para>The service is accessible only from the local <literal>127.0.0.1:4000</literal> port. It can be tested using a port forwarding like this
112
-
<programlisting>
113
-
<prompt>$ </prompt>ssh -L 4000:localhost:4000 myuser@example.net
149
+
<para>
150
+
The service is accessible only from the local
151
+
<literal>127.0.0.1:4000</literal> port. It can be tested using a
152
+
port forwarding like this
153
+
</para>
154
+
<programlisting>
155
+
$ ssh -L 4000:localhost:4000 myuser@example.net
114
156
</programlisting>
115
-
and then accessing <link xlink:href="http://localhost:4000">http://localhost:4000</link> from a web browser.</para>
116
-
</section>
117
-
<section xml:id="module-services-pleroma-admin-user">
118
-
<title>Creating the admin user</title>
119
-
<para>After Pleroma service is running, all <link xlink:href="https://docs-develop.pleroma.social/">Pleroma administration utilities</link> can be used. In particular an admin user can be created with
120
-
<programlisting>
121
-
<prompt>$ </prompt>pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>
157
+
<para>
158
+
and then accessing
159
+
<link xlink:href="http://localhost:4000" role="uri">http://localhost:4000</link>
160
+
from a web browser.
161
+
</para>
162
+
</section>
163
+
<section xml:id="module-services-pleroma-admin-user">
164
+
<title>Creating the admin user</title>
165
+
<para>
166
+
After Pleroma service is running, all
167
+
<link xlink:href="https://docs-develop.pleroma.social/">Pleroma
168
+
administration utilities</link> can be used. In particular an
169
+
admin user can be created with
170
+
</para>
171
+
<programlisting>
172
+
$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>
122
173
</programlisting>
123
-
</para>
124
-
</section>
125
-
<section xml:id="module-services-pleroma-nginx">
126
-
<title>Configuring Nginx</title>
127
-
<para>In this configuration, Pleroma is listening only on the local port 4000. Nginx can be configured as a Reverse Proxy, for forwarding requests from public ports to the Pleroma service. This is an example of configuration, using
128
-
<link xlink:href="https://letsencrypt.org/">Let's Encrypt</link> for the TLS certificates
129
-
<programlisting>
174
+
</section>
175
+
<section xml:id="module-services-pleroma-nginx">
176
+
<title>Configuring Nginx</title>
177
+
<para>
178
+
In this configuration, Pleroma is listening only on the local port
179
+
4000. Nginx can be configured as a Reverse Proxy, for forwarding
180
+
requests from public ports to the Pleroma service. This is an
181
+
example of configuration, using
182
+
<link xlink:href="https://letsencrypt.org/">Let's Encrypt</link>
183
+
for the TLS certificates
184
+
</para>
185
+
<programlisting>
130
186
security.acme = {
131
-
email = "root@example.net";
187
+
email = "root@example.net";
132
188
acceptTerms = true;
133
189
};
134
190
···
145
201
# specific settings, and they will enter in conflict.
146
202
147
203
virtualHosts = {
148
-
"pleroma.example.net" = {
204
+
"pleroma.example.net" = {
149
205
http2 = true;
150
206
enableACME = true;
151
207
forceSSL = true;
152
208
153
-
locations."/" = {
154
-
proxyPass = "http://127.0.0.1:4000";
209
+
locations."/" = {
210
+
proxyPass = "http://127.0.0.1:4000";
155
211
156
212
extraConfig = ''
157
213
etag on;
···
164
220
if ($request_method = OPTIONS) {
165
221
return 204;
166
222
}
167
-
add_header X-XSS-Protection "1; mode=block";
223
+
add_header X-XSS-Protection "1; mode=block";
168
224
add_header X-Permitted-Cross-Domain-Policies none;
169
225
add_header X-Frame-Options DENY;
170
226
add_header X-Content-Type-Options nosniff;
···
172
228
add_header X-Download-Options noopen;
173
229
proxy_http_version 1.1;
174
230
proxy_set_header Upgrade $http_upgrade;
175
-
proxy_set_header Connection "upgrade";
231
+
proxy_set_header Connection "upgrade";
176
232
proxy_set_header Host $host;
177
233
178
234
client_max_body_size 16m;
···
183
239
};
184
240
};
185
241
</programlisting>
186
-
</para>
187
-
</section>
242
+
</section>
188
243
</chapter>