Docker Compose Override Files: Managing Dev vs Prod Configs

Docker Compose override files let you maintain one base configuration with environment-specific adjustments layered on top — avoiding duplicated, drifting compose files for each environment.

The Problem This Solves

Development and production often need different settings (different environment variables, resource limits, exposed ports for debugging) — maintaining entirely separate compose files for each environment leads to duplication and drift; override files let you share a common base while cleanly layering differences.

Base Configuration

nano docker-compose.yml
services:
  app:
    build: .
    environment:
      - NODE_ENV=production
    restart: unless-stopped

  db:
    image: postgres:16
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Development Override

nano docker-compose.override.yml
services:
  app:
    build:
      target: development
    environment:
      - NODE_ENV=development
    volumes:
      - ./src:/app/src
    ports:
      - "9229:9229"

docker-compose.override.yml is automatically applied when present, without needing to specify it explicitly — ideal for a local development default.

Using the Base + Override Automatically

docker compose up -d

Docker Compose automatically merges docker-compose.yml with docker-compose.override.yml if the latter exists in the same directory.

Production-Specific Override

nano docker-compose.prod.yml
services:
  app:
    deploy:
      resources:
        limits:
          memory: 1G
    restart: always

Explicitly Combining Base + a Named Override File

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Unlike the automatically-applied docker-compose.override.yml, named files like docker-compose.prod.yml must be explicitly specified with -f.

How Merging Works

Override files merge with (not replace) the base configuration — specific values in the override take precedence, while unspecified settings inherit from the base; understand this merge behavior to avoid unexpected configuration combinations.

Keeping Secrets Out of Compose Files

See Docker Compose .env Files and Environment Variables Explained — combine override files (for structural differences) with .env files (for actual secret values) rather than hardcoding sensitive values directly in any compose file, including overrides.

Organizing Multiple Environment Overrides

docker-compose.yml           # base
docker-compose.override.yml  # local dev (auto-applied)
docker-compose.staging.yml   # staging-specific
docker-compose.prod.yml      # production-specific

Combining with Profiles for Even More Flexibility

See How to Use Docker Compose Profiles and Multiple Environments — profiles and override files are complementary techniques; profiles control which services run, override files control how they're configured.

Common Errors

Unexpected configuration in a specific environment — use docker compose config to view the fully merged, effective configuration, helping you understand exactly what's being applied after all overrides are combined.

Continue Reading

Browse more articles in Docker & Containers.

  • docker compose override, docker compose dev vs prod, docker compose environments, docker-compose.override.yml
  • 0 brukere syntes dette svaret var til hjelp
Var dette svaret til hjelp?

Relaterte artikler

How to Install Docker Engine on Ubuntu & Debian (Complete Guide)

Docker lets you package applications and their dependencies into lightweight, isolated containers...

How to Install Docker Compose on Ubuntu & Debian

Docker Compose lets you define and run multi-container applications from a single YAML file,...

Deploy Your First Docker Container: A Beginner's Walkthrough

With Docker installed, this hands-on walkthrough covers the core workflow you'll use constantly:...

How to Update Docker and Docker Compose Safely

Keeping Docker Engine and Compose updated brings security fixes, performance improvements, and...

Docker Compose Troubleshooting: Common Errors & Fixes

A reference guide to the Docker and Docker Compose errors you're most likely to encounter, with...