brain

homelab-theepicsaxguy

Properties11
statusseedling
typesource
created2026-09-26
updated2026-09-26
tagsoss
aliases
sourcehttps://github.com/theepicsaxguy/homelab
languageHCL
licenseMIT
stars221
public

3 min read

Over-Engineered GitOps Homelab

CI License

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.

CategoryToolDescription
HypervisorProxmox VEManages the bare‑metal server and virtual machines.
OSTalos LinuxMinimal, secure, API‑managed operating system for Kubernetes.
InfrastructureOpenTofuDeclaratively provisions all infrastructure (IaC).
GitOps EngineArgo CDDeploys and manages every app from this Git repo.
NetworkingCiliumeBPF‑based networking, security, and observability.
StorageLonghornDistributed block‑storage for stateful workloads.
SecretsExternal SecretsSyncs secrets from Bitwarden into Kubernetes.
AuthenticationAuthentikSingle Sign‑On (SSO) across all services.
Certificatescert‑managerAutomates TLS certificate issuance and renewal.
API GatewayGateway APINext‑generation Kubernetes ingress and traffic management.
DatabaseCloudNativePGManages highly‑available PostgreSQL clusters with native K8s integration.
CI / ChecksKubechecksValidates Argo CD changes before rollout.
TunnelCloudflaredCreates secure Cloudflare tunnels for private services.

Hardware

NameDeviceCPURAMStoragePurpose
Host3Dell Precision Tower 78102× Xeon E5-2650 v378 GB DDR41x 1TB SSD - 1x 1TB Nvme SSDHypervisor
NASSupermicro X8DTUXeon E562016 GB DDR32x 3TB HDD MirrorShared storage

Quick Start

  1. Make sure you have Proxmox access with your SSH key and install opentofu, talosctl, kubectl, and argocd. A little Kubernetes and Git know-how helps.
  2. 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

.
├── 📂 website                # Documentation site
├── 📂 k8s                 # Kubernetes manifests
│   ├── 📂 applications            # Applications
│   ├── 📂 infrastructure           # Infrastructure components
├── 📂 images                 # custom containers
└── 📂 tofu                # Tofu configuration
    └── 📂 talos       # Talos configuration

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.

  1. Read the Docs: Start with the Contributing Guide to learn the workflow and standards.
  2. Find an Issue: Look for items labeled good first issue to get started quickly.
  3. 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.

Summary

Over-engineered GitOps homelab (221 stars, MIT): Proxmox + Talos Linux + OpenTofu + Argo CD, Cilium/Longhorn/External Secrets/Authentik/Gateway API/CloudNativePG/Kubechecks — the current production-inspired toolchain snapshot.

Learnings

  • The stack table doubles as a 2026 ‘what serious homelabbers run’ survey; see Homelabs.

Gotchas

  • (none yet)

Hands-on

(research only)

Graph View

Backlinks