¶ Homelab Overview
Welcome to the documentation wiki for the Homelab infrastructure. This wiki covers the complete stack — from network hardware through Kubernetes orchestration to application deployment.
¶ Architecture at a Glance
The homelab runs on a Proxmox VE hypervisor hosting a 4-node Kubernetes cluster (1 control plane + 3 workers), managed entirely through GitOps principles using ArgoCD. A Synology DS920+ NAS provides both NFS storage for Kubernetes persistent volumes and hosts additional Docker-based services.
graph TB
subgraph Internet
CF[Cloudflare Tunnel]
end
subgraph LAN 192.168.88.0/24
RT[MikroTik Router .1]
subgraph Proxmox VE .100
CP[K8s Control Plane<br/>192.168.88.250]
W1[Worker 1<br/>192.168.88.249]
W2[Worker 2<br/>192.168.88.248]
W3[Worker 3<br/>192.168.88.247]
end
NAS[Synology DS920+<br/>192.168.88.19]
TNAS[TrueNAS<br/>192.168.88.230]
UTIL[Utility Server<br/>192.168.88.245]
end
CF --> RT
RT --> CP
RT --> NAS
CP --- W1
CP --- W2
CP --- W3
NAS -.->|NFS| CP
UTIL -.->|Exporters| CP
¶ Tech Stack
| Layer | Technology | Version/Details |
|---|---|---|
| Hypervisor | Proxmox VE | Hosts all K8s VMs |
| Container Orchestration | Kubernetes (kubeadm) | 4 nodes (1 CP + 3 workers) |
| GitOps | ArgoCD | App-of-apps pattern, 30 components |
| Infrastructure as Code | Terraform | Terraform Cloud backend (TA org) |
| Secret Management | HashiCorp Vault + VSO | 3-pod HA Raft, KV v2, per-namespace policies |
| Ingress | Traefik v3 + MetalLB | L2 mode, VIP 192.168.88.12, TLS 1.3 |
| TLS | cert-manager | Let's Encrypt DNS-01 via Cloudflare |
| DNS | Technitium + CoreDNS + ExternalDNS | DoH upstream, ad-blocking, DNSSEC, DoT/DoH, auto-sync |
| SSO | Authentik | OIDC for ArgoCD, Grafana, Harbor |
| Monitoring | VictoriaMetrics + Grafana + vmalert | 90-day retention, ntfy alerts (push notifications) |
| Push Notifications | ntfy | Self-hosted, FCM relay, deny-all auth, topics: homelab-alerts/ops/security/ups |
| Logging | VictoriaLogs + Vector | 30-day retention, syslog from MikroTik |
| Tracing | OpenTelemetry Collector + Tempo | 14-day retention in MinIO, metrics-generator for RED metrics |
| Container Registry | Harbor | OIDC, Cosign signing, Trivy scanning |
| Storage | NFS (Synology) + Longhorn | Retain/Delete policies, distributed block |
| NAS | Synology DS920+ | Immich, Vaultwarden, Paperless-ngx, etc. |
| CI/CD | GitHub Actions | Self-hosted ARC runners, Kaniko builds |
¶ Repository Map
graph LR
subgraph Repositories
A[k8s-cluster-config] -->|ArgoCD syncs| K8S[Kubernetes Cluster]
B[terraform-k8s-infra] -->|Terraform Cloud| VAULT[Vault + Harbor]
C[argocd-bootstrap] -->|kubectl apply -k| ARGO[ArgoCD Install]
D[LifeOps] -->|CI/CD Pipeline| HARBOR[Harbor Registry]
HARBOR -->|Image tag update| A
end
| Repository | Purpose | Key Contents |
|---|---|---|
k8s-cluster-config |
ArgoCD app-of-apps GitOps config | 30 core components, sync wave ordering |
terraform-k8s-infra |
Vault, VSO, Harbor Terraform | 4 modules, 9 namespaces, 15 secret paths |
argocd-bootstrap |
Initial ArgoCD install via Kustomize | Sealed secrets, OIDC config, ingress |
LifeOps |
Go + Next.js personal asset tracker | 6-stage CI/CD, Kaniko + Cosign + Trivy |
¶ Quick Navigation
¶ Infrastructure
- Architecture & Network Topology — Mermaid diagrams, data flow
- Network Topology & IP Assignments — Full IP table, service URLs
- MikroTik Router — Gateway configuration
- ArgoCD Bootstrap — Initial cluster setup
- Terraform Infrastructure — Vault, VSO, Harbor modules
- Vault & VSO Secrets — Secret management pattern
¶ Kubernetes
- Cluster Config Overview — App-of-apps pattern
- Core Components — All 30 components table
- Storage — NFS Synology, Longhorn
- Monitoring — VictoriaMetrics, Grafana, alerts
- Security — CrowdSec IDS/IPS — Detection, AppSec WAF, operational commands
- Security — Falco Alert Reference — MITRE tags, field guide, common rules, response actions
- Ingress & TLS — Traefik, cert-manager, MetalLB
- DNS — Technitium, CoreDNS, ExternalDNS
- Authentication — Authentik SSO, OIDC blueprints
¶ NAS & Applications
- Synology NAS Overview — Hardware, Docker, NFS
- NAS Docker Apps — Immich, Vaultwarden, Paperless, ntfy, IT Tools, etc.
- NAS Monitoring — Node Exporter, SNMP
- Service HA & Warm Standby — Nextcloud multi-replica, Vaultwarden/Immich NAS→K8s failover
- LifeOps Project — Go + Next.js app
- LifeOps CI/CD — Full pipeline docs
¶ Guides
- Add a New App — Step-by-step walkthrough
- Add a Vault Secret — Terraform + VSO setup