ADR-0013: Decide The Homelab Platform Substrate
Status
Section titled “Status”Proposed.
Context
Section titled “Context”The first homelab platform design assumed Proxmox as the bare-metal substrate. That assumption produced useful early material: first-boot runbooks, Terraform-oriented VM provisioning, storage notes and host hardening tasks.
The substrate is now reopened because the platform must be reproducible, declarative and maintainable before the Kubernetes workload plane, trusted admin plane and GOAD isolation are automated. A NixOS host running Incus may offer a cleaner declarative baseline than a Proxmox-first model, especially for host configuration, package pinning, user management and repeatable recovery.
Decision Drivers
Section titled “Decision Drivers”| Driver | Why It Matters |
|---|---|
| Reproducibility | The host must be rebuildable from versioned configuration, not only post-install scripts. |
| Operational clarity | Recruitable evidence comes from a design that explains lifecycle, backup and recovery tradeoffs. |
| Security hardening | SSH, firewalling, users, updates, audit tooling and kernel security features must be controlled. |
| Workload fit | The substrate must support OPNsense or firewall routing, Kubernetes nodes, trusted services and GOAD isolation. |
| Storage model | SSD/HDD placement, backups, snapshots and restore drills must be explicit without claiming false physical HA. |
| Automation surface | Terraform, Ansible, Packer, Nix and Incus automation must stay testable and idempotent. |
| Learning value | The platform should demonstrate tools that are credible in DevSecOps and platform engineering roles. |
Options
Section titled “Options”Option A: Proxmox VE Substrate
Section titled “Option A: Proxmox VE Substrate”Proxmox provides a mature virtualization platform with a strong UI, common homelab adoption, VM templates, snapshots and Terraform provider support. It fits OPNsense VMs, Windows-heavy GOAD automation and Kubernetes node VMs well.
Tradeoffs:
- Host reproducibility depends on installer answers plus post-install automation, not a fully declarative operating system.
- Some host state remains outside Terraform and Ansible unless carefully audited.
- A single physical host still cannot provide real physical HA, even if VM or Kubernetes control-plane resilience is demonstrated.
Option B: NixOS Host With Incus
Section titled “Option B: NixOS Host With Incus”NixOS can make the host itself declarative: packages, services, users, SSH, firewalling and hardening are expressed in versioned configuration. Incus can manage system containers and virtual machines for workloads that need stronger isolation than containers but less platform weight than a Proxmox installation.
Tradeoffs:
- The operational model is less common in traditional homelab material and may require stronger documentation for reviewers.
- Windows and GOAD VM automation must be validated carefully against Incus capabilities and image/template workflows.
- Network design, VLAN tagging and firewall placement need proof before the platform can replace the Proxmox assumptions.
Evaluation Plan
Section titled “Evaluation Plan”- Inventory existing Proxmox-specific files and public docs.
- Define the minimum platform contract: firewall routing, admin plane, Kubernetes nodes, GOAD isolation, backups and remote access.
- Build a comparison matrix for Proxmox and NixOS plus Incus against the decision drivers above.
- Prototype only reversible, non-production changes first.
- Select one substrate and update
homelab-platform,portfolio-docsand repository roadmaps accordingly.
Consequences
Section titled “Consequences”- Public documentation must no longer present Proxmox as the final substrate.
- Existing Proxmox runbooks remain current-state or historical material until this ADR is accepted.
- Roadmaps must include a cleanup task that removes, rewrites or archives Proxmox-specific automation if NixOS plus Incus is selected.
- Kubernetes distribution decisions must be evaluated after the substrate decision because Talos, k3s and RKE2 have different operational implications on Proxmox VMs versus an Incus/NixOS host.
Decision Outcome
Section titled “Decision Outcome”No option is accepted yet. The next implementation plan must gather evidence and update all Proxmox-specific documents so they read as current-state material, not immutable target architecture.