nixos/flake-target-refactor-spec.md

Spec: Refactor Flake Targets into Platform × Build-Type Matrix

Status: implemented. flake.nix's generatedTargets/mkTarget and modules/platforms/*/modules/build-types/* are the result of this spec — kept here for historical rationale only (referenced from CLAUDE.md's "Composition pattern" section), not as an active or open plan. The "Open Questions" below were resolved during implementation; don't treat them as outstanding. A tailscale-exit-node build type was added later, beyond this spec's original scope.

Context

The flake at ~/nixos currently defines these output targets (flat, ad-hoc naming):

• docker
• linode-minimal
• nix-cache
• nix-minimal
• nixos
• server
• pxe-boot

Some already follow a platform-buildtype convention (linode-minimal), most don't. ~/nix-auto-installer is a related repo and should be checked for any coupling to these target names (scripts, docs, CI, or install automation that reference them by name) before renaming anything.

Goal

Restructure the flake so targets are generated from two orthogonal concepts:

Build types (what the system is for):

• minimal
• nix-cache
• server
• docker
• pxe-boot
• gui

Platforms (what it's deployed on):

• linode (Linode VM)
• proxmox (Proxmox VM)
• lxc (Proxmox LXC container)

Final targets should be named consistently as <platform>-<buildtype>, e.g.:

linode-minimal    proxmox-minimal    lxc-minimal
linode-nix-cache  proxmox-nix-cache  lxc-nix-cache
linode-server     proxmox-server     lxc-server
linode-docker     proxmox-docker     lxc-docker
linode-pxe-boot   proxmox-pxe-boot   lxc-pxe-boot
linode-gui        proxmox-gui        lxc-gui

That's the full matrix (18 targets) if every build type applies to every platform. See Open Questions below — some combinations may not make sense and should be confirmed with me before being built out, not silently included or dropped.

Migration mapping (old → new)

Old target	New target	Notes
linode-minimal	linode-minimal	Already correct, keep as-is
nix-minimal	likely proxmox-minimal or a platform-less base module	Ambiguous — see Open Questions
nix-cache	base module consumed by linode-nix-cache, proxmox-nix-cache, lxc-nix-cache	Currently platform-less; needs to become a build-type module, not a standalone target
server	base module consumed by linode-server, proxmox-server, lxc-server	Same as above
docker	base module consumed by linode-docker, proxmox-docker, lxc-docker	Confirm docker actually makes sense as an LXC/VM guest build vs. a standalone container image — see Open Questions
pxe-boot	TBD — may stay a single target rather than a per-platform one	See Open Questions
nixos	TBD — unclear what this maps to in the new scheme	See Open Questions

Open Questions (Claude Code: raise these with me before implementing, don't guess)

1. nixos target — what is this currently used for (bare metal install, dev shell, template)? It doesn't obviously map to any of the six build types.
2. nix-minimal vs linode-minimal — are these two different things, or is nix-minimal a leftover/duplicate?
3. pxe-boot and gui across all three platforms — does PXE boot make sense for an LXC container or a cloud VM (Linode), or is it inherently bare-metal/ network-boot only and should remain a single non-platform target? Does gui make sense inside an LXC container?
4. docker as a build type — is this "a NixOS host configured to run Docker" (which would sensibly have linode/proxmox/lxc variants), or "a Docker container image built by the flake" (which wouldn't take a platform prefix at all, since it doesn't run on Linode/Proxmox/LXC as a guest OS)? These are structurally different and change how it should be wired in.
5. Confirm whether all 18 combinations should actually exist, or whether this is meant to produce only the combinations that are genuinely useful (e.g. maybe no one needs lxc-pxe-boot).

Implementation approach

1. Inventory first. Read the current flake.nix and any nixosConfigurations/ modules structure. Map every existing target to what module(s) it actually pulls in. Don't assume — confirm against the real file contents.
2. Separate build-type and platform into their own module directories, e.g.:

   modules/build-types/minimal.nix
   modules/build-types/nix-cache.nix
   modules/build-types/server.nix
   modules/build-types/docker.nix
   modules/build-types/pxe-boot.nix
   modules/build-types/gui.nix
   
   modules/platforms/linode.nix
   modules/platforms/proxmox.nix
   modules/platforms/lxc.nix
   

   Build-type modules should contain only what makes a system "minimal" vs "server" vs "gui", etc. Platform modules should contain only what's specific to running as a Linode VM vs Proxmox VM vs LXC container (virtualisation guest tools, boot method, filesystem/image format, LXC-specific constraints like no kernel modules, etc).
3. Generate the target matrix programmatically in flake.nix rather than hand-writing 18 near-identical nixosConfigurations entries — e.g. a small function that takes a platform name and build-type name, composes the two modules plus any shared base module, and produces the named output. This keeps future build types/platforms a one-line addition rather than a copy-paste job.
4. Only build combinations we've confirmed make sense (see Open Questions) — don't emit all 18 by default if some are structurally invalid.
5. Preserve existing working configs during the transition. Don't delete the old target names until their replacements build successfully — rename/alias at the end, not the start, so there's no window where the flake is broken.

Verification

For every new target produced:

nix flake check
nix build .#nixosConfigurations.<target>.config.system.build.toplevel

Confirm each builds without evaluation errors before considering it done. If a target fails to build, report which one and why rather than silently skipping it.

Deliverables

• Refactored flake.nix using the composed module + generated-matrix approach.
• New modules/build-types/*.nix and modules/platforms/*.nix files.
• Old flat target names removed only after their replacements are verified.
• A short README.md (or section in existing docs) listing the final target names and what each one is for.
• A summary at the end of what changed, what was removed, and any of the Open Questions above that got resolved differently than expected.

Out of scope

• Don't touch ~/nix-auto-installer contents beyond checking it for references to the old target names — if changes there are needed, flag them, don't make them without confirming.
• Don't add new build types or platforms beyond the ones listed here.