Skip to content

Secrets Management

Guide to generating, managing, and securing secrets for the Portugal Odyssey platform.

Overview

Secrets include: - Database passwords - Redis passwords - RabbitMQ credentials - JWT secrets - API keys (Stripe, AWS, etc.) - Service-specific secrets

Generating Secrets

Automated Generation

Use the secrets generation script:

make secrets

Or directly:

./infrastructure/scripts/generate-secrets.sh

What It Does

  1. Reads templates from infrastructure/env-templates/
  2. Generates cryptographically strong random passwords (24 characters)
  3. Ensures consistency for shared infrastructure
  4. Outputs .env files to infrastructure/compose/

Generated Files

  • infrastructure/compose/.env.shared
  • infrastructure/compose/.env.qualification
  • infrastructure/compose/.env.production

Manual Configuration

After generation, you MUST manually add external API keys:

# Edit qualification environment
nano infrastructure/compose/.env.qualification

Required Manual Configuration: - STRIPE_SECRET_KEY - Stripe API key - AWS_ACCESS_KEY_ID - AWS access key - AWS_SECRET_ACCESS_KEY - AWS secret key - GOOGLE_MAPS_API_KEY - Google Maps API key - Other third-party API keys

Secret Placeholders

The script recognizes these placeholders:

  • REPLACE_ME_STRONG_PASSWORD - Unique random secret
  • REPLACE_ME_STRONG_PASSWORD_MATCH_SHARED - Matches shared infrastructure password
  • REPLACE_ME_STRONG_[NAME] - Any other placeholder gets unique secret

Security Best Practices

1. Never Commit Secrets

  • .env files are in .gitignore
  • Never commit actual secrets to repository
  • Use templates with placeholders

2. Use Different Secrets Per Environment

  • Development: Simple passwords (or defaults)
  • Qualification: Production-like security
  • Production: Strong, unique passwords

3. Rotate Secrets Regularly

  • Rotate production secrets quarterly
  • Rotate immediately if compromised
  • Document rotation dates

4. Limit Access

  • Only grant access to those who need it
  • Use separate credentials for different roles
  • Audit access regularly

5. Secure Storage

  • Store production secrets securely
  • Use secret management tools if available
  • Encrypt secrets at rest

Secret Types

Infrastructure Secrets

Shared across environments: - PostgreSQL admin password - Redis password - RabbitMQ admin password

Environment-specific: - Database user passwords - JWT secrets - Service-specific secrets

Application Secrets

Third-party API keys: - Stripe keys - AWS credentials - Google Maps API key - SMTP credentials

Service secrets: - Keycloak client secrets - OAuth provider secrets - Webhook secrets

Deployment Secrets

VPS Deployment

Secrets are stored in .env.deploy file (not committed):

# Copy template
cp .env.deploy.example .env.deploy

# Edit with your credentials
nano .env.deploy

Required: - REGISTRY_IMAGE - Container registry prefix - REGISTRY_USER - Registry username - REGISTRY_PASSWORD - Registry password/token - DEPLOY_QUAL_HOST - Qualification VPS hostname - DEPLOY_USER - SSH user - SSH_PRIVATE_KEY - SSH private key (or use SSH agent)

Troubleshooting

Secrets Not Loading

# Check file exists
ls -la .env.dev

# Verify Docker Compose can read it
docker compose config | grep PASSWORD

Wrong Secrets Active

# Check which environment is active
docker compose ps

# Verify environment file
cat .env.dev | grep PASSWORD

Secret Rotation

  1. Generate New Secrets 

    make secrets

  2. Update Environment Files 

    # Update on VPS
nano /opt/po-platform/.env.qual

  3. Restart Services 

    make deploy-vps-qual SERVICE=all

See Also