homelab/docs/MIGRATION-STATUS.md

GitOps Migration Status

Completed Tasks

Phase 1: Foundation (✅ Complete)

1. SOPS + Age Setup

   • Installed SOPS 3.9.2 for ARM64
   • Installed Age encryption tool
   • Generated Age key: age1c7ke5ajhtzua7lrvzsg2p7krnnqv5jhvafh4lsl2s022j46jggnss4rxry
   • Created .sops.yaml configuration
   • Age private key location: ~/homelab/age.key (KEEP SECURE!)

2. Repository Structure

   • Created layered directory structure (infrastructure/platform/apps)
   • Added .gitignore to prevent secret leakage
   • Created comprehensive README.md
   • Initialized git repository with main branch

3. MCP Servers Migration

   • Extracted secrets from ~/git/mcp-servers/custom-values.yaml
   • Created SOPS-encrypted platform/mcp-servers/secrets.enc.yaml
   • Created clean values.yaml referencing encrypted secrets
   • Added Flux HelmRelease for mcp-umbrella chart
   • Created namespace.yaml and kustomization.yaml

4. Flux Configuration

   • Created clusters/production/infrastructure.yaml Kustomization
   • Created clusters/production/platform.yaml Kustomization
   • Configured SOPS decryption in Flux Kustomizations
   • Set up dependency chain (infrastructure → platform → apps)

5. Git Repository

   • Created repository in Gitea: http://192.168.1.49:13001/admin/homelab
   • Pushed initial commit with all configuration
   • Remote configured with token authentication

Next Steps

Phase 2: Flux Bootstrap (To Do)

1. Create SOPS Secret in Kubernetes

   # Create sops-age secret in flux-system namespace
   kubectl create namespace flux-system --dry-run=client -o yaml | kubectl apply -f -
   kubectl create secret generic sops-age \
     --namespace=flux-system \
     --from-file=age.agekey=/data/data/com.termux/files/home/homelab/age.key
   

2. Bootstrap Flux

   flux bootstrap git \
     --url=http://192.168.1.49:13001/admin/homelab \
     --branch=main \
     --path=clusters/production \
     --token-auth \
     --username=admin \
     --password=b8a17f45f86db1cb1924487189a2d8e3d298a611
   

3. Verify Deployment

   flux get sources git
   flux get kustomizations
   kubectl get helmreleases -A
   kubectl get pods -n mcp
   

Phase 3: Migrate Remaining Applications (To Do)

Applications still in ~/git/ to migrate:

Infrastructure Layer

• cert-manager
• ingress-nginx
• nfs-client-provisioner or other storage

Platform Layer

• gitea (already running, just migrate to GitOps)
• harbor (container registry)
• n8n (workflow automation)
• gotify (notifications)
• prometheus (monitoring)

Apps Layer

• Media:

  • audiobookshelf
  • media-servarr (sonarr, radarr, etc.)
  • mpd

• AI:

  • ollama
  • open-webui

• File Sharing:

  • firefox-send
  • pairdrop
  • pingvin-share
  • psitransfer

• Utilities:

  • bentopdf
  • stirling-pdf
  • minecraft

Phase 4: Clean Up (To Do)

Once all apps are migrated and verified:

1. Remove old ~/git/mcp-servers/custom-values.yaml (contains unencrypted secrets)
2. Update any remaining apps to use GitOps workflow
3. Document any manual steps required for each app

Important Security Notes

Secrets Management

1. Age Private Key: /data/data/com.termux/files/home/homelab/age.key

   • This key is required to decrypt secrets
   • NEVER commit this to git (already in .gitignore)
   • Back this up securely (consider encrypted USB, password manager, etc.)
   • Required for Flux to decrypt secrets in cluster

2. Gitea Token: Currently embedded in git remote URL

   • Token: b8a17f45f86db1cb1924487189a2d8e3d298a611
   • Consider using SSH keys instead for better security
   • Or use Flux's token management

3. Encrypted Secrets: platform/mcp-servers/secrets.enc.yaml

   • Contains API keys for: MCP Gateway, n8n, GitHub, Gitea
   • Encrypted with SOPS + Age
   • Safe to commit to git repository
   • Can be decrypted with: SOPS_AGE_KEY_FILE=~/homelab/age.key sops -d platform/mcp-servers/secrets.enc.yaml

Repository Links

• Gitea Web UI: http://192.168.1.49:13001/admin/homelab
• MCP Gateway: http://192.168.1.49:30743
• Local Repository: /data/data/com.termux/files/home/homelab

Migration Pattern for Future Apps

When migrating additional applications:

1. Create directory structure:

   {layer}/{app-name}/
   ├── namespace.yaml         # Create namespace
   ├── helmrelease.yaml       # HelmRelease if using Helm
   ├── kustomization.yaml     # Kustomize resources
   ├── secrets.enc.yaml       # SOPS-encrypted secrets
   └── values.yaml            # Helm values (no secrets!)
   

2. Extract secrets:

   # Create secrets file
   vim {layer}/{app-name}/secrets.yaml
   
   # Encrypt with SOPS
   SOPS_AGE_KEY_FILE=~/homelab/age.key sops -e {layer}/{app-name}/secrets.yaml > {layer}/{app-name}/secrets.enc.yaml
   
   # Remove unencrypted version
   rm {layer}/{app-name}/secrets.yaml
   

3. Update layer kustomization: Add app to {layer}/kustomization.yaml

4. Commit and push:

   git add .
   git commit -m "Add {app-name} to {layer}"
   git push
   

5. Flux will automatically reconcile within 10 minutes (or force: flux reconcile kustomization {layer})