🏠 homelab-gitops

My Kubernetes cluster managed with ArgoCD.

⚙️ Hardware (2 nodes)

Device	Name	Specs	OS	Role
Lenovo ThinkCentre M75q-2	homelab2	Ryzen 5 Pro 5650GE (6 core / 12 threads) / 24GB RAM / 256GB + 1TB SSD	NixOS	k8s controller+worker node
Lenovo ThinkCentre M75q-2	homelab3	Ryzen 5 Pro 5650GE (6 core / 12 threads) / 24GB RAM / 256GB + 1TB SSD	NixOS	k8s worker node

To access my apps, I expose them directly on the internet with port-forwarding on my router.

✨ Features

• Kubernetes cluster deployed with k0s
• GitOps deployment with ArgoCD and Helm
• Simple flat directory structure: argocd-apps contains ArgoCD applications deploying umbrella Helm charts in k8s-apps
• Fully automated HTTPS exposition using cert-manager, external-dns and traefik
• Authentication of sensitive apps with PocketID as a passkey-only OIDC provider
• WAF using ModSecurity plugin and some hacks
• Secrets management with external-secrets and GitLab CI/CD variables
• Dynamic volume provisioning and synchronous replication across nodes with Longhorn
• Offsite data backup using Velero and Backblaze B2
• Easy Backblaze-to-disk backup synchronization with Kopia and a custom script
• PostgreSQL database management with CloudNativePG
• Observability with Prometheus, Grafana, Loki and Opentelemetry Collector
• Alerting with Alertmanager and a Telegram Bot
• Thorough HTTP / PostgreSQL status checks with go-healthcheck and Gatus
• Automated updates with Renovate (even linuxserver images!)
• Scale to zero using Sablier
• Any app you'd want to host: Nextcloud, Immich, Paperless-ngx and more (see below)

💻 What's currently deployed in my cluster ?

This is an automatically updated list of the apps I have configured and/or deployed. Click on an app to check its Helm configuration.

App	Description	Is deployed
anki-sync-server	Sync server for AnkiDroid	✅
argocd	Declarative, GitOps continuous delivery tool for Kubernetes	✅
arr-stack	Arr Stack	✅
attic	Multi-tenant Nix Binary Cache	✅
blackbox-exporter	Allows blackbox probing of endpoints over HTTP, HTTPS, DNS, TCP, ICMP and gRPC	✅
calibre-web	Web app for browsing, reading and downloading eBooks stored in a Calibre database	✅
cert-manager	Automatically provision and manage TLS certificates in Kubernetes	✅
changedetection	Website change detection, web page monitoring, and website change alerts	✅
cloudnative-pg	CloudNativePG is a comprehensive platform designed to seamlessly manage PostgreSQL databases within Kubernetes environments, covering the entire operational lifecycle from initial deployment to ongoing maintenance	✅
convertx	Self-hosted online file converter	✅
external-dns	Configure external DNS servers (AWS Route53, Google CloudDNS and others) for Kubernetes Ingresses and Services	✅
external-secrets	External Secrets Operator reads information from a third-party service like AWS Secrets Manager and automatically injects the values as Kubernetes Secrets	✅
gitea	Self-hosted Git service with a lightweight code hosting solution written in Go	✅
go-healthcheck	Simple HTTP healthchecks	✅
home-assistant	Open source home automation that puts local control and privacy first	✅
homepage	A highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations	❌
httpbin	Echoes request data as JSON	✅
immich	High performance self-hosted photo and video management solution	✅
it-tools	Collection of handy online tools for developers	✅
kube-prometheus-stack	kube-prometheus-stack collects Kubernetes manifests, Grafana dashboards, and Prometheus rules combined with documentation and scripts to provide easy to operate end-to-end Kubernetes cluster monitoring with Prometheus using the Prometheus Operator	✅
loki	Like Prometheus, but for logs	✅
longhorn	Cloud-Native distributed storage built on and for Kubernetes	✅
metallb	A network load-balancer implementation for Kubernetes using standard routing protocols	✅
microbin	A secure, configurable file-sharing and URL shortening web app	✅
mosquitto	Open source MQTT broker	✅
nextcloud	A safe home for all your data	✅
opencloud	Excellent file sharing	✅
opentelemetry-collector	Vendor-agnostic implementation on how to receive, process and export telemetry data	✅
opentelemetry-operator	Kubernetes Operator for OpenTelemetry Collector	✅
paperless-ngx	Scan, index and archive all your physical documents	✅
pocket-id	Simple and easy-to-use OIDC provider that allows users to authenticate with their passkeys to your services	✅
reloader	A Kubernetes controller to watch changes in ConfigMap and Secrets and do rolling upgrades on Pods with their associated Deployment, StatefulSet, DaemonSet and DeploymentConfig	✅
sablier	A free and open-source software to start workloads on demand and stop them after a period of inactivity	✅
satisfactory-server	Satisfactory server	❌
scrobble-deduplicator	Periodically delete duplicate Last.fm scrobbles	✅
snapshot-controller	Implements the control loop for CSI snapshot functionality	❌
tailscale-operator	A Kubernetes Operator for Tailscale	✅
traefik	A Traefik based Kubernetes ingress controller	✅
vaultwarden	Unofficial Bitwarden compatible server written in Rust	✅
velero	Backup and migrate Kubernetes applications and their persistent volumes	✅
versity-gw	High-performance S3 translation service	✅
zigbee2mqtt	Zigbee to MQTT bridge	✅

🏗️ k0s quick install

The install assumes that all external secrets are already created in a GitLab project as CI/CD variables.

Start the k0s cluster:

cd ~/homelab-gitops
sudo k0s install controller --enable-worker -c ./k0s.yaml
sudo k0s start
sleep 5
sudo k0s status
sudo k0s kubeconfig admin > ~/.kube/config
kubectl taint nodes --all node-role.kubernetes.io/master-

Create the GitLab token secret used by external-secrets:

kubectl create ns external-secrets
kubectl create secret generic gitlab-secret -n external-secrets --from-literal=token=glpat-xxx

Deploy external-secrets and ArgoCD apps:

cd ../../k8s-apps/external-secrets && helm dependency update && helm template external-secrets -n external-secrets . | kubectl apply -n external-secrets -f -
kubectl create ns argocd
cd ../../k8s-apps/argocd && helm dependency update && helm template argocd . -n argocd | kubectl apply -n argocd -f -
kubectl apply -f ../../argocd-apps/app-of-apps.yaml -n argocd

Cluster should be ready!

💣 Teardown

Save the GitLab token secret

kubectl get secret -n external-secrets gitlab-secret -o yaml > gitlab-secret.yaml

Teardown the cluster

sudo k0s stop
sudo k0s reset -v -d