- Detailed initial config generation process.
- Detailed Nginx Configuration.
- Detailed private/public conf split.
docs: Improved documentation of Pleroma service
Secrets are only in the private file, and in a draft format for avoiding GitHub
complaints.
Fixed Nginx configuration.
docs: Improved the Nginx reverse proxy settings of Pleroma service
main
Massimo Zaniboni3 years agocommitted byFélix Baylac-Jacqué
<para>Note that you'll need to seed your database and upload your pleroma secrets to the path pointed by <literal>config.pleroma.secretConfigFile</literal>. You can find more informations about how to do that in the <linklinkend="module-services-pleroma-generate-config">next</link> section.</para>
</section>
<para>
<linkxlink:href="https://pleroma.social/">Pleroma</link> is a lightweight activity pub server.</para>
<title>Generating the Pleroma Config and Seed the Database</title>
<para>Before using this service, you'll need to generate your
server configuration and its associated database seed. The
<literal>pleroma_ctl</literal> CLI utility can help you with that. You
can start with <literal>pleroma_ctl instance gen --output config.exs
--output-psql setup.psql</literal>, this will prompt you some
questions and will generate both your config file and database initial
migration. </para>
<para>For more details about this configuration format, please have a look at the <linkxlink:href="https://docs-develop.pleroma.social/backend/configuration/cheatsheet/">upstream documentation</link>.</para>
<para>To seed your database, you can use the <literal>setup.psql</literal> file you just generated by running
<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 <linkxlink:href="https://docs-develop.pleroma.social/backend/configuration/cheatsheet/">upstream documentation</link>. Many refinements can be applied also after the service is running.</para>
<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 <linklinkend="opt-services.pleroma.configs">services.pleroma.configs</link> option contains the content of the file <literal>config.exs</literal>, generated <linklinkend="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>Secrets must be moved into a file pointed by <linklinkend="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
<para>After Pleroma service is running, all <linkxlink: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>
<sectionxml: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
<linkxlink:href="https://letsencrypt.org/">Let's Encrypt</link> for the TLS certificates
<programlisting>
sudo -u postgres psql -f setup.psql
</programlisting></para>
<para>In regard of the pleroma service configuration you also just generated, you'll need to split it in two parts. The "public" part, which do not contain any secrets and thus can be safely stored in the Nix store and its "private" counterpart containing some secrets (database password, endpoint secret key, salts, etc.).</para>
security.acme = {
email = "root@example.net";
acceptTerms = true;
};
<para>The public part will live in your NixOS machine configuration in the <linklinkend="opt-services.pleroma.configs">services.pleroma.configs</link> option. However, it's up to you to upload the secret pleroma configuration to the path pointed by <linklinkend="opt-services.pleroma.secretConfigFile">services.pleroma.secretConfigFile</link>. You can do that manually or rely on a third party tool such as <linkxlink:href="https://github.com/DBCDK/morph">Morph</link> or <linkxlink:href="https://github.com/NixOS/nixops">NixOps</link>.</para>
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.