dev/nixfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
e7122b8862ae9059e442c73400192fb22a03070d
nixfiles/docs/misc/installer.md
T
jackos1998 e7122b8862
CI / Check, build and cache nixfiles (push) Successful in 56m36s
Details
Update docs / update (push) Successful in 1m11s
Details
docs: Add box installation procedure 
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>
2026-08-19 01:30:59 +01:00

2.4 KiB
Raw Blame History

installer

The custom NixOS installer image used to bootstrap new boxes.

Role

  • Defines nixos.systems.installer, a minimal server system rendered as a bootable ISO via config.my.buildAs.iso (my.asISO); the same base can also be built as a kexec or netboot tree.
  • Build it with the devshell commands: build-iso installer (or build-kexec installer / build-netboot installer). The update-installer command force-tags installer to trigger a release rebuild in CI.

Image contents

  • Broad hardware support (my.build.allHardware pulls in the nixpkgs all-hardware profile); EFI- and USB-bootable, zstd-compressed squashfs. Volume ID jackos-<release>-<arch>, menu label "/dev/player0 Installer", image base name jackos-installer.
  • Root SSH with the deploy key authorized (PermitRootLogin prohibit-password); a random installer-<hex> hostname is set at boot.
  • INSTALL_ROOT=/mnt in the session environment, plus a show-hw-config alias wrapping nixos-generate-config --show-hardware-config --root $INSTALL_ROOT.
  • NixOS documentation enabled, NetworkManager available but not started at boot (run systemctl start NetworkManager, then nmtui), GC and memory-overcommit tuning for low-memory targets, LVM thin and NFS support.
  • Identifies itself as VARIANT_ID=installer in /etc/os-release, and leaves the target's persistent pstore entries alone (Unlink=no) so an install doesn't evacuate them.
  • No regular user (my.user.enable = false), no tmpfs-root management, no NAT, and not a deploy target (my.deploy.enable = false).

Installing a box

The end-to-end procedure — hardware inventory, partitioning, writing the box config, installing and documenting it — is in install-box.md. The devshell's installer commands (devshell/install.nix) drive an install over SSH against a booted installer reachable at $INSTALLER:

  • installer-shell — get a shell on the installer.
  • do-install <system> — builds the system's toplevel, nix copys the closure to the installer's $INSTALL_ROOT remote store, sets the system profile, touches /etc/NIXOS, and runs switch-to-configuration boot with NIXOS_INSTALL_BOOTLOADER=1 (skip the bootloader with --no-bootloader, skip substitution with --no-substitute).
Reference in New Issue View Git Blame Copy Permalink