# Akkoma {#module-services-akkoma}

[Akkoma](https://akkoma.dev/) is a lightweight ActivityPub microblogging server forked from Pleroma.

## Service configuration {#modules-services-akkoma-service-configuration}

The Elixir configuration file required by Akkoma is generated automatically from
[{option}`services.akkoma.config`](options.html#opt-services.akkoma.config). Secrets must be
included from external files outside of the Nix store by setting the configuration option to
an attribute set containing the attribute {option}`_secret` – a string pointing to the file
containing the actual value of the option.

For the mandatory configuration settings these secrets will be generated automatically if the
referenced file does not exist during startup, unless disabled through
[{option}`services.akkoma.initSecrets`](options.html#opt-services.akkoma.initSecrets).

The following configuration binds Akkoma to the Unix socket `/run/akkoma/socket`, expecting to
be run behind a HTTP proxy on `fediverse.example.com`.


```nix
{
  services.akkoma.enable = true;
  services.akkoma.config = {
    ":pleroma" = {
      ":instance" = {
        name = "My Akkoma instance";
        description = "More detailed description";
        email = "admin@example.com";
        registration_open = false;
      };

      "Pleroma.Web.Endpoint" = {
        url.host = "fediverse.example.com";
      };
    };
  };
}
```

Please refer to the [configuration cheat sheet](https://docs.akkoma.dev/stable/configuration/cheatsheet/)
for additional configuration options.

## User management {#modules-services-akkoma-user-management}

After the Akkoma service is running, the administration utility can be used to
[manage users](https://docs.akkoma.dev/stable/administration/CLI_tasks/user/). In particular an
administrative user can be created with

```ShellSession
$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>
```

## Proxy configuration {#modules-services-akkoma-proxy-configuration}

Although it is possible to expose Akkoma directly, it is common practice to operate it behind an
HTTP reverse proxy such as nginx.

```nix
{
  services.akkoma.nginx = {
    enableACME = true;
    forceSSL = true;
  };

  services.nginx = {
    enable = true;

    clientMaxBodySize = "16m";
    recommendedTlsSettings = true;
    recommendedOptimisation = true;
    recommendedGzipSettings = true;
  };
}
```

Please refer to [](#module-security-acme) for details on how to provision an SSL/TLS certificate.

### Media proxy {#modules-services-akkoma-media-proxy}

Without the media proxy function, Akkoma does not store any remote media like pictures or video
locally, and clients have to fetch them directly from the source server.

```nix
{
  # Enable nginx slice module distributed with Tengine
  services.nginx.package = pkgs.tengine;

  # Enable media proxy
  services.akkoma.config.":pleroma".":media_proxy" = {
    enabled = true;
    proxy_opts.redirect_on_failure = true;
  };

  # Adjust the persistent cache size as needed:
  #  Assuming an average object size of 128 KiB, around 1 MiB
  #  of memory is required for the key zone per GiB of cache.
  # Ensure that the cache directory exists and is writable by nginx.
  services.nginx.commonHttpConfig = ''
    proxy_cache_path /var/cache/nginx/cache/akkoma-media-cache
      levels= keys_zone=akkoma_media_cache:16m max_size=16g
      inactive=1y use_temp_path=off;
  '';

  services.akkoma.nginx = {
    locations."/proxy" = {
      proxyPass = "http://unix:/run/akkoma/socket";

      extraConfig = ''
        proxy_cache akkoma_media_cache;

        # Cache objects in slices of 1 MiB
        slice 1m;
        proxy_cache_key $host$uri$is_args$args$slice_range;
        proxy_set_header Range $slice_range;

        # Decouple proxy and upstream responses
        proxy_buffering on;
        proxy_cache_lock on;
        proxy_ignore_client_abort on;

        # Default cache times for various responses
        proxy_cache_valid 200 1y;