Docker Compose — Multi-File Compose

For complex projects, split your configuration across multiple compose files for different environments, teams, or concerns.

The -f Flag

# Combine base + environment-specific file
docker compose -f compose.yml -f compose.dev.yml up -d
docker compose -f compose.yml -f compose.prod.yml up -d
docker compose -f compose.yml -f compose.test.yml up -d

Files are merged left to right — later files override earlier ones.

Project Structure

project/
├── compose.yml              # Base services
├── compose.override.yml     # Auto-loaded dev config
├── compose.dev.yml          # Explicit dev config
├── compose.prod.yml         # Production config
├── compose.test.yml         # Test config
├── compose.monitoring.yml   # Monitoring stack
└── .env                     # Environment variables

Environment Variable

export COMPOSE_FILE=compose.yml:compose.prod.yml
docker compose up -d

Or in .env:

COMPOSE_FILE=compose.yml:compose.prod.yml

The separator is : on Linux/macOS and ; on Windows.

Practical Example

compose.yml (base):

services:
  api:
    image: myapi:latest
    ports:
      - "3000:3000"
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data
volumes:
  db-data:

compose.dev.yml:

services:
  api:
    build: ./api
    volumes:
      - ./api:/app
    command: npm run dev
    environment:
      NODE_ENV: development
  adminer:
    image: adminer
    ports:
      - "8080:8080"

compose.prod.yml:

services:
  api:
    image: ghcr.io/myorg/api:${VERSION}
    restart: unless-stopped
    environment:
      NODE_ENV: production
  db:
    restart: unless-stopped

Makefile for Convenience

dev:
	docker compose -f compose.yml -f compose.dev.yml up -d

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

test:
	docker compose -f compose.yml -f compose.test.yml run --rm test

down:
	docker compose down -v

make dev     # Start development
make prod    # Start production
make test    # Run tests

include vs -f

Feature	include:	-f flag
Where	In compose.yml	CLI argument
Merge	Side by side (additive)	Override/merge
Self-contained	Yes	No (needs CLI)
Version	v2.20+	Always

Summary

Approach	Use Case
Override (auto)	Default dev settings
-f flag	Environment-specific configs
COMPOSE_FILE	Persistent multi-file setup
include:	Modular additive composition
Makefile	Team-friendly shortcuts

---

Quick Reference

Item	Detail
-f a.yml -f b.yml	Merge multiple files
COMPOSE_FILE	Env var for default files
compose.override.yml	Auto-loaded (dev defaults)
Left to right	Later files override earlier
Makefile	Team shortcuts for compose commands