foxhunt/docs/DOCKER_SECRETS_QUICKSTART.md

# Docker Secrets Quick Start Guide

**Quick reference for deploying Foxhunt with Docker Swarm secrets**

---

## Prerequisites

```bash
# 1. Initialize Docker Swarm
docker swarm init

# 2. Generate TLS certificates (if not already done)
cd certs && ./generate-certs.sh

# 3. Have your credentials ready:
#    - AWS Access Key ID & Secret
#    - Benzinga API Key
#    - Vault Token
```

---

## Quick Setup (Automated)

### Option 1: Interactive Mode (Recommended)

```bash
# Run the setup script and follow prompts
./scripts/setup-docker-secrets.sh --interactive
```

### Option 2: From Environment Variables

```bash
# Create .env file with your secrets
cp .env.example .env
# Edit .env with your actual values

# Load secrets from .env
./scripts/setup-docker-secrets.sh --from-env
```

---

## Manual Setup (Step by Step)

### 1. Generate Secrets

```bash
# JWT Secret (96 bytes)
openssl rand -base64 96 | docker secret create foxhunt_jwt_secret -

# PostgreSQL
echo "foxhunt_prod" | docker secret create foxhunt_postgres_user -
openssl rand -base64 32 | docker secret create foxhunt_postgres_password -

# Redis
openssl rand -base64 32 | docker secret create foxhunt_redis_password -

# InfluxDB
openssl rand -base64 32 | docker secret create foxhunt_influxdb_token -
```

### 2. Add External API Keys

```bash
# Vault Token
echo "YOUR_VAULT_TOKEN" | docker secret create foxhunt_vault_token -

# AWS Credentials
echo "YOUR_AWS_ACCESS_KEY_ID" | docker secret create foxhunt_aws_access_key_id -
echo "YOUR_AWS_SECRET_ACCESS_KEY" | docker secret create foxhunt_aws_secret_access_key -

# Benzinga API Key
echo "YOUR_BENZINGA_KEY" | docker secret create foxhunt_benzinga_api_key -
```

### 3. Add TLS Certificates

```bash
docker secret create foxhunt_tls_cert ./certs/server.crt
docker secret create foxhunt_tls_key ./certs/server.key
docker secret create foxhunt_tls_ca ./certs/ca-bundle.crt
```

---

## Verification

### List All Secrets

```bash
# List Foxhunt secrets
docker secret ls | grep foxhunt

# Expected output:
# foxhunt_jwt_secret
# foxhunt_postgres_user
# foxhunt_postgres_password
# foxhunt_redis_password
# foxhunt_vault_token
# foxhunt_influxdb_token
# foxhunt_aws_access_key_id
# foxhunt_aws_secret_access_key
# foxhunt_benzinga_api_key
# foxhunt_tls_cert
# foxhunt_tls_key
# foxhunt_tls_ca
```

### Inspect Secret Metadata

```bash
# View secret metadata (NOT the actual value)
docker secret inspect foxhunt_jwt_secret

# Verify secret exists and has correct timestamp
docker secret inspect foxhunt_jwt_secret --format '{{.CreatedAt}}'
```

---

## Deploy to Production

```bash
# Deploy with specific version
VERSION=v1.0.0 docker stack deploy -c docker-compose.prod.yml foxhunt

# Or use latest
docker stack deploy -c docker-compose.prod.yml foxhunt

# Monitor deployment
watch docker stack ps foxhunt

# Check service logs
docker service logs foxhunt_api_gateway -f
```

---

## Verify Secret Access

```bash
# Check if services can access secrets
docker exec $(docker ps -q -f name=foxhunt_api_gateway) ls -la /run/secrets/

# Should show files like:
# -r--r--r-- 1 root root 128 Oct 12 10:00 jwt_secret
# -r--r--r-- 1 root root  44 Oct 12 10:00 postgres_password
# -r--r--r-- 1 root root  13 Oct 12 10:00 postgres_user
# ...
```

---

## Common Operations

### Update a Secret (Rotation)

```bash
# 1. Create new version
openssl rand -base64 96 | docker secret create foxhunt_jwt_secret_v2 -

# 2. Update docker-compose.prod.yml
#    Change: foxhunt_jwt_secret -> foxhunt_jwt_secret_v2

# 3. Redeploy
docker stack deploy -c docker-compose.prod.yml foxhunt

# 4. Remove old secret (after validation)
docker secret rm foxhunt_jwt_secret
```

### Remove All Secrets

```bash
# Using the script
./scripts/setup-docker-secrets.sh --remove-all

# Or manually
docker secret ls | grep foxhunt | awk '{print $2}' | xargs docker secret rm
```

### Troubleshooting Secret Access

```bash
# Check service logs for secret-related errors
docker service logs foxhunt_api_gateway 2>&1 | grep -i secret

# Verify secret is mounted in container
docker exec $(docker ps -q -f name=foxhunt_api_gateway) cat /run/secrets/jwt_secret

# Check service configuration
docker service inspect foxhunt_api_gateway --format '{{json .Spec.TaskTemplate.ContainerSpec.Secrets}}' | jq
```

---

## Service Secret Usage

Each service uses secrets as follows:

| Service | Secrets Used |
|---------|-------------|
| **API Gateway** | jwt_secret, postgres_user, postgres_password, redis_password, vault_token, tls_cert, tls_key, tls_ca |
| **Trading Service** | postgres_user, postgres_password, redis_password, vault_token, tls_cert, tls_key, tls_ca |
| **Backtesting Service** | postgres_user, postgres_password, redis_password, vault_token, benzinga_api_key, aws_access_key_id, aws_secret_access_key, tls_cert, tls_key, tls_ca |
| **ML Training Service** | postgres_user, postgres_password, redis_password, vault_token, aws_access_key_id, aws_secret_access_key, tls_cert, tls_key, tls_ca |

---

## Security Checklist

- [ ] All secrets created with strong randomness
- [ ] TLS certificates valid and not expired
- [ ] Vault token has appropriate permissions
- [ ] AWS credentials have minimal required permissions
- [ ] PostgreSQL password is strong (32+ characters)
- [ ] Redis password enabled in production
- [ ] No secrets stored in version control
- [ ] Secrets rotation schedule documented
- [ ] Audit logging enabled for secret access
- [ ] Backup of secret metadata created

---

## Migration from .env

If migrating from environment variables:

```bash
# 1. Backup current .env
cp .env .env.backup

# 2. Load secrets from .env
./scripts/setup-docker-secrets.sh --from-env

# 3. Update docker-compose.prod.yml to use secrets

# 4. Deploy
docker stack deploy -c docker-compose.prod.yml foxhunt

# 5. Verify services are healthy
docker stack ps foxhunt

# 6. Remove .env from production (keep backup)
rm .env
```

---

## References

- Full documentation: [DOCKER_SECRETS.md](./DOCKER_SECRETS.md)
- Deployment guide: [DEPLOYMENT.md](./DEPLOYMENT.md)
- TLS setup: [TLS_SETUP.md](./TLS_SETUP.md)
- Project overview: [../CLAUDE.md](../CLAUDE.md)

---

**Need Help?**

```bash
# Show script help
./scripts/setup-docker-secrets.sh --help

# List all secrets
./scripts/setup-docker-secrets.sh --list

# Docker secrets documentation
man docker secret
```

---

**Last Updated**: 2025-10-12  
**Version**: 1.0.0