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 ```nix
  21 {
  22   services.postgresql = {
  23     enable = true;
  24     package = pkgs.postgresql_13;
  25   };
  26 }
  27 ```
  28 and activated with the usual
  29 ```ShellSession
  30 $ nixos-rebuild switch
  31 ```
  32
  33 Then you can create and seed the database, using the `setup.psql` file that you generated in the previous section, by running
  34 ```ShellSession
  35 $ sudo -u postgres psql -f setup.psql
  36 ```
  37
  38 ## Enabling the Pleroma service locally {#module-services-pleroma-enable}
  39
  40 In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.
  41
  42 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.
  43 ```nix
  44 {
  45   services.pleroma = {
  46     enable = true;
  47     secretConfigFile = "/var/lib/pleroma/secrets.exs";
  48     configs = [
  49       ''
  50       import Config
  51
  52       config :pleroma, Pleroma.Web.Endpoint,
  53         url: [host: "pleroma.example.net", scheme: "https", port: 443],
  54         http: [ip: {127, 0, 0, 1}, port: 4000]
  55
  56       config :pleroma, :instance,
  57         name: "Test",
  58         email: "admin@example.net",
  59         notify_email: "admin@example.net",
  60         limit: 5000,
  61         registrations_open: true
  62
  63       config :pleroma, :media_proxy,
  64         enabled: false,
  65         redirect_on_failure: true
  66
  67       config :pleroma, Pleroma.Repo,
  68         adapter: Ecto.Adapters.Postgres,
  69         username: "pleroma",
  70         database: "pleroma",
  71         hostname: "localhost"
  72
  73       # Configure web push notifications
  74       config :web_push_encryption, :vapid_details,
  75         subject: "mailto:admin@example.net"
  76
  77       # ... TO CONTINUE ...
  78       ''
  79     ];
  80   };
  81 }
  82 ```
  83
  84 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
  85 ```
  86 # Pleroma instance passwords
  87
  88 import Config
  89
  90 config :pleroma, Pleroma.Web.Endpoint,
  91    secret_key_base: "<the secret generated by pleroma_ctl>",
  92    signing_salt: "<the secret generated by pleroma_ctl>"
  93
  94 config :pleroma, Pleroma.Repo,
  95   password: "<the secret generated by pleroma_ctl>"
  96
  97 # Configure web push notifications
  98 config :web_push_encryption, :vapid_details,
  99   public_key: "<the secret generated by pleroma_ctl>",
 100   private_key: "<the secret generated by pleroma_ctl>"
 101
 102 # ... TO CONTINUE ...
 103 ```
 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.
 105
 106 The service can be enabled with the usual
 107 ```ShellSession
 108 $ nixos-rebuild switch
 109 ```
 110
 111 The service is accessible only from the local `127.0.0.1:4000` port. It can be tested using a port forwarding like this
 112 ```ShellSession
 113 $ ssh -L 4000:localhost:4000 myuser@example.net
 114 ```
 115 and then accessing <http://localhost:4000> from a web browser.
 116
 117 ## Creating the admin user {#module-services-pleroma-admin-user}
 118
 119 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
 120 ```ShellSession
 121 $ pleroma_ctl user new <nickname> <email>  --admin --moderator --password <password>
 122 ```
 123
 124 ## Configuring Nginx {#module-services-pleroma-nginx}
 125
 126 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
 127 [Let's Encrypt](https://letsencrypt.org/) for the TLS certificates
 128 ```nix
 129 {
 130   security.acme = {
 131     email = "root@example.net";
 132     acceptTerms = true;
 133   };
 134
 135   services.nginx = {
 136     enable = true;
 137     addSSL = true;
 138
 139     recommendedTlsSettings = true;
 140     recommendedOptimisation = true;
 141     recommendedGzipSettings = true;
 142
 143     recommendedProxySettings = false;
 144     # NOTE: if enabled, the NixOS proxy optimizations will override the Pleroma
 145     # specific settings, and they will enter in conflict.
 146
 147     virtualHosts = {
 148       "pleroma.example.net" = {
 149         http2 = true;
 150         enableACME = true;
 151         forceSSL = true;
 152
 153         locations."/" = {
 154           proxyPass = "http://127.0.0.1:4000";
 155
 156           extraConfig = ''
 157             etag on;
 158             gzip on;
 159
 160             add_header 'Access-Control-Allow-Origin' '*' always;
 161             add_header 'Access-Control-Allow-Methods' 'POST, PUT, DELETE, GET, PATCH, OPTIONS' always;
 162             add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Idempotency-Key' always;
 163             add_header 'Access-Control-Expose-Headers' 'Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id' always;
 164             if ($request_method = OPTIONS) {
 165               return 204;
 166             }
 167             add_header X-XSS-Protection "1; mode=block";
 168             add_header X-Permitted-Cross-Domain-Policies none;
 169             add_header X-Frame-Options DENY;
 170             add_header X-Content-Type-Options nosniff;
 171             add_header Referrer-Policy same-origin;
 172             add_header X-Download-Options noopen;
 173             proxy_http_version 1.1;
 174             proxy_set_header Upgrade $http_upgrade;
 175             proxy_set_header Connection "upgrade";
 176             proxy_set_header Host $host;
 177
 178             client_max_body_size 16m;
 179             # NOTE: increase if users need to upload very big files
 180           '';
 181         };
 182       };
 183     };
 184   };
 185 }
 186 ```