jackos1998
e7122b8862
Canonical, agent-agnostic procedure for bringing a new box into the flake, from a booted installer through to a deployable system, plus a thin Claude Code skill pointing at it -- same split as the nixpkgs upgrade procedure. Records the conventions that were not written down anywhere: sgdisk plus an LVM PV for the nix and persist volumes, adopting the installer's SSH host keys so secrets can be encrypted before first boot, and taking whatever show-hw-config emits that the flake's own modules do not already set. Also notes in AGENTS.md that a changed recipient list should be re-encrypted per file with ragenix --rekey-one; --rekey rewrites every secret in secrets/ and buries the actual change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.5 KiB
2.5 KiB
name, description
| name | description |
|---|---|
| install-box | Install a new NixOS box into this flake, from bare hardware booted into the custom installer through to a deployable system: probe the hardware, partition and format the disks, write the box config and flake entry, run do-install, and document the box. Use when the user wants to install, bootstrap, provision or add a new box/host/machine. |
Install a box
The canonical, agent-agnostic procedure lives in the repo at
docs/install-box.md. Read it and follow the phases in order.
Key reminders (see the doc for the full steps):
- It is guided, not automated — stop at the ⏸ points: settling what the box actually is
(Phase 1), wiping and partitioning disks (Phase 3), and running
do-install(Phase 6). The user often wants to do the install step by hand. - Phase 1 is not derivable from the hardware. Name, site, role, channel and whether the box gets assignments now all have to come from the user. Ask before writing files.
show-hw-configis a shell alias, so it needsinstaller-shell bash -lic show-hw-config. Run it twice: once early for the kernel-module lists, once after mounting for the filesystems.git addthe new box directory before evaluating — the flake reads through git, and an untracked path fails as "Path … is not tracked by Git" rather than as a Nix error.- Validate with
check-system <host>, notbuild-system— evaluation catches module and option errors cheaply. - Seed the SSH host key from the installer (Phase 3) by copying
/etc/ssh/ssh_host_*onto the persist volume. The installer regenerates them each boot, so they are safe to adopt, and it meansmy.secrets.keycan be set and secrets encrypted before the install rather than after first boot. - Every box declares a secret even when its own config declares none —
my.userpulls inuser-passwd.txtby default — so settingmy.secrets.keyalways requiresragenix --rekey-one secrets/user-passwd.txt.age. Check withnix eval .#nixosConfigurations.<host>.config.age.secrets --apply builtins.attrNamesrather than assuming there is nothing to do. Re-encrypt selectively;ragenix --rekeyrewrites every secret insecrets/and drowns the real change in churn. - Take everything useful out of
show-hw-config, not just the modules and filesystems — drop an option only when a nixfiles module already sets it. - Finish with Phase 8: box page, site index row,
networking.mdprose. Don't hand-edit anything between<!-- ... -->markers.