# 왼쪽에서 오른쪽 순서로 파일을 병합한다.
docker compose -f compose.yaml -f compose.dev.yaml up -d

# 실제 적용 결과를 먼저 확인한다.
docker compose -f compose.yaml -f compose.dev.yaml config

# 운영 환경도 파일 조합을 명시한다.
docker compose -f compose.yaml -f compose.prod.yaml up -d

Compose 병합 규칙

기본 파일 탐색을 쓸 때는 override 파일이 자동 병합된다

같은 디렉터리에서 Compose의 기본 파일 탐색 규칙을 그대로 쓰고 있고 compose.yaml과 compose.override.yaml이 함께 있으면, docker compose up만 실행해도 두 파일이 자동으로 병합됩니다. 공통 설정은 기본 파일에, 로컬 개발용 bind mount나 디버그 포트 같은 차이는 override 파일에 두면 기본 명령을 바꾸지 않고 개발 편의를 추가할 수 있습니다. 반대로 -f로 파일 조합을 직접 지정하는 워크플로에서는 자동 병합에만 기대지 말고 실제로 어떤 파일이 적용되는지 명시적으로 확인하는 편이 안전합니다.

# compose.yaml (공통 기반)
services:
  app:
    image: myorg/app:latest
    ports:
      - "3000:3000"

# compose.override.yaml (자동 병합, 개발 편의 추가)
services:
  app:
    build: .          # 이미지 대신 로컬 빌드
    volumes:
      - .:/app        # 소스 코드 bind mount
    environment:
      DEBUG: "true"

-f 플래그로 여러 파일을 명시적으로 합치는 방법 — 환경마다 다른 파일 조합을 쓸 수 있다

-f 플래그를 여러 번 지정하면 파일을 왼쪽에서 오른쪽 순서로 병합합니다. 뒤에 나오는 파일의 설정이 앞 파일을 덮어씁니다. 자동 병합(override 파일)에 의존하지 않고 환경별 파일 조합을 명확하게 제어할 수 있어, 실수로 잘못된 설정이 섞이는 문제를 방지합니다.

# 개발 환경
docker compose -f compose.yaml -f compose.dev.yaml up -d

# 운영 환경 (restart 정책, 리소스 제한 추가)
docker compose -f compose.yaml -f compose.prod.yaml up -d

# compose.prod.yaml 예시
services:
  app:
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

자동 override와 명시적 -f 조합은 쓰는 목적이 다르다

compose.override.yaml은 로컬 개발 편의를 기본 명령에 자연스럽게 얹는 용도에 가깝고, -f compose.yaml -f compose.prod.yaml은 실행 환경을 명시적으로 고르는 용도에 가깝습니다. 팀 전체가 같은 개발 편의를 공유하면 자동 override가 편하지만, 운영/스테이징처럼 실수 비용이 큰 환경은 -f로 조합을 눈에 보이게 고르는 편이 안전합니다.

# 로컬 개발: 기본 + 자동 override
docker compose up -d

# 운영 배포: 어떤 파일을 섞는지 명시
docker compose -f compose.yaml -f compose.prod.yaml up -d

mapping, sequence, 고유 리소스는 같은 방식으로 합쳐지지 않는다

mapping은 뒤 파일의 같은 키가 앞 값을 바꾸면서 나머지 키를 합칩니다. 일반 sequence는 뒤 항목을 이어 붙이지만, command·entrypoint·healthcheck.test는 덮어써 한 명령만 남깁니다. ports, volumes, secrets, configs는 고유 키를 기준으로 병합하므로 단순 배열처럼 중복된다고 가정하지 않습니다. docker compose config로 결과를 확인해야 합니다.

# compose.yaml
services:
  app:
    ports:
      - "3000:3000"
    environment:
      LOG_LEVEL: info

# compose.dev.yaml
services:
  app:
    ports:
      - "9229:9229"   # 배열 병합 → 3000:3000도 유지됨
    environment:
      LOG_LEVEL: debug  # 맵 덮어쓰기 → debug로 교체됨

동일한 컨테이너 대상 경로를 가진 volume처럼 고유 키가 충돌하면 뒤 파일의 설정이 그 자원을 바꿉니다. 환경별 파일에서 bind mount의 대상 경로를 재사용할 때 특히 주의합니다.

병합 오류 예방