nixos/README.md

NixOS LAN Configurations

Flake-based NixOS configuration repository for Wayne's LAN servers and workstation.

Hosts

Targets are named <platform>-<buildtype>, generated from two orthogonal pieces composed in flake.nix:

• Platforms (what it runs on): linode, proxmox, lxc
• Build types (what it's for): minimal, nix-cache, server, docker, gui, pxe-boot

Not every combination exists — pxe-boot has no linode variant, since PXE/DHCP/TFTP need LAN L2 adjacency that a Linode VPS doesn't have. The full list:

Target	Purpose
linode-minimal	Minimal NixOS host profile on a Linode VPS (real, deployed)
proxmox-minimal	Minimal NixOS host profile on Proxmox (real, deployed — previously the flat nix-minimal target)
lxc-minimal	Minimal NixOS host profile in a Proxmox LXC container
linode-nix-cache / proxmox-nix-cache / lxc-nix-cache	Local Nix binary cache and remote builder (proxmox-nix-cache is the real, deployed one — previously the flat nix-cache target)
linode-server / proxmox-server / lxc-server	Storage, NFS, backup, and monitoring exporter host (proxmox-server is the real, deployed one — previously the flat server target)
linode-docker / proxmox-docker / lxc-docker	Docker host for the main container stack (proxmox-docker is the real, deployed one — previously the flat docker target)
linode-gui / proxmox-gui / lxc-gui	Cinnamon desktop workstation (proxmox-gui is the real, deployed one — previously the flat nixos target)
proxmox-pxe-boot / lxc-pxe-boot	HTTP/iPXE boot asset host (proxmox-pxe-boot is the real, deployed one — previously the flat pxe-boot target)

Each buildtype's hosts/<name>/host.nix carries the per-machine identity (hostname, hostId, per-machine secrets, system.stateVersion) that must stay fixed regardless of which platform it's built for — see flake-target-refactor-spec.md for the full rationale. Every deployed host stamps its own active target name into /etc/flake-target at build time, so nixos-rebuild switch --flake .#$(cat /etc/flake-target) always picks up the right one even after a platform migration changes the flake attribute name.

List hosts with:

nix eval --json .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]'

Layout

Path	Purpose
flake.nix	Flake inputs, the mkTarget platform × build-type generator, and nixosConfigurations outputs
variables.nix	Single source of truth for shared values (LAN domain/CIDR, hostnames, timezone, primary username, storage root, ...) — passed to every module and Home Manager config as the vars argument via specialArgs/extraSpecialArgs
hosts/<name>/host.nix	Per-machine identity: hostname, hostId, per-machine secrets, system.stateVersion
hosts/nixos/home.nix	Workstation-specific Home Manager config (used by the gui build type)
modules/platforms/	Platform-specific config: virtualisation guest tools, boot method, hardware config (linode.nix, proxmox.nix, lxc.nix)
modules/build-types/	Build-type-specific config: what makes a system minimal/server/docker/gui/pxe-boot/nix-cache
modules/common/	Shared NixOS config, Home Manager, aliases imported by every host
modules/nix-cache/	Binary cache and remote builder client/server modules
modules/installer/	Auto-installer environment (ISO, also served as PXE netboot) — see docs/auto-installer.md
host-keys/	Gitignored, locally-generated SSH host keys for the auto-installer — see docs/auto-installer.md
docs/	Operational notes for cache, builders, lock updates, boot services, the auto-installer, and Proxmox image builds
scripts/	Codex setup, validation, and host-key-prep helpers

Validation

Safe validation commands for Codex and local review:

bash scripts/codex-setup.sh
bash scripts/codex-maintenance.sh dry-run
bash scripts/codex-maintenance.sh

For individual host evaluation:

nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw

Use nix build --dry-run --no-link when build planning is needed. Do not run deployment, install, disk formatting, mount, or reboot commands from automated review sessions.

Operations

• Host rebuilds should consume the committed flake.lock.
• Routine dependency updates should happen through the flake lock automation described in docs/flake-lock-automation.md.
• nix-cache serves substitutes over HTTP and can act as a remote builder for client hosts.
• pxe-boot serves iPXE boot files over HTTP from /srv/pxe.

Deploying a new host

Three different paths depending on target, none of them involving a manual nixos-rebuild switch from this repo:

• Most hosts: boot the auto-installer, pick the target from its menu — see docs/auto-installer.md.
• lxc-* targets: not installed at all — build a ready-to-run container tarball and pct restore it directly. docs/auto-installer.md covers why (and the installer's menu excludes them for the same reason).
• proxmox-* targets: can alternatively be built as a standalone .raw disk image and attached to a new VM with no install step — see docs/proxmox-images.md.

Security Notes

Do not commit tokens, private keys, live credentials, or new password hashes as plaintext. Secrets are managed with sops-nix: encrypted files live under secrets/, recipients (per-host age keys derived from each host's existing SSH host key, plus an admin key) are declared in .sops.yaml. To add or edit a secret:

nix-shell -p sops --run "sops secrets/<file>.yaml"

then reference it from a module via config.sops.secrets."<name>".path (or sops.templates for values that need to be embedded in a rendered config file, e.g. nix.conf's access-tokens). Never write a secret value directly into a tracked .nix file. A pre-commit hook (.githooks/, enabled via git config core.hooksPath .githooks, done automatically by scripts/codex-setup.sh) runs gitleaks protect --staged to catch mistakes before they're committed.

The auto-installer environment is the one deliberate exception to sops-nix-everywhere: it has a hardcoded login password instead (no stable per-boot host key for sops-nix to derive from on ephemeral media) — see "Host keys" in docs/auto-installer.md for why, and how the private keys it does pre-seed for target hosts stay out of git via the gitignored host-keys/ directory.

This repository's git history still contains secrets committed before this migration (see remove-sensetive-info-refactor.md) — those are being scrubbed and rotated separately; don't treat the repo as safe to make public until that's finished.