Introduction to Docker Compose Override Files

What Are Override Files?

Docker Compose supports layered configuration files. The base docker-compose.yml defines your services, while override files modify settings for specific environments.

Default Behavior

When you run docker compose up, Compose automatically merges:

1. docker-compose.yml (base)
2. docker-compose.override.yml (if it exists)

Example: Development Override

Base file (docker-compose.yml):

services:
  app:
    image: myapp:latest
    environment:
      - NODE_ENV=production

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

volumes:
  pgdata:

Override file (docker-compose.override.yml):

services:
  app:
    build: .
    volumes:
      - ./src:/app/src
    environment:
      - NODE_ENV=development
      - DEBUG=true
    ports:
      - "3000:3000"
      - "9229:9229"  # Debug port

  db:
    ports:
      - "5432:5432"  # Expose DB for local tools

Production Override

# docker-compose.prod.yml
services:
  app:
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M
    logging:
      driver: json-file
      options:
        max-size: "10m"

# Use in production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Best Practices

• Base file: service definitions, volumes, networks
• Override file: development settings (ports, debug, live reload)
• Production file: resource limits, logging, restart policies
• Add docker-compose.override.yml to .gitignore for local-only settings