foxhunt/docs/DOCKER_SECRETS_QUICKSTART.md

Docker Secrets Quick Start Guide

Quick reference for deploying Foxhunt with Docker Swarm secrets

---

Prerequisites

# 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)

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

Option 2: From Environment Variables

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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:

# 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
• Deployment guide: DEPLOYMENT.md
• TLS setup: TLS_SETUP.md
• Project overview: ../CLAUDE.md

---

Need Help?

# 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