nixos-common

Shared NixOS library: three top-level option modules (per-host commonOptions, fleet-wide commonNetworking, a notification framework commonNotify), commonAdmins for declarative admin accounts, commonDeployUser for the unattended-deploy SSH user, commonFlakeUpdater for scheduled flake.lock refresh, a host builder, and a set of opt-in server modules (commonAcmeDns, commonAlloy, commonAuthentik, commonBackup, commonBackupInternal, commonBeszel, commonCaddy, commonContainerBase, commonCrowdsec, commonGatus, commonGrafana, commonHardening, commonHeadplane, commonHeadscale, commonHomeAssistant, commonHomepage, commonLoki, commonMailRelay, commonMonitoring, commonNextcloud, commonNtfy, commonOnlyOffice, commonPostgres, commonPrometheus, commonRedis, commonRustdesk, commonTailscale, commonUptimeKuma, commonVaultwarden) plus a few shell helpers.

Layout

Top-level dirs split into server/ and desktop/ where the distinction is meaningful; truly shared content stays at the top level of each dir.

flake.nix
docs/
  future-design.md
  modules/                — per-module docs
  lib/                    — per-helper docs
  scripts/                — per-script docs
lib/
  default.nix             — aggregator (top-level + server + desktop)
  mkHost.nix              — shared host builder
  server/
    caddySnippets.nix     — Caddy vhost builders
    gatusEndpoints.nix    — Gatus endpoint + alert builders
    monitorTargets.nix    — neutral monitor spec → Gatus/Kuma renderers
    serviceInventory.nix  — one inventory → status-page checks + dashboard tiles
    dumpDatabase.nix      — atomic mysqldump / pg_dump / sqlite .backup snippet
    authentik.nix         — Authentik OIDC-app / scope-mapping blueprint renderers
    backup/
      successReport.nix   — detailed backup-success report
      failureReport.nix   — detailed backup-failure report
  desktop/                — (empty)
modules/
  options.nix             — nixosModules.commonOptions
  admins.nix              — nixosModules.commonAdmins
  deploy-user.nix         — nixosModules.commonDeployUser
  networking.nix          — nixosModules.commonNetworking
  notify.nix              — nixosModules.commonNotify
  shell.nix               — nixosModules.commonShell
  flake-updater.nix       — nixosModules.commonFlakeUpdater
  update-check.nix        — nixosModules.commonUpdateCheck (umbrella)
  image-update-check.nix  — nixosModules.commonImageUpdateCheck
  service-update-check.nix — nixosModules.commonServiceUpdateCheck
  server/
    authentik/
      default.nix         — nixosModules.commonAuthentik (options + aggregator)
      postgres.nix        — wires authentik DB through commonPostgres
      redis.nix           — wires authentik cache through commonRedis
      containers.nix      — server/worker/LDAP OCI containers + podman net
    backup/
      default.nix         — nixosModules.commonBackup
      notify.nix          — success/failure notification wiring
      internal.nix        — nixosModules.commonBackupInternal (pull-based)
    acme-dns.nix          — nixosModules.commonAcmeDns
    container-base.nix    — nixosModules.commonContainerBase
    alloy.nix             — nixosModules.commonAlloy
    beszel.nix            — nixosModules.commonBeszel
    caddy.nix             — nixosModules.commonCaddy
    crowdsec/
      default.nix         — nixosModules.commonCrowdsec
      bouncer.nix         — nftables bouncer + auto-register oneshot
    gatus/
      default.nix         — nixosModules.commonGatus
      dispatch.nix        — type/macro dispatch tables for checks
    grafana.nix           — nixosModules.commonGrafana
    hardening.nix         — nixosModules.commonHardening
    headplane.nix         — nixosModules.commonHeadplane (OCI)
    headscale.nix         — nixosModules.commonHeadscale
    home-assistant.nix    — nixosModules.commonHomeAssistant
    homepage.nix          — nixosModules.commonHomepage (OCI, one per view)
    loki.nix              — nixosModules.commonLoki
    mail-relay.nix        — nixosModules.commonMailRelay
    monitoring.nix        — nixosModules.commonMonitoring (Gatus/Kuma dispatch)
    nextcloud/
      default.nix         — nixosModules.commonNextcloud
      oidc.nix            — user_oidc login + provider registration
    ntfy.nix              — nixosModules.commonNtfy
    onlyoffice.nix        — nixosModules.commonOnlyOffice
    postgres.nix          — nixosModules.commonPostgres (shared DB layer)
    prometheus.nix        — nixosModules.commonPrometheus
    redis.nix             — nixosModules.commonRedis (instances attrset)
    rustdesk.nix          — nixosModules.commonRustdesk
    tailscale.nix         — nixosModules.commonTailscale
    uptime-kuma.nix       — nixosModules.commonUptimeKuma
    vaultwarden/
      default.nix         — nixosModules.commonVaultwarden
      oci.nix             — OCI-container backend
      native.nix          — services.vaultwarden (native) backend
  desktop/                — (empty)
