Extending Compose Files for Different Environments

WHY IT EXISTS: Managing a single application across multiple environments (development, staging, production) requires slight configuration changes. Maintaining separate, nearly identical Compose files for each environment is duplicative and error-prone. Extending files provides a clean, DRY (Don't Repeat Yourself) way to manage these variations.

THE MENTAL MODEL: Treat multiple Compose files like layers of a configuration. You have a base layer (docker-compose.yml) that defines the core, stable parts of your application stack. Then, you apply environment-specific layers on top (e.g., docker-compose.override.yml for development) that add or change specific settings, just like a stylesheet overrides a base HTML document.

HOW IT WORKS: Docker Compose can merge multiple configuration files into a single composite one. By default, it automatically looks for docker-compose.yml and docker-compose.override.yml in the current directory and merges them. You can also explicitly specify which files to use and in what order with the -f flag, like docker compose -f file1.yml -f file2.yml up. The configuration from file2.yml is merged on top of file1.yml, with its values taking precedence in case of a conflict.

WHEN TO USE IT: Use this feature to separate environment-specific concerns. A base file can define your api and db services. A development override file can then add port mappings and volume mounts for live code reloading. A production file might define restart policies, resource limits, and logging configurations.

WHEN NOT TO USE IT: Avoid this for defining entirely separate applications; each set of files should describe variants of a single application. If you have a complex web of a dozen override files, your application may have outgrown Compose and could benefit from a more powerful orchestrator like Kubernetes.

ONE CANONICAL EXAMPLE: A common setup includes a docker-compose.yml with a web service. For local development, a docker-compose.override.yml is automatically included. This override file might add a volumes entry to mount your local source code into the container (./app:/code) and expose a port (ports: - "8000:8000"). For production, you would explicitly use a different file, docker compose -f docker-compose.yml -f docker-compose.prod.yml up, where docker-compose.prod.yml sets restart: unless-stopped and uses production environment variables.