<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pleroma">
<title>Pleroma</title>
<para>
<link xlink:href="https://pleroma.social/">Pleroma</link> is a
lightweight activity pub server.
</para>
<section xml:id="module-services-pleroma-generate-config">
<title>Generating the Pleroma config</title>
<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
</para>
<programlisting>
$ mkdir tmp-pleroma
$ cd tmp-pleroma
$ nix-shell -p pleroma-otp
$ pleroma_ctl instance gen --output config.exs --output-psql setup.psql
</programlisting>
<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>
</section>
<section xml:id="module-services-pleroma-initialize-db">
<title>Initializing the database</title>
<para>
First, the Postgresql service must be enabled in the NixOS
configuration
</para>
<programlisting>
services.postgresql = {
enable = true;
package = pkgs.postgresql_13;
};
</programlisting>
<para>
and activated with the usual
</para>
<programlisting>
$ nixos-rebuild switch
</programlisting>
<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
</para>
<programlisting>
$ sudo -u postgres psql -f setup.psql
</programlisting>
</section>
<section xml:id="module-services-pleroma-enable">
<title>Enabling the Pleroma service locally</title>
<para>
In this section we will enable the Pleroma service only locally,
so its configurations can be improved incrementally.
</para>
<para>
This is an example of configuration, where
<xref linkend="opt-services.pleroma.configs" /> 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.
</para>
<programlisting>
services.pleroma = {
enable = true;
secretConfigFile = "/var/lib/pleroma/secrets.exs";
configs = [
''
import Config
config :pleroma, Pleroma.Web.Endpoint,
url: [host: "pleroma.example.net", scheme: "https", port: 443],
http: [ip: {127, 0, 0, 1}, port: 4000]
config :pleroma, :instance,
name: "Test",
email: "admin@example.net",
notify_email: "admin@example.net",
limit: 5000,
registrations_open: true
config :pleroma, :media_proxy,
enabled: false,
redirect_on_failure: true
config :pleroma, Pleroma.Repo,
adapter: Ecto.Adapters.Postgres,
username: "pleroma",
database: "pleroma",
hostname: "localhost"
# Configure web push notifications
config :web_push_encryption, :vapid_details,
subject: "mailto:admin@example.net"
# ... TO CONTINUE ...
''
];
};
</programlisting>
<para>
Secrets must be moved into a file pointed by
<xref linkend="opt-services.pleroma.secretConfigFile" />, 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
</para>
<programlisting>
# Pleroma instance passwords
import Config
config :pleroma, Pleroma.Web.Endpoint,
secret_key_base: "<the secret generated by pleroma_ctl>",
signing_salt: "<the secret generated by pleroma_ctl>"
config :pleroma, Pleroma.Repo,
password: "<the secret generated by pleroma_ctl>"
# Configure web push notifications
config :web_push_encryption, :vapid_details,
public_key: "<the secret generated by pleroma_ctl>",
private_key: "<the secret generated by pleroma_ctl>"
# ... TO CONTINUE ...
</programlisting>
<para>
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>
<para>
The service can be enabled with the usual
</para>
<programlisting>
$ nixos-rebuild switch
</programlisting>
<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
</para>
<programlisting>
$ ssh -L 4000:localhost:4000 myuser@example.net
</programlisting>
<para>
and then accessing
<link xlink:href="http://localhost:4000">http://localhost:4000</link>
from a web browser.
</para>
</section>
<section xml:id="module-services-pleroma-admin-user">
<title>Creating the admin user</title>
<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
</para>
<programlisting>
$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>
</programlisting>
</section>
<section xml:id="module-services-pleroma-nginx">
<title>Configuring Nginx</title>
<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
<link xlink:href="https://letsencrypt.org/">Let’s Encrypt</link>
for the TLS certificates
</para>
<programlisting>
security.acme = {
email = "root@example.net";
acceptTerms = true;
};
services.nginx = {
enable = true;
addSSL = true;
recommendedTlsSettings = true;
recommendedOptimisation = true;
recommendedGzipSettings = true;
recommendedProxySettings = false;
# NOTE: if enabled, the NixOS proxy optimizations will override the Pleroma
# specific settings, and they will enter in conflict.
virtualHosts = {
"pleroma.example.net" = {
http2 = true;
enableACME = true;
forceSSL = true;
locations."/" = {
proxyPass = "http://127.0.0.1:4000";
extraConfig = ''
etag on;
gzip on;
add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow-Methods' 'POST, PUT, DELETE, GET, PATCH, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Idempotency-Key' always;
add_header 'Access-Control-Expose-Headers' 'Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id' always;
if ($request_method = OPTIONS) {
return 204;
}
add_header X-XSS-Protection "1; mode=block";
add_header X-Permitted-Cross-Domain-Policies none;
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header Referrer-Policy same-origin;
add_header X-Download-Options noopen;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
client_max_body_size 16m;
# NOTE: increase if users need to upload very big files
'';
};
};
};
};
</programlisting>
</section>
</chapter>