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.