A production-ready, secure homelab deployment using Kubernetes with proper secret management, health checks, and multi-environment support. Features Helm charts, Kustomize overlays, and comprehensive automation.

• No hardcoded passwords - All secrets properly managed
• External Secrets Operator for centralized secret management
• Separated databases - No more sidecar anti-patterns
• Health checks & resource limits on all services
• Multi-environment support (dev/staging/production)

• External Secrets Operator - Centralized secret management
• Kubernetes Secrets - No hardcoded passwords in Kubernetes manifests
• Automated secret generation - 32+ character random passwords
• Secret rotation capability - Update without service downtime
• SOPS + age (GitOps optional) - Encrypted secrets at rest in git (ArgoCD via KSOPS)

• K3s Kubernetes - Lightweight, production-ready Kubernetes
• Traefik Ingress - Ingress controller (routing + TLS termination via cert-manager)
• MinIO - S3-compatible object storage
• Local Path Provisioner - Dynamic persistent volume provisioning
• Separated Databases - StatefulSets instead of sidecars

• Prometheus + Grafana - Comprehensive metrics and visualization
• Uptime Kuma - Service uptime monitoring
• AlertManager - Alert management and notifications
• Loki (optional) - Log aggregation (Promtail is opt-in)

• Nextcloud - File synchronization and collaboration
• Vaultwarden - Password manager (Bitwarden-compatible)
• Jellyfin - Media server for streaming content
• Homepage - Application dashboard
• Authelia - Authentication and authorization
• Ollama (optional) - Local LLM runtime
• Open WebUI (optional) - Chat UI for Ollama

• Helm Charts - Templated, configurable deployments
• Kustomize Overlays - Environment-specific configurations
• ArgoCD - GitOps continuous delivery
• SOPS secrets (optional) - Store Secret manifests encrypted in git (see docs/runbooks/gitops-secrets.md)
• Ansible - System configuration management
• Automated backups - Scheduled data protection
• Health Checks - Liveness and readiness probes

• Kubernetes cluster (K3s recommended) and kubectl configured
• 4GB+ RAM, 50GB+ storage (more if you enable more services)
• Root or sudo access (for installing tools)
• Internet connection (image pulls and Helm charts)

git clone https://github.com/<you>/homelab.git
cd homelab

# Deploy (installs core controllers and creates any missing secrets)
./setup-v2.sh

# Validate deployment
./scripts/validate-setup.sh

If you want ArgoCD-managed encrypted Secrets:

./scripts/sops-bootstrap.sh
./scripts/configure-argocd-ksops.sh

If you use just, this repo includes a justfile:

just setup
just validate
just ci
just trivy

This repo includes a .pre-commit-config.yaml with fast local checks.

Install pre-commit (pick one):

• pipx install pre-commit
• python3 -m pip install --user pre-commit
• Or: run ./scripts/install-dev-tools.sh and use .tools/venv/bin/pre-commit

Enable the git hook:

pre-commit install

Optional (recommended): also run the full repo gate before pushing (runs ./scripts/ci.sh and fails if required tools are missing):

pre-commit install --hook-type pre-push

Run on all files:

pre-commit run -a

Install pinned versions of the tools used by ./scripts/ci.sh into .tools/:

./scripts/install-dev-tools.sh
# or
just dev-tools

Tool versions are pinned in tools/versions.env. Most repo scripts (including ./scripts/ci.sh and ./setup-v2.sh) will automatically use .tools/ if present.

# Examples
ENABLE_AI_SERVICES=true ./setup-v2.sh
ENABLE_DEV_SERVICES=true ./setup-v2.sh
ENABLE_GITOPS=true ./setup-v2.sh

INSTALL_VELERO=false INSTALL_METALLB=false ./setup-v2.sh
INSTALL_LOGGING=true INSTALL_PROMTAIL=true ./setup-v2.sh

# First, setup your Synology NAS
./scripts/synology-setup.sh 192.168.1.100 admin ~/.ssh/id_rsa

# Then run the main setup
./setup.sh

