# Pleroma {#module-services-pleroma}

[Pleroma](https://pleroma.social/) is a lightweight activity pub server.

## Generating the Pleroma config {#module-services-pleroma-generate-config}

The `pleroma_ctl` CLI utility will prompt you some questions and it will generate an initial config file. This is an example of usage
```ShellSession
$ mkdir tmp-pleroma
$ cd tmp-pleroma
$ nix-shell -p pleroma-otp
$ pleroma_ctl instance gen --output config.exs --output-psql setup.psql
```

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.

## Initializing the database {#module-services-pleroma-initialize-db}

First, the Postgresql service must be enabled in the NixOS configuration
```nix
{
  services.postgresql = {
    enable = true;
    package = pkgs.postgresql_13;
  };
}
```
and activated with the usual
```ShellSession
$ nixos-rebuild switch
```

Then you can create and seed the database, using the `setup.psql` file that you generated in the previous section, by running
```ShellSession
$ sudo -u postgres psql -f setup.psql
```

## Enabling the Pleroma service locally {#module-services-pleroma-enable}

In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.

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.
```nix
{
  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 ...
      ''
    ];
  };
}
```

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
```
# 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>"