PSA/docs/getting-started/docker_compose.md

Docker Compose Structure

The Docker Compose configuration has been organized into multiple files to support both Community Edition (CE) and Enterprise Edition (EE) while following best practices and eliminating duplication.

File Structure

• docker-compose.base.yaml: Contains shared service definitions for postgres and redis
• docker-compose.ce.yaml: Community Edition specific configurations
• docker-compose.ee.yaml: Enterprise Edition specific configurations

Base Configuration

The base configuration (docker-compose.base.yaml) includes:

• Core service definitions for postgres and redis
• Shared network configuration
• Secret definitions

Edition-Specific Configurations

Community Edition (CE)

The CE configuration (docker-compose.ce.yaml) includes:

• Standard service configurations
• CE-specific Dockerfile paths
• Default community settings
• Service environment variables
• Network and dependency configurations

Enterprise Edition (EE)

The EE configuration (docker-compose.ee.yaml) includes:

• Enterprise-specific database setup
• EE-specific Dockerfile paths
• Additional enterprise features and settings
• Service environment variables
• Network and dependency configurations

Usage

Running Community Edition

# Development
docker compose -f docker-compose.base.yaml -f docker-compose.ce.yaml up

# Production
docker compose -f docker-compose.base.yaml -f docker-compose.ce.yaml -f docker-compose.prod.yaml up -d

Running Enterprise Edition

# Development
docker compose -f docker-compose.base.yaml -f docker-compose.ee.yaml up

# Production
docker compose -f docker-compose.base.yaml -f docker-compose.ee.yaml -f docker-compose.prod.yaml up -d

Service Configuration

Environment Variables

Each service has its own environment variable configuration that includes:

• Basic application settings (VERSION, APP_NAME, etc.)
• Database configuration
• Redis settings
• Service-specific variables

Example:

environment:
  VERSION: ${VERSION}
  APP_NAME: ${APP_NAME}
  APP_ENV: ${APP_ENV:-development}
  NODE_ENV: ${APP_ENV:-development}
  DB_HOST: postgres
  DB_PORT: ${DB_PORT:-5432}
  # ... other variables

Service Extensions

Services extend from their base definitions using Docker Compose's extends feature:

services:
  postgres:
    extends:
      file: docker-compose.base.yaml
      service: postgres

Secrets

Secrets are defined in the base configuration and referenced in service configurations:

secrets:
  - db_password_server
  - redis_password
  # ... other secrets

Best Practices

1. Service Organization

   • Keep base services in docker-compose.base.yaml
   • Use edition-specific files for specialized configurations
   • Maintain clear separation between CE and EE features

2. Environment Variables

   • Define defaults in compose files
   • Use .env files for local overrides
   • Follow naming conventions

3. Service Dependencies

   • Use depends_on with conditions
   • Ensure proper startup order
   • Handle service readiness

4. Network Configuration

   • Use dedicated networks
   • Name networks consistently
   • Control service exposure

Development Workflow

1. Make changes to the base configuration if they apply to both editions
2. Update edition-specific configurations as needed
3. Test changes in both CE and EE environments
4. Update documentation if the structure changes

Troubleshooting

If you encounter issues:

1. Verify you're using the correct combination of compose files
2. Check environment variables are properly set
3. Ensure secrets exist in the correct location
4. Review service logs for specific error messages

Common issues and solutions:

Database Connection Issues

# Check postgres logs
docker compose logs postgres

# Verify environment variables
docker compose config

Service Startup Issues

# Check service logs
docker compose logs [service-name]

# Verify service configuration
docker compose config --services

Notes

• The base configuration provides core services and shared settings
• Edition-specific files add features and customizations
• Environment variables should be properly set in .env files
• Secrets are managed through Docker secrets
• Service dependencies are handled through depends_on conditions
• Networks are isolated per environment