Docker Compose 개발 환경 구성 — 로컬 개발을 위한 실무 설정

프로덕션 이미지를 그대로 로컬에서 돌리면 코드 한 줄 바꿀 때마다 이미지를 새로 빌드해야 한다. Bind Mount와 Watch Mode를 활용하면 컨테이너를 재시작하지 않고도 변경 사항이 즉시 반영된다. 개발용 Compose 파일을 별도로 관리하면 프로덕션 설정을 오염시키지 않으면서도 빠른 피드백 루프를 유지할 수 있다.

디렉터리 구조

project/
├── docker-compose.yml          # 공통 베이스
├── docker-compose.dev.yml      # 개발 오버라이드
├── docker-compose.prod.yml     # 프로덕션 오버라이드
├── app/
│   └── src/
└── db/
    └── init.sql

베이스 파일에 공통 서비스 정의를 두고, 환경별 파일로 오버라이드한다. docker compose -f docker-compose.yml -f docker-compose.dev.yml up 명령으로 두 파일을 병합해 실행한다.

Bind Mount로 코드 실시간 반영

# docker-compose.dev.yml
services:
  app:
    build:
      context: .
      target: dev          # 멀티스테이지 빌드의 dev 스테이지
    volumes:
      - ./app/src:/app/src # 호스트 경로 : 컨테이너 경로
    environment:
      - NODE_ENV=development
    ports:
      - "3000:3000"        # 개발용 포트 노출
      - "9229:9229"        # Node.js 디버거 포트

Bind Mount: 호스트 파일시스템의 디렉터리를 컨테이너 내부에 직접 마운트하는 방식. 호스트에서 파일을 수정하면 컨테이너 내부에도 즉시 반영된다.

target: dev는 Dockerfile의 멀티스테이지 빌드에서 개발 전용 스테이지를 가리킨다. 프로덕션 이미지에는 포함되지 않는 개발 도구(nodemon, ts-node 등)를 이 스테이지에만 설치한다.

로컬 DB 연동

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp_dev
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
    ports:
      - "5432:5432"        # 로컬 DB 클라이언트 접속용
    volumes:
      - db_data:/var/lib/postgresql/data
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql

volumes:
  db_data:

Named Volume: 컨테이너가 삭제되어도 데이터를 보존하는 Docker 관리 볼륨. Bind Mount와 달리 Docker가 경로를 관리한다.

5432 포트를 호스트에 노출하면 DBeaver, TablePlus 같은 로컬 DB 클라이언트에서 바로 접속할 수 있다. init.sql은 최초 컨테이너 생성 시 한 번 실행되어 스키마와 시드 데이터를 초기화한다.

Watch Mode

Docker Compose v2.22부터 watch 서브커맨드가 정식 지원된다.

# docker-compose.dev.yml
services:
  app:
    develop:
      watch:
        - action: sync
          path: ./app/src
          target: /app/src
        - action: rebuild
          path: package.json

호스트 파일 변경 │ ▼ action: sync? ──Yes──▶ 컨테이너 내 경로로 즉시 동기화 │ No │ action: rebuild? ──Yes──▶ 이미지 재빌드 후 컨테이너 재시작

Watch Mode: docker compose watch 명령으로 활성화. 파일 변경을 감지해 sync(파일 복사) 또는 rebuild(이미지 재빌드) 액션을 자동 실행한다.

sync는 단순 파일 복사라 빠르고, rebuild는 의존성 변경처럼 이미지 재빌드가 필요한 경우에 쓴다. package.json이 바뀌면 npm install이 포함된 이미지를 다시 빌드해야 하므로 rebuild로 지정한다.

개발 vs 프로덕션 설정 비교

항목	개발	프로덕션
소스 마운트	Bind Mount	이미지에 복사(COPY)
포트 노출	디버거 포트 포함	필요한 포트만
환경 변수	`.env.dev`	Secret Manager
재시작 정책	`no`	`unless-stopped`
로그 레벨	`debug`	`warn`

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --watch 한 줄로 Watch Mode가 활성화된 개발 환경이 뜬다. 팀원 모두가 동일한 Compose 파일을 공유하므로 "내 로컬에서만 안 된다"는 상황이 줄어든다.