Environment Configuration¶

Guide to configuring environment variables for the Portugal Odyssey platform.

Quick Start¶

Copy environment templates
Edit configuration files
Generate secrets
Verify configuration

Environment Files¶

The platform uses three main environments:

Development (.env.dev) - Local development
Qualification (.env.qual) - Staging/testing
Production (.env.prod) - Live production

Setup Steps¶

1. Copy Templates¶

# Copy development template
cp infrastructure/env-templates/.env.development .env.dev

# Copy qualification template
cp infrastructure/env-templates/env.qualification.template .env.qual

# Copy production template
cp infrastructure/env-templates/env.production.template .env.prod

2. Configure Development Environment¶

Edit .env.dev:

nano .env.dev

Key variables to set: - Database passwords - Redis password - RabbitMQ credentials - Service-specific API keys (if needed)

3. Generate Secrets¶

Use the Makefile to generate secure random secrets:

make secrets

This generates secure passwords for: - PostgreSQL - Redis - RabbitMQ - JWT secrets

4. Verify Configuration¶

# Check Docker Compose can read variables
docker compose -f docker-compose.yml -f infrastructure/compose/development.yml config

Environment-Specific Configuration¶

Development¶

Purpose: Local development with relaxed security

Key Settings: - Use simple passwords (or defaults) - Enable debug logging - Allow insecure connections for local testing

Qualification¶

Purpose: Pre-production testing

Key Settings: - Use production-like security - Real service integrations (where possible) - Separate from production data

Production¶

Purpose: Live production environment

Key Settings: - Strong, unique passwords - Production API keys - Secure configurations - Monitoring enabled

Required Variables¶

See Environment Variables Reference for complete list.

Minimum required: - Database credentials - Redis password - RabbitMQ credentials - Registry credentials (for deployments)

Security Notes¶

Never commit .env files - They're in .gitignore
Use different secrets per environment
Rotate secrets regularly in production
Limit access to production secrets

Troubleshooting¶

Variables Not Loading¶

# Check file exists
ls -la .env.dev

# Verify Docker Compose can read it
docker compose config

Missing Variables¶

Check the template files in infrastructure/env-templates/ for all required variables.

Wrong Environment¶

Ensure you're using the correct .env file for your target environment.