Configuration

Now that you understand how include, extends, and override files work, how do you pick the right one? Here’s a practical guide. Use override files for environment-specific configuration Override files are the right choice when you need to adapt the same stack to different environments or developer setups: # compose.yml - base definition, committed to git services: app: image: myapp:${TAG:-latest} environment: NODE_ENV: production # compose.override.yml - local dev tweaks, optionally gitignored services: app: build: . # Build locally instead of pulling image environment: NODE_ENV: development volumes: - .:/app # Mount source for hot reload Good fit for: ...

Docker Compose gives you three ways to split and reuse configurations. They look similar but work at different levels and serve different purposes. Override files: project-level merge Override files are merged with your main compose.yml at the project level. compose.override.yml is loaded automatically; additional files require the -f flag: # compose.override.yml is loaded automatically docker compose up # Explicit merge docker compose -f compose.yml -f compose.prod.yml up Mappings are merged (override wins), arrays are concatenated: ...

Keep configurations DRY! The include directive enables modular, reusable Compose setups. Basic include usage Split configurations into logical modules: # compose.yml include: - path: ./services/database.yml - path: ./services/cache.yml - path: ./services/monitoring.yml services: app: image: myapp:latest depends_on: - postgres - redis # services/database.yml services: postgres: image: postgres:15 volumes: - postgres_data:/var/lib/postgresql/data volumes: postgres_data: Project-wide organization Structure complex projects: project/ ├── compose.yml # Main entry point ├── common/ │ ├── networks.yml # Shared networks │ └── volumes.yml # Shared volumes ├── services/ │ ├── frontend.yml # Frontend services │ ├── backend.yml # Backend services │ └── database.yml # Data layer └── environments/ ├── dev.yml # Development overrides └── prod.yml # Production config # compose.yml include: - path: ./common/networks.yml - path: ./common/volumes.yml - path: ./services/frontend.yml - path: ./services/backend.yml - path: ./services/database.yml - path: ${COMPOSE_ENV:-./environments/dev.yml} Conditional includes Include files based on environment: ...

Stop copy-pasting the same configuration. YAML anchors let you define once and reuse everywhere in your Compose files. The basics Define an anchor with & and reference it with *: services: web: &default-app image: myapp:latest environment: NODE_ENV: production LOG_LEVEL: info networks: - app-network worker: <<: *default-app # Inherit all settings from web command: npm run worker The worker service inherits everything from web, then overrides the command. ...

Same compose.yml, different environments. Here’s the cleanest approach. Basic setup Create different env files for each environment: .env.dev DATABASE_URL=postgresql://localhost:5432/dev_db API_KEY=dev_key_12345 LOG_LEVEL=debug REPLICAS=1 .env.prod DATABASE_URL=postgresql://prod-db.example.com:5432/prod_db API_KEY=${SECURE_API_KEY} # From CI/CD secrets LOG_LEVEL=error REPLICAS=3 How to use them # Development docker compose --env-file .env.dev up # Production docker compose --env-file .env.prod up # Override specific vars API_KEY=test_key docker compose --env-file .env.dev up Layering configs You can use multiple env files: # Base + environment-specific docker compose \ --env-file .env.base \ --env-file .env.prod \ up Note: Later files override earlier ones. ...