# Secrets Management Setup Guide

This document describes the tools and configuration required for managing encrypted secrets in DeepData.

## Required Tools

### Homebrew Packages (macOS)

| Tool | Version | Purpose | Install Command |
|------|---------|---------|-----------------|
| age | 1.3.1 | Encryption tool for secrets | `brew install age` |
| sops | 3.13.1 | Secrets encryption manager | `brew install sops` |
| helm | 4.1.0+ | Kubernetes package manager | `brew install helm` |

### Helm Plugins

| Plugin | Version | Purpose | Install Method |
|--------|---------|---------|----------------|
| helm-secrets | 4.6.0 | Helm integration with sops | Manual clone (see below) |

**Note:** Helm 4.x has compatibility issues with helm-secrets plugin. Use manual installation:

```bash
cd /Users/macoo/Library/helm/plugins
git clone --depth 1 --branch v4.6.0 https://github.com/jkroepke/helm-secrets.git helm-secrets
```

If plugin fails to load, edit `plugin.yaml` to remove the `command:` field and use only `platformCommand:`.

## Project Configuration Files

| File | Purpose | Location |
|------|---------|----------|
| `.sops.yaml` | SOPS encryption rules | Project root |
| `.sops-keys/key.txt` | Age encryption key (private) | Project root (gitignored) |
| `secrets.yaml` | Encrypted secrets per chart | `deployment/helm/<chart>/` |

## Quick Setup

### 1. Install Required Tools

```bash
# macOS (Homebrew)
brew install age sops helm

# Helm plugin (manual)
cd ~/Library/helm/plugins
git clone --depth 1 --branch v4.6.0 https://github.com/jkroepke/helm-secrets.git helm-secrets
```

### 2. Generate Age Key (if not exists)

```bash
mkdir -p .sops-keys
age-keygen -o .sops-keys/key.txt
```

**Important:** Backup the key file securely. It cannot be recovered if lost.

### 3. Update `.sops.yaml` with Your Public Key

```yaml
creation_rules:
  - path_regex: deployment/helm/.*\.yaml$
    age: <your-public-key-from-key.txt>
```

### 4. Create/Encrypt Secrets Files

```bash
# Set environment variable
export SOPS_AGE_KEY_FILE=.sops-keys/key.txt

# Encrypt existing file
sops --encrypt --in-place deployment/helm/deepdata/secrets.yaml

# Or create new encrypted file
sops deployment/helm/deepdata/secrets.yaml
```

## Usage

### View Decrypted Secrets

```bash
SOPS_AGE_KEY_FILE=.sops-keys/key.txt sops --decrypt deployment/helm/deepdata/secrets.yaml
```

### Deploy with Secrets

```bash
# Using helper script
./scripts/secrets.sh helm-install deepdata deepdata

# Manual method
TMP_FILE=$(mktemp)
SOPS_AGE_KEY_FILE=.sops-keys/key.txt sops --decrypt deployment/helm/deepdata/secrets.yaml > $TMP_FILE
helm install deepdata deployment/helm/deepdata -n deepdata -f $TMP_FILE
rm $TMP_FILE
```

### Docker Compose

```bash
# Copy and edit .env
cp deployment/docker/deepdata/.env.example deployment/docker/deepdata/.env

# Edit with your secrets
vim deployment/docker/deepdata/.env

# Deploy
docker compose -f deployment/docker/deepdata/docker-compose.yml up -d
```

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `SOPS_AGE_KEY_FILE` | Path to age private key |
| `SOPS_CONFIG` | Path to .sops.yaml (optional) |

## Security Notes

1. **Never commit `.sops-keys/` directory** - It's in `.gitignore`
2. **Backup your age key** - Store in secure location (password manager, encrypted backup)
3. **Use strong passwords** - Generate with `openssl rand -base64 32`
4. **Rotate keys periodically** - Especially after team changes

## Troubleshooting

### Plugin Load Error

If helm plugin shows "both platformCommand and command are set":
```bash
# Edit plugin.yaml
vim ~/Library/helm/plugins/helm-secrets/plugin.yaml
# Remove the "command:" line, keep only "platformCommand:"
```

### Decryption Failed

```bash
# Check key file exists
ls -la .sops-keys/key.txt

# Verify key matches encrypted file's recipient
grep "recipient:" deployment/helm/deepdata/secrets.yaml
```

### Key Rotation

```bash
# Generate new key
age-keygen -o .sops-keys/key-new.txt

# Update .sops.yaml with new public key

# Re-encrypt all secrets
for f in deployment/helm/*/secrets.yaml; do
  SOPS_AGE_KEY_FILE=.sops-keys/key.txt sops --decrypt $f > /tmp/plain.yaml
  SOPS_AGE_KEY_FILE=.sops-keys/key-new.txt sops --encrypt /tmp/plain.yaml > $f
done

# Replace old key
mv .sops-keys/key-new.txt .sops-keys/key.txt
```