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**
   ```bash
   # 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**
   ```bash
   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**
   ```bash
   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**:
   ```bash
   # 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**:
   ```bash
   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}`)