pkgs/
  server/                 — (empty)
  desktop/                — (empty)
.githooks/
  pre-commit              — runs the hygiene scans; enable via install-hooks.sh
scripts/
  check-pii.sh            — PII / secret / brand-name scan (for pre-commit)
  install-hooks.sh        — point git at .githooks/ (core.hooksPath)
  lib/
    common.sh             — shell helpers (source, no exec)
    sops.sh               — sops admin helpers + ensure_sops_keys + host-key/age
    mail.sh               — read-only mail-server health-check helpers
    deploy.sh             — nixos_anywhere_run deploy helper
    bootstrap.sh          — provider-agnostic host bootstrap (run_host_bootstrap + hooks)
    gcp.sh                — idempotent gcloud helpers (buckets, service accounts, IAM)
  server/
    colmena-checked.sh    — colmena wrapper gating on key passphrases
    check-deploy-keys.sh  — same audit, standalone (for pre-commit)
    closure-diff.sh       — zero-build drift prover (before vs work .drv)
    bootstrap-ssh-host.sh — bootstrap any SSH-reachable host via lib/bootstrap.sh
    prune-backups.sh      — restic forget/prune from an admin workstation
  desktop/                — (empty)

Per-feature docs

Each module / helper / script has a doc under docs/ explaining what it does, how to wire it, and any caveats. Source files keep only a short header pointing at the doc.

Consuming this flake

In the consumer's flake.nix, reference the repo by its git URL:

inputs.common.url = "git+ssh://git@forge.magnificent.nz/alister/nixos-common.git";

How to test against a consumer

To develop against a local checkout, point the input at a path instead:

inputs.common.url = "path:/home/alister/nixos-common";

Or one-shot without editing:

nixos-rebuild build --flake . \
  --override-input common path:/home/alister/nixos-common \
  --no-write-lock-file

Sanity-check the library evaluates

cd /home/alister/nixos-common
nix flake check

Conventions

• File size budget for code/config (.nix, .sh): aim for under 200 lines excluding comments and blank lines; 250 is the hard ceiling. If a helper exceeds it, split into smaller files under a same-named subdirectory with a default.nix aggregator (e.g. lib/server/caddy/{primitives,composites,snippets,default}.nix).
• Docs (.md) have no hard line limit — split a doc into meaningful sub-docs when it grows large enough that readers would benefit from focused files (rule of thumb: when distinct topics start competing inside one file, split by topic).
• File header comments are short — what the file is and a link to its doc. Detailed prose lives in docs/.
• Server / desktop split — lib/, modules/, pkgs/, scripts/ each have server/ and desktop/ subdirs for clearly one-sided content. Genuinely shared content stays at the top level of each dir.
• X-Served-By and other diagnostic headers are opt-in (default off). The library never emits identity-bearing headers unless the consumer explicitly enables them with a non-PII label.
• Mechanism, not policy. Modules expose options; consumer supplies the values. No hardcoded hostnames, IPs, sops paths, branding, or organisation names anywhere in this repo.

Consumer pattern: import-time data → specialArgs, not _module.args

Any value a consumer module needs while computing its imports — e.g. generating one container/import per entry in an inventory list, or importing a library module by path (inputs.common.nixosModules.X) — must be passed via specialArgs, never _module.args.

specialArgs are handed straight to the module function, so they exist during the import phase. _module.args only exist after the module fixpoint, so referencing one in imports causes infinite recursion ("... is not externally provided, so querying _module.args instead, requiring config"). Use _module.args only for values consumed inside config.

• Plain lib.nixosSystem / mkHost: pass them in specialArgs (mkHost already does specialArgs = { inherit inputs vars; }).
• colmena: use meta.specialArgs for fleet-wide values and meta.nodeSpecialArgs.<host> for per-host values. Do not put import-time inventory in a node's _module.args.