theepicsaxguy / homelab

Over-Engineered GitOps Homelab 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** The Stack 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. | --- Hardware | 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 | --- Quick Start • Make sure you have Proxmox access with your SSH key and install , , , and . A little Kubernetes and Git know-how helps. • Clone this repository and follow the steps in the Quick Start guide. --- Why This Homelab? • **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. Who Is This For? • **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." --- Folder Structure More details are in Architecture. --- Roadmap • [ ] Hybrid cloud backups • [ ] Node autoscaling • [ ] Additional monitoring dashboards --- Limitations 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. --- Contributing 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. --- License MIT – see LICENSE for details. --- Credits Inspired by Vehagn's Homelab.