After rebuilding my homelab one too many times, I committed to managing it entirely with GitOps. This repository is the result: a blueprint for a resilient, production-inspired Kubernetes cluster.
I'm sharing it to document my own journey and to help others build a stable, maintainable homelab without repeating my mistakes. Explore the Documentation │ See the Architecture │ Get Started
This lab is built on a foundation of powerful, open-source tools that work together to create a fully automated system.
| Category | Tool | Description |
|---|---|---|
| Hypervisor | Proxmox VE | Manages the bare‑metal server and virtual machines. |
| OS | Talos Linux | Minimal, secure, API‑managed operating system for Kubernetes. |
| Infrastructure | OpenTofu | Declaratively provisions all infrastructure (IaC). |
| GitOps Engine | Argo CD | Deploys and manages every app from this Git repo. |
| Networking | Cilium | eBPF‑based networking, security, and observability. |
| Storage | Longhorn | Distributed block‑storage for stateful workloads. |
| Secrets | External Secrets | Syncs secrets from Bitwarden into Kubernetes. |
| Authentication | Authentik | Single Sign‑On (SSO) across all services. |
| Certificates | cert‑manager | Automates TLS certificate issuance and renewal. |
| API Gateway | Gateway API | Next‑generation Kubernetes ingress and traffic management. |
| Database | CloudNativePG | Manages highly‑available PostgreSQL clusters with native K8s integration. |
| CI / Checks | Kubechecks | Validates Argo CD changes before rollout. |
| Tunnel | Cloudflared | Creates secure Cloudflare tunnels for private services. |
| Name | Device | CPU | RAM | Storage | Purpose |
|---|---|---|---|---|---|
| Host3 | Dell Precision Tower 7810 | 2× Xeon E5-2650 v3 | 78 GB DDR4 | 1x 1TB SSD - 1x 1TB Nvme SSD | Hypervisor |
| NAS | Supermicro X8DTU | Xeon E5620 | 16 GB DDR3 | 2x 3TB HDD Mirror | Shared storage |
- Make sure you have Proxmox access with your SSH key and install
opentofu,talosctl,kubectl, andargocd. A little Kubernetes and Git know-how helps. - Clone this repository and follow the steps in the Quick Start guide.
- Everything as Code: I describe the entire lab in this repo. That gives me a full audit trail and lets me rebuild from scratch.
- Automated from Day One: Provisioning, deployments, and secrets run on autopilot.
- Secure by Default: Non-root containers, network policies, and single sign-on are baked in from the start.
- Real-World Learning: I'm applying enterprise ideas at home so I can tinker and pick up new skills.
- The Learner: Understand how a production-grade Kubernetes stack really works.
- The Tinkerer: Deploy self-hosted apps on a stable base without endless upkeep.
- The Pro: Experiment with enterprise patterns or run a lab that "just works."
.
├── 📂 website # Documentation site
├── 📂 k8s # Kubernetes manifests
│ ├── 📂 applications # Applications
│ ├── 📂 infrastructure # Infrastructure components
├── 📂 images # custom containers
└── 📂 tofu # Tofu configuration
└── 📂 talos # Talos configurationMore details are in Architecture.
- Hybrid cloud backups
- Node autoscaling
- Additional monitoring dashboards
These docs describe how my cluster works today. Hardware or configuration changes could make some steps outdated. Treat them as a reference to adapt rather than a drop‑in manual.
You can contribute! I'm currently the sole maintainer and would welcome collaboration on anything from typo fixes to new applications.
- Read the Docs: Start with the Contributing Guide to learn the workflow and standards.
- Find an Issue: Look for items labeled good first issue to get started quickly.
- Suggest an Idea: Have a feature request? Open an issue and let's talk about it.
For questions, open an issue or start a discussion. More details are at homelab.orkestack.com.
MIT – see LICENSE for details.
Inspired by Vehagn's Homelab.
