This repository is the complete infrastructure-as-code definition for my home lab — a three-node Proxmox cluster running Kubernetes, Gitea, a full monitoring stack, and a dozen self-hosted services. Every VM, network rule, and application deployment is codified in Ansible playbooks and Terraform modules, documented end to end.
Hardware
The cluster runs on three Intel NUC 12 Pros (i7-1260P, 64GB RAM, 2TB NVMe each) connected over a dedicated 2.5GbE VLAN on a Ubiquiti USW-Pro-24-PoE switch. Shared storage is a Synology DS1621+ with 6x16TB drives in RAID-Z2, exposed to the cluster via NFS and iSCSI. Total power draw at idle sits around 180W — less than a gaming PC.
Software Stack
Proxmox handles hypervisor duties. Terraform provisions VMs from cloud-init templates, and Ansible configures everything from base OS hardening to application deployment. Kubernetes runs as a k3s cluster across three worker VMs with MetalLB for bare-metal load balancing and Longhorn for distributed block storage.
Self-hosted services include Gitea (git forge), Drone CI (build pipelines), Vaultwarden (password management), Paperless-ngx (document archive), Home Assistant (home automation), and a Jellyfin media server. Every service deploys via Helm charts stored in the Gitea instance — full GitOps loop.
Monitoring and Observability
Prometheus scrapes metrics from every node, VM, and Kubernetes pod. Grafana dashboards cover cluster health, per-service resource consumption, NAS throughput, and UPS battery status. Alertmanager pushes critical alerts to a private Matrix channel — I get notified if a drive starts throwing SMART errors or if a pod enters a crash loop, wherever I am.
- Loki for centralized log aggregation across all nodes
- Uptime Kuma for external endpoint monitoring with status pages
- Custom Ansible role for automated Proxmox backup verification
- WireGuard mesh VPN for secure remote access without port forwarding
- Automated Let’s Encrypt certificates via Traefik ingress controller
A homelab that isn’t documented is just a pile of hardware you’ll forget how to rebuild.
Why Open Source It
Every homelab guide I found online was either a YouTube walkthrough with no reproducible config or a single Ansible playbook with zero documentation. This repo is the resource I wished existed when I started — every decision documented in ADR format, every playbook tested in CI, every secret managed through SOPS-encrypted YAML. Fork it, adapt it, break it, learn from it.
The repository is licensed under MIT. Hardware purchase links, power consumption benchmarks, and a cost breakdown are included in the wiki for anyone planning a similar build.