Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

Loading category cards

Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.

DockerCompose와 멀티컨테이너

Compose override 파일

환경별 차이를 Compose 파일 분리로 관리하는 기본 패턴을 정리합니다.

마지막 수정 2026년 4월 2일

빠른 흐름

bash

# -f로 파일을 명시하면 뒤에 오는 파일이 앞 설정을 덮어씀
docker compose -f compose.yaml -f compose.dev.yaml up -d

# 운영 환경
docker compose -f compose.yaml -f compose.prod.yaml up -d

설정 흐름

어떤 Compose 파일 분리 방식을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
로컬 개발 편의만 얹기	`compose.override.yaml`
환경별 명시적 파일 조합	`-f` 플래그
병합 결과를 확인하고 싶다	`docker compose config`
개인 설정을 저장소 밖으로 빼기	override 파일 + `.gitignore`

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

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

yaml

# 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 파일)에 의존하지 않고 환경별 파일 조합을 명확하게 제어할 수 있어, 실수로 잘못된 설정이 섞이는 문제를 방지합니다.

bash

# 개발 환경
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로 조합을 눈에 보이게 고르는 편이 안전합니다.

bash

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

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

배열 vs 맵 병합 규칙 — 배열은 합쳐지고, 맵은 덮어씌워진다

Compose 병합 시 ports, volumes, env_file처럼 배열 타입 필드는 두 파일의 항목이 합쳐집니다. 반면 environment처럼 맵(키-값) 타입 필드는 뒤 파일의 값이 앞 파일 값을 덮어씁니다. 이 차이를 모르면 포트가 중복 등록되거나 환경 변수가 예상과 다르게 적용될 수 있습니다.

yaml

# 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로 교체됨

체크포인트

상황	적합한 선택
로컬 개발 편의 설정 추가	compose.override.yaml (자동 병합)
환경별 명시적 파일 조합	-f 플래그로 파일 지정
공통 기반에 운영 전용 설정 추가	compose.yaml + compose.prod.yaml
배열 필드 병합 결과 확인	`docker compose config`로 최종 설정 출력
팀원마다 개인 설정을 .gitignore에 넣을 때	compose.override.yaml을 .gitignore에 추가

주의할 점

병합 결과가 예상과 다를 때는 docker compose config로 최종 설정을 확인해야 한다. 배열과 맵의 병합 규칙이 다르고, 파일 순서와 실행 방식이 결과에 영향을 주기 때문에 직관적이지 않은 결과가 나올 수 있습니다. 특히 운영 배포 전에는 최종 설정을 눈으로 확인하는 편이 안전합니다.

yaml

# compose.override.yaml
services:
  app:
    volumes:
      - .:/app

bash

# override 자동 병합을 잊고 서버에서 그냥 실행
docker compose up -d
# 운영 서버 경로 구조에 따라 bind mount가 깨지거나,
# 이미지에 들어 있던 코드가 가려질 수 있음

참고 링크

1 sources

Docker Docs: Use multiple Compose files

Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

DockerCompose와 멀티컨테이너

Compose override 파일

환경별 차이를 Compose 파일 분리로 관리하는 기본 패턴을 정리합니다.

마지막 수정 2026년 4월 2일

빠른 흐름

bash

# -f로 파일을 명시하면 뒤에 오는 파일이 앞 설정을 덮어씀
docker compose -f compose.yaml -f compose.dev.yaml up -d

# 운영 환경
docker compose -f compose.yaml -f compose.prod.yaml up -d

설정 흐름

어떤 Compose 파일 분리 방식을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
로컬 개발 편의만 얹기	`compose.override.yaml`
환경별 명시적 파일 조합	`-f` 플래그
병합 결과를 확인하고 싶다	`docker compose config`
개인 설정을 저장소 밖으로 빼기	override 파일 + `.gitignore`

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

yaml

# 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 플래그로 여러 파일을 명시적으로 합치는 방법 — 환경마다 다른 파일 조합을 쓸 수 있다

bash

# 개발 환경
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 조합은 쓰는 목적이 다르다

bash

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

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

배열 vs 맵 병합 규칙 — 배열은 합쳐지고, 맵은 덮어씌워진다

yaml

# 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로 교체됨

체크포인트

상황	적합한 선택
로컬 개발 편의 설정 추가	compose.override.yaml (자동 병합)
환경별 명시적 파일 조합	-f 플래그로 파일 지정
공통 기반에 운영 전용 설정 추가	compose.yaml + compose.prod.yaml
배열 필드 병합 결과 확인	`docker compose config`로 최종 설정 출력
팀원마다 개인 설정을 .gitignore에 넣을 때	compose.override.yaml을 .gitignore에 추가

주의할 점

yaml

# compose.override.yaml
services:
  app:
    volumes:
      - .:/app

bash

# override 자동 병합을 잊고 서버에서 그냥 실행
docker compose up -d
# 운영 서버 경로 구조에 따라 bind mount가 깨지거나,
# 이미지에 들어 있던 코드가 가려질 수 있음

참고 링크

1 sources

Docker Docs: Use multiple Compose files