diff options
Diffstat (limited to 'nixos/modules/services/networking/pleroma.xml')
| -rw-r--r-- | nixos/modules/services/networking/pleroma.xml | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/nixos/modules/services/networking/pleroma.xml b/nixos/modules/services/networking/pleroma.xml new file mode 100644 index 00000000000..ad0a481af28 --- /dev/null +++ b/nixos/modules/services/networking/pleroma.xml @@ -0,0 +1,188 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + 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 +<programlisting> +<prompt>$ </prompt>mkdir tmp-pleroma +<prompt>$ </prompt>cd tmp-pleroma +<prompt>$ </prompt>nix-shell -p pleroma-otp +<prompt>$ </prompt>pleroma_ctl instance gen --output config.exs --output-psql setup.psql +</programlisting> + </para> + <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 +<programlisting> +services.postgresql = { + enable = true; + package = pkgs.postgresql_13; +}; +</programlisting> +and activated with the usual +<programlisting> +<prompt>$ </prompt>nixos-rebuild switch +</programlisting> + </para> + <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 +<programlisting> +<prompt>$ </prompt>sudo -u postgres psql -f setup.psql +</programlisting> + </para> + </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 <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. +<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> + <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 +<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> + 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 +<programlisting> +<prompt>$ </prompt>nixos-rebuild switch +</programlisting> + </para> + <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 +<programlisting> +<prompt>$ </prompt>ssh -L 4000:localhost:4000 myuser@example.net +</programlisting> +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 +<programlisting> +<prompt>$ </prompt>pleroma_ctl user new <nickname> <email> --admin --moderator --password <password> +</programlisting> + </para> + </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 +<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> + </para> + </section> +</chapter> |