GitOps-managed Kubernetes homelab using Flux CD.
This repository contains the complete infrastructure and application configuration for a Kubernetes homelab environment. Everything is managed declaratively through Git, with Flux CD automatically reconciling the cluster state.
| Environment | Nodes | Storage | Load Balancing | Version |
|---|---|---|---|---|
| Staging | 1 server + 1 agent (k3d) | local-path | k3d built-in | K3s v1.31.5 |
| Production | 3 control planes (HA) | Longhorn (3-replica) | MetalLB | K3s v1.33.6 |
| Service | Staging | Production |
|---|---|---|
| Commafeed | commafeed.staging.ronaldlokers.nl | commafeed.ronaldlokers.nl |
| Homepage | homepage.staging.ronaldlokers.nl | homepage.ronaldlokers.nl |
| Immich | immich.staging.ronaldlokers.nl | immich.ronaldlokers.nl |
| Linkding | linkding.staging.ronaldlokers.nl | linkding.ronaldlokers.nl |
| Nightscout | nightscout.staging.ronaldlokers.nl | nightscout.ronaldlokers.nl |
| Speedtest Tracker | N/A | speedtest.ronaldlokers.nl |
| Grafana | grafana.staging.ronaldlokers.nl | grafana.ronaldlokers.nl |
| Longhorn | N/A | longhorn.ronaldlokers.nl |
Runs in a Proxmox VM on hightower (Intel NUC7i3DNHE):
- Platform: k3d (K3s in Docker)
- Host: Ubuntu Server VM with Docker
- IP: 10.0.40.52
Runs in a Sipeed NanoCluster with Raspberry Pi CM5 modules:
- 3 nodes: kube-srv-1, kube-srv-2, kube-srv-3
- Compute Module: Raspberry Pi CM5
- RAM: 16GB per node
- Storage: 64GB eMMC per node
- IPs: 10.0.40.101, 10.0.40.102, 10.0.40.103
- GitOps: Flux CD - Continuous delivery from Git
- Automation: Renovate - Automated dependency updates
- Certificates: cert-manager - Automatic TLS with Let's Encrypt
- Ingress: Traefik - Ingress controller
- Load Balancer: MetalLB - Bare-metal load balancer (production only)
- Storage: Longhorn - Distributed block storage (production only)
- Database: CloudNative-PG - PostgreSQL operator with DocumentDB extension for MongoDB compatibility
- Monitoring: kube-prometheus-stack - Prometheus & Grafana
- Logging: Loki + Grafana Alloy - Log aggregation and querying (staging)
- Applications:
- Commafeed - Self-hosted RSS reader
- Homepage - Modern application dashboard
- Immich - Self-hosted photo and video management
- Linkding - Bookmark manager
- Nightscout - CGM remote monitoring for diabetes management
- Speedtest Tracker - Internet speed test history with Grafana integration
- Setup Guide - How to set up staging and production clusters
- Architecture - Repository structure, deployment flow, and networking
- Security - SOPS encryption and secrets management
- Network Security - NetworkPolicy implementation and zero-trust architecture
- Stack Details - Detailed component information
- War Stories - Real-world challenges and solutions from building this cluster
- Control Plane: 3-node HA with embedded etcd (survives 1-node failure)
- Storage: Longhorn with 3-replica redundancy (survives 2-node failure)
- Load Balancing: MetalLB provides single VIP (10.0.40.100) for ingress
- Database: PostgreSQL cluster with 3 instances and DocumentDB extension for redundancy
- Certificates: Automatic TLS with Let's Encrypt DNS-01 challenges
- Push changes to Git repository
- Flux detects changes within about a minute (or instantly with manual reconciliation)
- Flux applies changes to the cluster
- Health checks ensure successful deployment
- Renovate scans for dependency updates hourly
- Creates pull requests with changelogs
- Review and merge to automatically deploy updates
- Zero-Trust Networking: NetworkPolicies enforce default-deny with explicit allow rules
- Namespace Isolation: Prevents lateral movement between services
- Egress Control: Limits external communication to approved endpoints
- TLS Everywhere: Automatic certificates with Let's Encrypt DNS-01 challenges
- Secrets Management: SOPS encryption with age keys (separate per environment)
- Private keys stored in Proton Pass (not in Git)
- PostgreSQL backups to Backblaze B2 object storage
- Daily automated backups with 14-30 day retention
- Point-in-time recovery (PITR) capability
- Continuous WAL archiving for near-zero data loss
- Off-cluster storage survives complete cluster failure
.
├── clusters/ # Flux entry points for each environment
├── infrastructure/
│ ├── controllers/ # Core services (cert-manager, cloudnative-pg, longhorn, metallb, renovate)
│ └── configs/ # Infrastructure configuration (issuers, database clusters, middlewares)
├── apps/ # Applications (linkding, homepage)
├── monitoring/ # Observability (kube-prometheus-stack, dashboards)
└── docs/ # Documentation
See Architecture for detailed structure information.
This is a personal homelab repository, but feel free to use it as inspiration for your own setup!
This repository is provided as-is for educational purposes.

