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>
41 lines
2.5 KiB
Markdown
41 lines
2.5 KiB
Markdown
---
|
|
name: install-box
|
|
description: >-
|
|
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`](../../../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-config` is a shell alias**, so it needs `installer-shell bash -lic show-hw-config`.
|
|
Run it twice: once early for the kernel-module lists, once after mounting for the filesystems.
|
|
- **`git add` the 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>`**, not `build-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 means
|
|
`my.secrets.key` can 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.user` pulls in
|
|
`user-passwd.txt` by default — so setting `my.secrets.key` always requires
|
|
`ragenix --rekey-one secrets/user-passwd.txt.age`. Check with
|
|
`nix eval .#nixosConfigurations.<host>.config.age.secrets --apply builtins.attrNames` rather than
|
|
assuming there is nothing to do. Re-encrypt selectively; `ragenix --rekey` rewrites every secret
|
|
in `secrets/` 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.md` prose. Don't hand-edit anything
|
|
between `<!-- ... -->` markers.
|