Architecture overview
A high-level look at how this homelab is put together. Internal topology, hostnames, and IP addressing are deliberately omitted here — see the Homelab page for the public-facing summary.
Layers
| Layer | What runs | Why |
|---|---|---|
| Hypervisor | A single Proxmox VE host runs everything as VMs and Linux containers | Nothing runs on bare metal except the hypervisor and one dedicated backup appliance |
| Operating systems | NixOS, configured declaratively from one flake, on most VMs/containers; vendor-standard Linux on a few appliances (identity server, backup server) | A machine's running state is a reproducible function of source control, not manual changes accumulated over time |
| Containerized applications | Docker containers under Docker Swarm, spread across a small multi-node cluster | Redundancy; a reverse proxy in front handles routing and automatic TLS for every service |
| High availability | Two supporting two-node clusters: file-server (shared storage) and database (shared MariaDB) | Synchronous block-level replication and automatic failover — a single node failure doesn't take a service down |
| Identity and access | A central identity server handles authentication, authorization, and internal DNS for every managed host; select operator-facing services add single-sign-on with two-factor on top | One account, one password policy, one place to revoke access, instead of per-service local accounts scattered everywhere |
Everything as code
Every host, network resource, and service definition is declared in version control:
- Terraform captures and detects drift in the hypervisor's VM inventory.
- Ansible idempotently configures the non-NixOS hosts.
- NixOS flakes declaratively manage every NixOS host — VMs and containers alike.
- CI pipelines run daily drift-detection, so configuration that's changed outside of code gets flagged automatically rather than discovered by accident.
Secrets are encrypted at rest (SOPS + age) and never committed in plaintext. Nothing gets deployed to a production host without a dry-run/plan step reviewed first.