Docker Compose Profiles and Overrides
One project often runs in several situations. Developers want debugging tools and live code reloading. Test servers want a clean setup. Production wants strict settings. Writing three separate Compose files from scratch creates duplication. Profiles and override files let one base file serve every situation.
Profiles: Switching Services On and Off
A profile is a label attached to a service. A labeled service stays asleep until you ask for its profile by name. Services without labels always start.
services:
web:
image: my-web
db:
image: postgres:16
adminer:
image: adminer
profiles: ["debug"]
seed-data:
image: my-seeder
profiles: ["setup"]
Running docker compose up -d starts web and db only. The debug and setup helpers wait quietly.
Activating a Profile
docker compose --profile debug up -d docker compose --profile debug --profile setup up -d COMPOSE_PROFILES=debug docker compose up -d
Each command wakes the matching services along with the always-on services.
When Profiles Shine
Profile Typical services --------- ---------------------------------------- debug database viewer, mail catcher setup one-time data loader, migration runner test test runner, mock external services monitoring metrics collector, dashboard
Override Files: Layering Settings
Compose reads two files by default. The base file is docker-compose.yml. The override file is docker-compose.override.yml. Compose merges them automatically, and values in the override win.
docker-compose.yml docker-compose.override.yml
------------------------ ---------------------------
services: services:
web: web:
image: my-web build: .
ports: volumes:
- "80:80" - ./src:/app/src
environment:
DEBUG: "true"
Think of the base file as a plain white shirt and the override as a jacket you add for a specific day.
How Merging Works
- Single values such as image or command are replaced by the override.
- Lists such as ports and volumes are combined.
- Mappings such as environment are merged key by key.
Using Named Files for Each Environment
The -f flag selects files explicitly. Compose merges them from left to right.
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
A production file might add restart policies and resource limits.
# docker-compose.prod.yml
services:
web:
restart: always
deploy:
resources:
limits:
memory: 512M
Typical File Layout
project/ docker-compose.yml shared base docker-compose.override.yml developer extras (loads automatically) docker-compose.prod.yml production settings (loaded with -f) docker-compose.test.yml test settings (loaded with -f)
Previewing the Merged Result
docker compose -f docker-compose.yml -f docker-compose.prod.yml config
The config command prints the final merged file. Review it before you deploy.
Profiles or Overrides
Question Use ---------------------------------------- --------- Should extra services appear sometimes? Profiles Should settings change per environment? Overrides
Both tools combine well. A project can use an override file for production settings and profiles for optional helpers.
Common Mistakes
- Leaving docker-compose.override.yml in a production folder, which loads development settings by accident.
- Listing a profile service in depends_on from an always-on service. Compose then fails because the dependency stays asleep.
- Forgetting the order of -f flags. The last file wins.
Real-World Scenario
A startup builds a booking website with a web service, an API, and a database. During development, engineers want a database viewer and a mail catcher that captures test emails. These helpers have no place on the production server. The team marks both helpers with a debug profile. Developers run the stack with the profile on their laptops, and the production server runs the same file without it.
The developers also want live code reloading. Their override file mounts the source folder into the web container and turns on debug mode. The override file loads automatically on laptops. The production server never loads it, because the deployment script names the base file and the production file explicitly with the -f flag.
Why This Design Reduces Errors
Every environment shares one base definition, so a new service or a changed image name appears everywhere at once. Teams that copy whole files between environments forget to update one copy, and the environments drift apart. A shared base with small layers on top keeps differences visible and short. A reviewer can open the override file and see in ten lines exactly how production differs from development.
Practice Exercise
Create a base file with a web service. Add an override file that publishes port 8081 and sets an environment variable. Run docker compose config and read the merged result. Add a service with a profile and start the stack with and without the profile flag. Compare the container lists.
