Modules

The framework’s features are provided as high-level NixOS modules, grouped by category under dnf/modules/ and documented in the module reference.

Create a module

Choose the category (dnf/modules/standard/<category>/ or mixin).
Write the file header according to the rules (see code headers).
Declare the options then the module config.
Regenerate (just generate) and test before committing.

For a self-hosted service (web UI, API, storage…), follow the dedicated guide Create a service module : reverse proxy, persistence, firewall, Kanidm SSO and per-host activation.

Anatomy of a module

A DNF module follows the classic NixOS pattern: a header, an options block and a config block activated by enable.

{ lib, config, ... }:
let
  cfg = config.darkone.service.hello;
in
{
  options.darkone.service.hello = {
    enable = lib.mkEnableOption "Enable the hello service";
    port = lib.mkOption {
      type = lib.types.port;
      default = 8080;
      description = "Listening port.";
    };
  };

  config = lib.mkIf cfg.enable {
    # ... actual configuration, only activated if enable = true
  };
}

Naming convention

All framework options live under the darkone namespace :

darkone.<category>.<name>.<option>

darkone.service.immich.enable : a service.
darkone.system.security.level : a system setting.
darkone.host.desktop.enable : a host profile (mixin).

Helpers (`dnfLib`)

dnfLib (defined in dnf/lib/) provides cross-cutting functions, injected into each module. The most useful ones:

Helper	Role
`extractServiceParams` / `buildServiceParams`	Read service parameters (domain, title, icon…).
`mkOidcContext` / `mkKanidmEndpoints`	Connect a service to Kanidm SSO (OIDC).
`mkInternalFirewall`	Open ports on the internal interface only.
`findHost` / `findService` / `isGateway` / `isHcs`	Query network topology.
`mkHomepageSection`	Declare the portal entry.
`mkIsActive`	Activate a security rule based on level/category.

The service registry

A service declares its topology in dnf/config/modules.nix (not in its .nix) : reverse proxy, uniqueness per zone, external access, automatic activation by host profile.

adguardhome = {
  uniquePerZone = true;
  activation.profiles.gateway.triggers.keys.adguardhome = [ "enable" ];
};

Flag	Default	Effect
`reverseProxy`	`true`	The service is exposed via Caddy.
`uniquePerZone`	`false`	Only one instance allowed per zone.
`externalAccess`	`false`	Reachable outside the zone (via the HCS).
`require`	`[ ]`	Services to enable on the same host (otherwise build error).
`activation.profiles.<profile>`		Enabled by default on hosts of a profile.

The generated `default.nix`

Each module folder has a default.nix that imports its files. It is generated by just generate (list of imports) → do not edit it.

just generate    # regenerates default.nix + var/generated/