pyrox.dev
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
7The `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
15The `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
19First, the Postgresql service must be enabled in the NixOS configuration
20```
21services.postgresql = {
22 enable = true;
23 package = pkgs.postgresql_13;
24};
25```
26and activated with the usual
27```ShellSession
28$ nixos-rebuild switch
29```
30
31Then 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
38In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.
39
40This 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```
42services.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
80Secrets 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
84import Config
85
86config :pleroma, Pleroma.Web.Endpoint,
87 secret_key_base: "<the secret generated by pleroma_ctl>",
88 signing_salt: "<the secret generated by pleroma_ctl>"
89
90config :pleroma, Pleroma.Repo,
91 password: "<the secret generated by pleroma_ctl>"
92
93# Configure web push notifications
94config :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```
100Note 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
102The service can be enabled with the usual
103```ShellSession
104$ nixos-rebuild switch
105```
106
107The 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```
111and then accessing <http://localhost:4000> from a web browser.
112
113## Creating the admin user {#module-services-pleroma-admin-user}
114
115After 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
122In 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```
125security.acme = {
126 email = "root@example.net";
127 acceptTerms = true;
128};
129
130services.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```