Homelab GitOps Repository

This repository contains the declarative configuration for my Kubernetes homelab, managed using FluxCD v2 and SOPS-encrypted secrets.

Architecture

The repository is organized into three layers:

Layer 0 - Infrastructure

Core cluster infrastructure that other applications depend on:

• cert-manager: TLS certificate management
• ingress-nginx: Ingress controller for HTTP/HTTPS routing
• storage: Persistent volume provisioning

Layer 1 - Platform

Platform services that support applications:

• gitea: Self-hosted Git server
• harbor: Container registry
• n8n: Workflow automation
• mcp-servers: Model Context Protocol servers with gateway
• gotify: Push notifications
• prometheus: Monitoring and alerting

Layer 2 - Apps

User-facing applications:

• media: Audiobookshelf, Media-Servarr stack, MPD
• ai: Ollama, Open WebUI
• file-sharing: Firefox Send, Pairdrop, Pingvin Share, PsiTransfer
• utilities: BentoPDF, Stirling PDF, Minecraft

Secrets Management

All secrets are encrypted using SOPS with age encryption.

Decrypting Secrets

# Decrypt a single file
sops -d infrastructure/cert-manager/secrets.enc.yaml > secrets.yaml

# Edit encrypted file in-place
sops infrastructure/cert-manager/secrets.enc.yaml

Encrypting New Secrets

# Encrypt a new secret file
sops -e secrets.yaml > secrets.enc.yaml

Deployment

This repository is deployed using FluxCD v2:

# Bootstrap Flux (already done)
flux bootstrap git \
  --url=http://192.168.1.49:13001/admin/homelab.git \
  --branch=main \
  --path=clusters/production

# Check Flux status
flux get all

Environment

• Platform: K3s on ARM (Raspberry Pi)
• OS: Termux on Android
• GitOps: FluxCD v2
• Secrets: SOPS + Age encryption
• Registry: Harbor (self-hosted)

Directory Structure

.
├── bootstrap/          # Flux bootstrap manifests
├── infrastructure/     # Layer 0: Core infrastructure
├── platform/          # Layer 1: Platform services
├── apps/              # Layer 2: Applications
├── clusters/          # Cluster-specific configurations
│   └── production/    # Production cluster Kustomizations
└── docs/             # Additional documentation

Maintenance

Updating Applications

1. Edit the HelmRelease or Kustomization in the appropriate directory
2. Commit and push changes to Gitea
3. Flux will automatically reconcile within 1 minute (or force with flux reconcile)

Adding New Applications

1. Create directory in appropriate layer (infrastructure/platform/apps)
2. Add namespace.yaml, helmrelease.yaml, and kustomization.yaml
3. If secrets needed, create secrets.enc.yaml using SOPS
4. Add reference to layer's kustomization.yaml
5. Commit and push

Contact

Maintained by CaffeineTux