NixOS
The flake that builds each Linux host and OS image, the fleet baseline each host shares, and the daily upgrade from main.
NixOS builds the lab's general-purpose Linux hosts from Nix code. Kubernetes nodes run Talos Linux.
One flake builds the NixOS hosts, OS images and Nix-built packages. The registry, nix/hosts/default.nix, lists them.
Parts#
| Part | Job | Where it runs |
|---|---|---|
| Registry | Lists each host, image and package. flake.nix derives its outputs from it. | Evaluation |
| Fleet baseline | The modules each deployable host gets, in nix/profiles/fleet.nix | Each host entry |
| sops-nix | Decrypts host secrets with the SSH host key | Hosts that import nix/system/sops.nix |
| Netboot | Serves x86 PXE boot and forge's signed RAM-boot image | spore |
| Talos boot | Serves folly's signed iPXE, HookOS and Talos ISO on the bootstrap VLAN | spore |
| Kea | Leases folly's netboot pool and names the signed iPXE, through the gateway's relay | spore |
| Tinkerbell | Runs folly's reprovisioning workflows and drives the nodes' BMCs | spore |
| Build host and cache | CI builds and the Nix caches | GitHub Actions, Cachix and forge |
Registry#
The header of nix/hosts/default.nix defines each field. kind sets the default baseline, and baseline overrides it, as in iso and netboot.
kind | Default baseline | Result |
|---|---|---|
host | Fleet baseline, nix/profiles/fleet.nix | A deployable system |
image | Image baseline, nix/profiles/base.nix | A built image, such as wsl |
package | None | A plain derivation, such as asterisk-image |
- A host turns off part of the fleet baseline with an explicit override, or with a
homelab.fleet.*option that the image baseline declares.
Auto-upgrade#
A host with auto-upgrade rebuilds from main at 03:37 local time, up to an hour later at random, and switches without a reboot. A failed build keeps the running generation.
| Hosts | Auto-upgrade | Set in |
|---|---|---|
| Pi 4 hosts (microSD root) | Off | nix/hardware/pi4/default.nix |
| Pi Zero hosts | Off | nix/profiles/pi-zero.nix |
| Every other host | On | nix/system/nixos.nix |
Rules#
- If you deploy a host change from a branch, merge it before the next auto-upgrade, or the upgrade removes it.
- Read addresses and names through
nix/lib/networks.nix,nix/lib/anchor.nixandnix/lib/fleet.nix, which project the topology files. A copied value goes stale when the topology file changes. - A new host cannot decrypt its SOPS file until its SSH host key is a recipient, as Manage SOPS secrets describes.
- Run
mise run nix:checkbefore a PR. It evaluates each configuration and runs the fleet assertions innix/lib/checks.nix, and a failure failsnix-ci.
Where it lives#
nix/hosts/: the registry and one file per hostnix/profiles/,nix/hardware/,nix/system/andnix/services/: baselines, board support, fleet modules and service modulesnix/images/: image modules.github/workflows/nix-ci.yaml: the PR flake check and the builds onmain
Related#
Linked from 8
- HostsEvery host in the homelab, with its role, site, hardware, OS and status, and how to reach it.
- How changes shipThe path each kind of change takes from a pull request to the running system, and the GitOps rule that no one changes live state by hand.
- PlatformThe shared systems that the apps and hosts depend on, and what applies each layer from git.
- Build host and cacheHow GitHub Actions builds NixOS closures and images, the Nix binary caches that hosts pull from, and the arm64 build role of forge.
- NetbootThe network boot service on spore, with TFTP and HTTP for folly's boot files and a signed RAM-boot image that forge falls back to.
- GlossaryThe lab-specific terms that the wiki pages use, what each means, and the page that defines it.
- TopologyThe two JSON files that hold the lab's network facts, the format rule they follow, and the Flux, Nix and OpenTofu code that reads them.
- Deploy a NixOS hostDeploy the NixOS configuration of a host from your machine or from GitHub Actions, or restore the previous generation.