Skip to content

Environment Configuration

Guide to configuring and managing Dev, Qualification, and Production environments.

Environment Overview

The platform supports three distinct environments:

Environment Purpose Domain Pattern Location
Development Local development *.dev.codecomedy.dev Developer machines
Qualification Staging/testing *.po.codecomedy.dev VPS (shared with prod)
Production Live production *.portugalodyssey.pt VPS (shared with qual)

Environment Architecture

Network Isolation

Qualification and Production run on the same VPS but are isolated:

  • Separate Docker networks: po-internal-qual and po-internal-prod
  • Separate databases: Environment-specific PostgreSQL databases
  • Separate RabbitMQ virtual hosts: portugal_odyssey_qual and portugal_odyssey_prod
  • Shared infrastructure: Traefik, monitoring stack

Domain Routing

Traefik routes traffic based on domain:

  • Dev: *.dev.codecomedy.dev → Development services
  • Qual: *.po.codecomedy.dev → Qualification services
  • Prod: *.portugalodyssey.pt → Production services

Development Environment

Purpose

Local development with hot reload and debugging capabilities.

Configuration

File: .env.dev (copied from infrastructure/env-templates/.env.development)

Key Settings: - Simple passwords (or defaults) - Debug logging enabled - Local service URLs - Development database

Starting Development

# Create networks (first time)
make networks

# Start development stack
make dev

# View logs
make dev-logs

Access Points

  • Public frontend: https://public-fo-dev.portugalodyssey.pt
  • Strapi CMS: https://cms-dev.portugalodyssey.pt
  • API Gateway: https://api-dev.portugalodyssey.pt
  • Traefik Dashboard: http://localhost:8080

Qualification Environment

Purpose

Pre-production testing environment for QA and integration testing.

Configuration

File: .env.qual (copied from infrastructure/env-templates/env.qualification.template)

Key Settings: - Production-like security - Separate from production data - Real service integrations (where possible) - Qualification-specific credentials

Deployment

# Deploy to qualification VPS
make deploy-vps-qual SERVICE=service-name TAG=latest

# Or deploy all services
make deploy-vps-qual

VPS Configuration

  • Host: qual.portugalodyssey.pt
  • User: root
  • Path: /opt/po-platform
  • Network: po-internal-qual

Production Environment

Purpose

Live production environment serving real users.

Configuration

File: .env.prod (copied from infrastructure/env-templates/env.production.template)

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

Deployment

# Deploy to production VPS (requires approval)
make deploy-vps-prod SERVICE=service-name TAG=latest

Warning: Production deployments require extra caution and approval.

VPS Configuration

  • Host: prod.portugalodyssey.pt (or same VPS as qual)
  • User: root
  • Path: /opt/po-platform
  • Network: po-internal-prod

Environment Variables

Shared Variables

All environments share some infrastructure variables:

  • POSTGRES_USER / POSTGRES_PASSWORD
  • REDIS_PASSWORD
  • RABBITMQ_USER / RABBITMQ_PASSWORD

Environment-Specific Variables

Each environment has its own set:

Development: - POSTGRES_USER_DEV / POSTGRES_PASSWORD_DEV - RABBITMQ_USER_DEV / RABBITMQ_PASSWORD_DEV

Qualification: - POSTGRES_USER_QUAL / POSTGRES_PASSWORD_QUAL - RABBITMQ_USER_QUAL / RABBITMQ_PASSWORD_QUAL - JWT_SECRET_QUAL

Production: - POSTGRES_USER / POSTGRES_PASSWORD - RABBITMQ_USER / RABBITMQ_PASSWORD - JWT_SECRET

See Environment Variables Reference for complete list.

Database Configuration

Multi-Database Setup

PostgreSQL is configured to create multiple databases per environment:

Development: - strapi, booking, payment, user_management, experience, analytics, reviews, iam, keycloak, kong

Qualification: - Same databases with _qual suffix (e.g., notification_qual)

Production: - Same databases with _prod suffix (e.g., notification_prod)

Database Initialization

Databases are created automatically via infrastructure/scripts/init-multiple-databases.sh:

# Set in .env file
POSTGRES_MULTIPLE_DATABASES=strapi,booking,payment,user_management,experience,analytics,reviews,iam,keycloak,kong,notification_qual

RabbitMQ Configuration

Virtual Hosts

Each environment uses its own virtual host:

  • Dev: portugal_odyssey_dev
  • Qual: portugal_odyssey_qual
  • Prod: portugal_odyssey_prod

Virtual hosts are created automatically via: - Definitions file: infrastructure/config/rabbitmq/definitions.json - Init script: infrastructure/scripts/init-rabbitmq-vhosts.sh

See RabbitMQ Setup for details.

Environment Switching

Local Development

# Switch to qualification locally
make qual

# Switch back to development
make dev

VPS Deployment

# Deploy to qualification
make deploy-vps-qual SERVICE=service-name

# Deploy to production
make deploy-vps-prod SERVICE=service-name

Best Practices

  1. Never mix environments - Keep dev/qual/prod completely separate
  2. Use different secrets - Never reuse production secrets
  3. Test in qualification first - Always test changes in qual before prod
  4. Monitor deployments - Watch logs and health checks after deployment
  5. Document changes - Keep environment-specific notes

Troubleshooting

Environment Not Starting

# Check environment file exists
ls -la .env.dev

# Verify Docker Compose can read it
docker compose -f docker-compose.yml -f infrastructure/compose/development.yml config

Wrong Environment Active

# Check current environment
docker compose ps

# Stop current environment
make dev-stop  # or qual-stop, prod-stop

# Start correct environment
make dev  # or qual, prod

Database Connection Issues

# Check database is running
docker ps | grep postgres

# Verify connection
docker exec po-postgres psql -U postgres -c "SELECT version();"

See Also