1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
|
# Akkoma {#module-services-akkoma}
[Akkoma](https://akkoma.dev/) is a lightweight ActivityPub microblogging server forked from Pleroma.
## Service configuration {#modules-services-akkoma-service-configuration}
The Elixir configuration file required by Akkoma is generated automatically from
[{option}`services.akkoma.config`](options.html#opt-services.akkoma.config). Secrets must be
included from external files outside of the Nix store by setting the configuration option to
an attribute set containing the attribute {option}`_secret` – a string pointing to the file
containing the actual value of the option.
For the mandatory configuration settings these secrets will be generated automatically if the
referenced file does not exist during startup, unless disabled through
[{option}`services.akkoma.initSecrets`](options.html#opt-services.akkoma.initSecrets).
The following configuration binds Akkoma to the Unix socket `/run/akkoma/socket`, expecting to
be run behind a HTTP proxy on `fediverse.example.com`.
```nix
{
services.akkoma.enable = true;
services.akkoma.config = {
":pleroma" = {
":instance" = {
name = "My Akkoma instance";
description = "More detailed description";
email = "admin@example.com";
registration_open = false;
};
"Pleroma.Web.Endpoint" = {
url.host = "fediverse.example.com";
};
};
};
}
```
Please refer to the [configuration cheat sheet](https://docs.akkoma.dev/stable/configuration/cheatsheet/)
for additional configuration options.
## User management {#modules-services-akkoma-user-management}
After the Akkoma service is running, the administration utility can be used to
[manage users](https://docs.akkoma.dev/stable/administration/CLI_tasks/user/). In particular an
administrative user can be created with
```ShellSession
$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>
```
## Proxy configuration {#modules-services-akkoma-proxy-configuration}
Although it is possible to expose Akkoma directly, it is common practice to operate it behind an
HTTP reverse proxy such as nginx.
```nix
{
services.akkoma.nginx = {
enableACME = true;
forceSSL = true;
};
services.nginx = {
enable = true;
clientMaxBodySize = "16m";
recommendedTlsSettings = true;
recommendedOptimisation = true;
recommendedGzipSettings = true;
};
}
```
Please refer to [](#module-security-acme) for details on how to provision an SSL/TLS certificate.
### Media proxy {#modules-services-akkoma-media-proxy}
Without the media proxy function, Akkoma does not store any remote media like pictures or video
locally, and clients have to fetch them directly from the source server.
```nix
{
# Enable nginx slice module distributed with Tengine
services.nginx.package = pkgs.tengine;
# Enable media proxy
services.akkoma.config.":pleroma".":media_proxy" = {
enabled = true;
proxy_opts.redirect_on_failure = true;
};
# Adjust the persistent cache size as needed:
# Assuming an average object size of 128 KiB, around 1 MiB
# of memory is required for the key zone per GiB of cache.
# Ensure that the cache directory exists and is writable by nginx.
services.nginx.commonHttpConfig = ''
proxy_cache_path /var/cache/nginx/cache/akkoma-media-cache
levels= keys_zone=akkoma_media_cache:16m max_size=16g
inactive=1y use_temp_path=off;
'';
services.akkoma.nginx = {
locations."/proxy" = {
proxyPass = "http://unix:/run/akkoma/socket";
extraConfig = ''
proxy_cache akkoma_media_cache;
# Cache objects in slices of 1 MiB
slice 1m;
proxy_cache_key $host$uri$is_args$args$slice_range;
proxy_set_header Range $slice_range;
# Decouple proxy and upstream responses
proxy_buffering on;
proxy_cache_lock on;
proxy_ignore_client_abort on;
# Default cache times for various responses
proxy_cache_valid 200 1y;
proxy_cache_valid 206 301 304 1h;
# Allow serving of stale items
proxy_cache_use_stale error timeout invalid_header updating;
'';
};
};
}
```
#### Prefetch remote media {#modules-services-akkoma-prefetch-remote-media}
The following example enables the `MediaProxyWarmingPolicy` MRF policy which automatically
fetches all media associated with a post through the media proxy, as soon as the post is
received by the instance.
```nix
{
services.akkoma.config.":pleroma".":mrf".policies =
map (pkgs.formats.elixirConf { }).lib.mkRaw [
"Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy"
];
}
```
#### Media previews {#modules-services-akkoma-media-previews}
Akkoma can generate previews for media.
```nix
{
services.akkoma.config.":pleroma".":media_preview_proxy" = {
enabled = true;
thumbnail_max_width = 1920;
thumbnail_max_height = 1080;
};
}
```
## Frontend management {#modules-services-akkoma-frontend-management}
Akkoma will be deployed with the `akkoma-fe` and `admin-fe` frontends by default. These can be
modified by setting
[{option}`services.akkoma.frontends`](options.html#opt-services.akkoma.frontends).
The following example overrides the primary frontend’s default configuration using a custom
derivation.
```nix
{
services.akkoma.frontends.primary.package = pkgs.runCommand "akkoma-fe" {
config = builtins.toJSON {
expertLevel = 1;
collapseMessageWithSubject = false;
stopGifs = false;
replyVisibility = "following";
webPushHideIfCW = true;
hideScopeNotice = true;
renderMisskeyMarkdown = false;
hideSiteFavicon = true;
postContentType = "text/markdown";
showNavShortcuts = false;
};
nativeBuildInputs = with pkgs; [ jq xorg.lndir ];
passAsFile = [ "config" ];
} ''
mkdir $out
lndir ${pkgs.akkoma-frontends.akkoma-fe} $out
rm $out/static/config.json
jq -s add ${pkgs.akkoma-frontends.akkoma-fe}/static/config.json ${config} \
>$out/static/config.json
'';
}
```
## Federation policies {#modules-services-akkoma-federation-policies}
Akkoma comes with a number of modules to police federation with other ActivityPub instances.
The most valuable for typical users is the
[`:mrf_simple`](https://docs.akkoma.dev/stable/configuration/cheatsheet/#mrf_simple) module
which allows limiting federation based on instance hostnames.
This configuration snippet provides an example on how these can be used. Choosing an adequate
federation policy is not trivial and entails finding a balance between connectivity to the rest
of the fediverse and providing a pleasant experience to the users of an instance.
```nix
{
services.akkoma.config.":pleroma" = with (pkgs.formats.elixirConf { }).lib; {
":mrf".policies = map mkRaw [
"Pleroma.Web.ActivityPub.MRF.SimplePolicy"
];
":mrf_simple" = {
# Tag all media as sensitive
media_nsfw = mkMap {
"nsfw.weird.kinky" = "Untagged NSFW content";
};
# Reject all activities except deletes
reject = mkMap {
"kiwifarms.cc" = "Persistent harassment of users, no moderation";
};
# Force posts to be visible by followers only
followers_only = mkMap {
"beta.birdsite.live" = "Avoid polluting timelines with Twitter posts";
};
};
};
}
```
## Upload filters {#modules-services-akkoma-upload-filters}
This example strips GPS and location metadata from uploads, deduplicates them and anonymises the
the file name.
```nix
{
services.akkoma.config.":pleroma"."Pleroma.Upload".filters =
map (pkgs.formats.elixirConf { }).lib.mkRaw [
"Pleroma.Upload.Filter.Exiftool"
"Pleroma.Upload.Filter.Dedupe"
"Pleroma.Upload.Filter.AnonymizeFilename"
];
}
```
## Migration from Pleroma {#modules-services-akkoma-migration-pleroma}
Pleroma instances can be migrated to Akkoma either by copying the database and upload data or by
pointing Akkoma to the existing data. The necessary database migrations are run automatically
during startup of the service.
The configuration has to be copy‐edited manually.
Depending on the size of the database, the initial migration may take a long time and exceed the
startup timeout of the system manager. To work around this issue one may adjust the startup timeout
{option}`systemd.services.akkoma.serviceConfig.TimeoutStartSec` or simply run the migrations
manually:
```ShellSession
pleroma_ctl migrate
```
### Copying data {#modules-services-akkoma-migration-pleroma-copy}
Copying the Pleroma data instead of re‐using it in place may permit easier reversion to Pleroma,
but allows the two data sets to diverge.
First disable Pleroma and then copy its database and upload data:
```ShellSession
# Create a copy of the database
nix-shell -p postgresql --run 'createdb -T pleroma akkoma'
# Copy upload data
mkdir /var/lib/akkoma
cp -R --reflink=auto /var/lib/pleroma/uploads /var/lib/akkoma/
```
After the data has been copied, enable the Akkoma service and verify that the migration has been
successful. If no longer required, the original data may then be deleted:
```ShellSession
# Delete original database
nix-shell -p postgresql --run 'dropdb pleroma'
# Delete original Pleroma state
rm -r /var/lib/pleroma
```
### Re‐using data {#modules-services-akkoma-migration-pleroma-reuse}
To re‐use the Pleroma data in place, disable Pleroma and enable Akkoma, pointing it to the
Pleroma database and upload directory.
```nix
{
# Adjust these settings according to the database name and upload directory path used by Pleroma
services.akkoma.config.":pleroma"."Pleroma.Repo".database = "pleroma";
services.akkoma.config.":pleroma".":instance".upload_dir = "/var/lib/pleroma/uploads";
}
```
Please keep in mind that after the Akkoma service has been started, any migrations applied by
Akkoma have to be rolled back before the database can be used again with Pleroma. This can be
achieved through `pleroma_ctl ecto.rollback`. Refer to the
[Ecto SQL documentation](https://hexdocs.pm/ecto_sql/Mix.Tasks.Ecto.Rollback.html) for
details.
## Advanced deployment options {#modules-services-akkoma-advanced-deployment}
### Confinement {#modules-services-akkoma-confinement}
The Akkoma systemd service may be confined to a chroot with
```nix
{
services.systemd.akkoma.confinement.enable = true;
}
```
Confinement of services is not generally supported in NixOS and therefore disabled by default.
Depending on the Akkoma configuration, the default confinement settings may be insufficient and
lead to subtle errors at run time, requiring adjustment:
Use
[{option}`services.systemd.akkoma.confinement.packages`](options.html#opt-systemd.services._name_.confinement.packages)
to make packages available in the chroot.
{option}`services.systemd.akkoma.serviceConfig.BindPaths` and
{option}`services.systemd.akkoma.serviceConfig.BindReadOnlyPaths` permit access to outside paths
through bind mounts. Refer to
[`BindPaths=`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#BindPaths=)
of {manpage}`systemd.exec(5)` for details.
### Distributed deployment {#modules-services-akkoma-distributed-deployment}
Being an Elixir application, Akkoma can be deployed in a distributed fashion.
This requires setting
[{option}`services.akkoma.dist.address`](options.html#opt-services.akkoma.dist.address) and
[{option}`services.akkoma.dist.cookie`](options.html#opt-services.akkoma.dist.cookie). The
specifics depend strongly on the deployment environment. For more information please check the
relevant [Erlang documentation](https://www.erlang.org/doc/reference_manual/distributed.html).
|