The generator

The generator (src/generator/, written in Rust) transforms the declarative configuration etc/config.yaml into Nix code consumed by the framework.

From YAML to Nix

• Input: etc/config.yaml → hosts, users, network, services.
• Output: var/generated/ → hosts.nix, users.nix, network.nix.

These files are generated: never edit them by hand. To regenerate them after a configuration change:

just generate

Generated files

var/generated/ and the */ref/modules.mdx pages are produced by tools. Edit the generator or the source, never the output.

The flow

A single source of truth (etc/config.yaml) is transformed into deterministic Nix code, consumed by the framework via flake.nix.

Commands

The generator exposes one command per target. just generate chains them all together; you can also invoke a single one.

Command	Output	Content
hosts	var/generated/hosts.nix	Hosts: profiles, services, colmena tags.
users	var/generated/users.nix	Users: profiles, groups.
network	var/generated/network.nix	Topology: zones, DNS, VPN.
disko	usr/machines/<hôte>/disko.nix	Per-host partitioning.
doc	*/ref/modules.mdx	Module reference (documentation).

just generate          # regenerate everything (via the Justfile)
just codegen           # regenerate only the module reference (doc)

Reading modules

The generator also reads dnf/config/modules.nix (service topology): it applies flags (reverse proxy, uniqueness…) and validates require dependencies → a required service must be enabled on the same host, otherwise generation fails. For the doc command, it parses Nix sources (the rnix parser) to extract options and headers. Documenting an option = describing it in the module, then just codegen.

Execution context

The generator runs in two modes, chosen automatically:

• Co-development (sources + cargo present) → cargo run: fast compilation loop while modifying the generator.
• Release (no local checkout) → dnf-generator binary provided by the framework’s devShell (nix develop github:darkone-linux/...).

Deterministic output

Files are formatted with nixfmt -sv: a diff between two runs reflects only real configuration changes.