homelab/
├── setup-v2.sh             # 🆕 Enhanced secure setup script
├── setup.sh                 # 🚫 Legacy (insecure)
├── config/
│   ├── homelab-secure.yaml  # 🆕 Secure configuration
│   └── homelab.yaml         # Symlink to secure config
├── helm/                    # 🆕 Helm charts
│   └── nextcloud/           # Example Helm chart
├── kustomize/               # 🆕 Environment overlays
│   ├── base/                # Base configurations
│   └── overlays/            # Environment-specific
│       ├── development/
│       ├── staging/
│       └── production/
├── extras/                  # Optional (higher-risk) manifests not installed by default
├── legacy/                  # Archived legacy manifests (not used by setup-v2.sh)
├── kubernetes/
│   ├── secrets/             # 🆕 Secret management
│   ├── storage/             # Storage configurations
│   ├── ingress/             # Traefik and cert-manager
│   ├── monitoring/          # Prometheus, Grafana, Uptime Kuma
│   ├── services/            # All self-hosted services (updated)
│   └── gitops/              # ArgoCD configurations
├── scripts/
│   ├── generate-secrets.sh  # 🆕 Secure secret generation
│   ├── backup-secrets.sh    # Encrypted secret backup (age)
│   ├── restore-secrets.sh   # Encrypted secret restore (age)
│   ├── configure-wildcard-dns.sh # Pi-hole wildcard DNS for *.<domain>
│   ├── validate-setup.sh    # 🆕 Comprehensive validation
│   └── synology-setup.sh    # Synology NAS configuration
├── ansible/                 # System configuration
├── docs/                    # Documentation
└── SECURITY_NOTICE.md       # 🆕 Security upgrade guide

• Secrets: generated into the secrets namespace; see docs/credentials.md.
• Helm values: kubernetes/**/values.yaml and helm/**/values.yaml.
• Feature toggles: see ENABLE_* and INSTALL_* at the top of setup-v2.sh.
• Kustomize overlays: ./scripts/kustomize-apply.sh kustomize/overlays/production
• setup-v2.sh reads config/homelab.yaml for defaults like homelab.domain, homelab.timezone, homelab.email, ingress.cert_manager.cluster_issuer, and gitops.repo_url (env vars override).

After setup, access your services at:

If you enable Pi-hole, you can configure wildcard DNS so you do not need per-machine /etc/hosts entries:

./scripts/configure-wildcard-dns.sh

# Then point your clients (or router DHCP) at the Pi-hole DNS service IP:
kubectl -n pihole get svc pihole-dns

Disable the automatic DNS step during setup-v2.sh with:

CONFIGURE_WILDCARD_DNS=false ./setup-v2.sh

• TLS certificates via cert-manager (local CA by default; optional Let’s Encrypt for public domains)
• Pod Security Admission (PSA) namespace labeling (POD_SECURITY_MODE=audit|enforce; see docs/runbooks/hardening.md)
• Policy-as-code (optional) with Kyverno (INSTALL_KYVERNO=true; see docs/runbooks/hardening.md)
• Firewall configuration with UFW
• Fail2ban for intrusion prevention
• SSH hardening with key-only authentication
• Regular security updates via unattended-upgrades
• Backup encryption and rotation

Automated backups run daily at 2 AM:

• Configuration files - Full cluster state
• Application data - Persistent volumes
• Database dumps - Complete data export
• Retention policy - 30 days default

Restore with:

/usr/local/bin/restore-homelab.sh /path/to/backup

Encrypted secret backups (recommended before rebuilds):

./scripts/backup-secrets.sh
./scripts/restore-secrets.sh backups/secrets-secrets-<timestamp>.yaml.age

The homelab supports easy addition of more services:

• Radarr, Sonarr, Lidarr (media automation)
• Overseerr (request management)
• Tautulli (Plex/Jellyfin analytics)

• GitLab CE (Git repository hosting)
• Jenkins (CI/CD)
• Code-server (VS Code in browser)

• Pi-hole (DNS filtering)
• WireGuard VPN
• Nginx Proxy Manager

Add services by placing Kubernetes manifests in kubernetes/services/<service-name>/

Services not accessible:

kubectl get pods --all-namespaces
kubectl get ingress --all-namespaces

Storage issues:

kubectl get pv
kubectl get pvc --all-namespaces

SSL certificate problems:

kubectl get certificates --all-namespaces
kubectl describe certificate <cert-name>

Day-2 operations (backup/restore/upgrades): docs/runbooks/README.md

All setup logs are saved to setup.log

Service logs:

kubectl logs -f deployment/<service-name> -n <namespace>

1. Fork the repository
2. Create a feature branch
3. Add your service/improvement
4. Test thoroughly
5. Submit a pull request

MIT License - see LICENSE for details

• K3s - Lightweight Kubernetes
• Traefik - Cloud Native Networking Stack
• Helm - Package Manager for Kubernetes
• All the amazing open-source projects that make this possible

⭐ Star this repo if you found it helpful! ⭐