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
  17 </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>
  25 services.postgresql = {
  26   enable = true;
  27   package = pkgs.postgresql_13;
  28 };
  29 </programlisting>
  30 and activated with the usual
  31 <programlisting>
  32 <prompt>$ </prompt>nixos-rebuild switch
  33 </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
  38 </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>
  46 services.pleroma = {
  47   enable = true;
  48   secretConfigFile = "/var/lib/pleroma/secrets.exs";
  49   configs = [
  50     ''
  51     import Config
  52
  53     config :pleroma, Pleroma.Web.Endpoint,
  54       url: [host: "pleroma.example.net", scheme: "https", port: 443],
  55       http: [ip: {127, 0, 0, 1}, port: 4000]
  56
  57     config :pleroma, :instance,
  58       name: "Test",
  59       email: "admin@example.net",
  60       notify_email: "admin@example.net",
  61       limit: 5000,
  62       registrations_open: true
  63
  64     config :pleroma, :media_proxy,
  65       enabled: false,
  66       redirect_on_failure: true
  67
  68     config :pleroma, Pleroma.Repo,
  69       adapter: Ecto.Adapters.Postgres,
  70       username: "pleroma",
  71       database: "pleroma",
  72       hostname: "localhost"
  73
  74     # Configure web push notifications
  75     config :web_push_encryption, :vapid_details,
  76       subject: "mailto:admin@example.net"
  77
  78     # ... TO CONTINUE ...
  79     ''
  80   ];
  81 };
  82 </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>
  86 # Pleroma instance passwords
  87
  88 import Config
  89
  90 config :pleroma, Pleroma.Web.Endpoint,
  91    secret_key_base: "&lt;the secret generated by pleroma_ctl&gt;",
  92    signing_salt: "&lt;the secret generated by pleroma_ctl&gt;"
  93
  94 config :pleroma, Pleroma.Repo,
  95   password: "&lt;the secret generated by pleroma_ctl&gt;"
  96
  97 # Configure web push notifications
  98 config :web_push_encryption, :vapid_details,
  99   public_key: "&lt;the secret generated by pleroma_ctl&gt;",
 100   private_key: "&lt;the secret generated by pleroma_ctl&gt;"
 101
 102 # ... TO CONTINUE ...
 103 </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
 109 </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
 114 </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 &lt;nickname&gt; &lt;email&gt;  --admin --moderator --password &lt;password&gt;
 122 </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>
 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 </programlisting>
 186   </para>
 187  </section>
 188 </chapter>