homelab

Khue's Homelab is an open-source project that automates the entire lifecycle of a homelab environment, from bare metal provisioning to running self-hosted services, using Infrastructure as Code and GitOps principles. The project is currently in ALPHA status and is designed as a highly customizable framework for building personal homelabs. The core workflow starts with PXE boot-based bare metal provisioning, which automatically installs Fedora Server on physical machines. It then sets up a lightweight Kubernetes distribution (K3s) and deploys a comprehensive stack of self-hosted applications using ArgoCD for GitOps-based continuous deployment. Key capabilities include: - **Bare Metal Provisioning**: Automated PXE boot setup that provisions physical servers without manual intervention. - **Kubernetes Management**: Automated installation and management of K3s clusters with automatic rolling upgrades for both the OS and Kubernetes. - **GitOps Application Deployment**: Applications are deployed and managed through GitOps using ArgoCD, with support for automatic updates (with approval gates). - **Networking and Security**: Supports VPN via Tailscale or Wireguard, automated certificate management with cert-manager, and secure internet exposure through Cloudflare Tunnel. - **CI/CD**: Integrated Woodpecker CI for continuous integration and ArgoCD for continuous deployment. - **Storage**: Distributed storage using Rook Ceph for cloud-native storage within Kubernetes. - **Monitoring and Alerting**: Full observability stack with Prometheus, Grafana, and Loki for metrics, dashboards, and log aggregation. - **Identity Management**: Single sign-on support via Kanidm. - **DNS Automation**: ExternalDNS automatically updates DNS records for exposed services. - **Backup and Restore**: Automated backup and restore capabilities. - **Modular Architecture**: Easy to add or remove features and components. - **Multi-Environment Support**: Supports multiple environments such as dev and prod. - **Infrastructure Testing**: Built-in infrastructure testing capabilities. The tech stack includes Ansible for bare metal automation, ArgoCD for GitOps, Cilium for eBPF-based networking and observability, cert-manager for certificate management, Cloudflare for DNS and tunneling, Docker for ephemeral PXE servers, ExternalDNS for DNS synchronization, Fedora Server as the base OS, Gitea as a self-hosted Git service, Grafana for observability, Helm as the Kubernetes package manager, K3s as the lightweight Kubernetes distribution, Kanidm for identity management, Loki for log aggregation, NGINX as the Kubernetes Ingress Controller, Nix for development shells, ntfy for notifications, Prometheus for monitoring, Renovate for dependency updates, Rook Ceph for storage, Tailscale and Wireguard for VPN, Woodpecker CI for CI/CD, and Zot Registry for private container registry. The project can be tried locally without hardware (sandbox mode) or deployed on real hardware for production workloads. Documentation is available at homelab.khuedoan.com. The project is licensed under GPLv3 and welcomes contributions. It is inspired by various open-source projects and community resources in the homelab and self-hosting space.