[Docker Compose][Watch] bind mount와 sync·rebuild를 언제 나눠 써야 하나

IT 리서치 노트

[Docker Compose][Watch] bind mount와 sync·rebuild를 언제 나눠 써야 하나

Docker Compose Watch와 bind mount는 모두 로컬 변경을 개발 컨테이너에 반영하지만 역할이 다르다. 2026년 9월 8일 KST 기준 Watch는 Compose 2.22.0 이상에서 sync와 rebuild를 제어한다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

소스 hot reload는 sync, 의존성 파일은 rebuild, 양방향 공유 데이터는 bind mount로 나눈다. 플랫폼 의존 결과물은 동기화하지 않는다.

Docker Compose ps·logs·inspect 진단 순서와 depends_on service_healthy 설정법을 함께 보면 설정 확인 뒤 런타임 장애까지 이어서 점검할 수 있다.

2. 어디서 실제로 막히는가

프로젝트 전체 bind mount는 작은 파일이 많은 폴더에서 I/O를 늘리고 macOS host의 native module이 Linux 컨테이너 파일을 덮을 수 있다. 모든 변경을 rebuild하면 저장할 때마다 개발 루프가 느려진다. 실패를 확인할 때는 명령이 0으로 끝났는지만 보지 않는다. 예상한 서비스 이름, 이미지 태그, 마운트 경로와 실제 출력이 일치하는지 확인하고, 다른 터미널과 CI에서도 같은 명령을 실행한다. 한쪽에서만 결과가 다르면 Compose 파일보다 실행 위치, CLI 버전, 활성 profile, shell 환경을 먼저 비교한다. 설정 변경 뒤 컨테이너가 계속 예전 값으로 뜨면 기존 컨테이너와 볼륨이 남았는지도 확인한다. 재현 기록에는 docker compose version, pwd, 사용한 -f와 --env-file, 실행 명령, 종료 코드, 핵심 출력만 남긴다.

• 실행 디렉터리와 명령 인자를 기록한다.
• 예상값과 실제 출력을 같은 표로 비교한다.
• 경고, 종료 코드, 서비스 상태를 함께 확인한다.
• 비밀값은 출력과 화면에서 제거한다.

파일 저장은 감지되지만 애플리케이션이 바뀌지 않는다면 sync 대상 경로, 컨테이너 사용자 권한, 프레임워크의 hot reload 감시 경로를 함께 봐야 한다. rebuild 이벤트가 반복되면 lockfile이나 생성 파일이 watch 범위에 잘못 들어갔는지도 확인한다.

3. 실무에서 적용하는 순서

Compose 버전과 local build 사용 여부를 확인한다. src에는 sync, lockfile에는 rebuild를 지정하고 .dockerignore와 watch ignore를 점검한다. 로그에서 두 이벤트를 구분한다. 검증은 작은 재현부터 시작한다. 복사한 최소 Compose 파일에서 관련 서비스 하나만 남기고 config -q로 문법을 확인한다. 다음으로 config 또는 config --services 출력에서 원하는 설정이 실제 모델에 포함됐는지 본다. 그 뒤 docker compose up을 실행하고 ps와 logs에서 컨테이너 상태와 변경 반영 여부를 확인한다. 실패하면 동시에 여러 값을 바꾸지 말고 환경변수, profile, watch 규칙을 하나씩 되돌린다. 성공 기준은 로컬과 CI의 렌더링 결과가 같고, 재생성한 컨테이너의 설정과 로그가 기대값을 보여 주는 것이다.

1. 현재 버전과 실행 위치를 확인한다.
2. 공식 명령으로 최종 설정을 렌더링한다.
3. 한 변수 또는 한 서비스만 바꿔 재현한다.
4. ps와 logs에서 런타임 결과를 확인한다.
5. 성공·실패 출력을 저장해 비교한다.
6. CI에 검증 명령을 추가한다.

docker compose config -q
docker compose ps
docker compose logs --tail=100

4. 공식 문서와 예시 화면으로 확인하기

Watch와 bind mount의 경계를 공식 문서에서 확인한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

Watch는 bind mount를 없애는 기능이 아니라 컨테이너 개발에 맞춘 동반 기능이다.

ignore와 action 제어가 필요한지가 선택 기준이다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

지원 버전도 확인한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

Compose Watch는 Docker Compose 2.22.0 이상이 필요하다.

팀원별 Compose 버전 차이를 먼저 제거한다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

변경 종류별 반영 방식을 나눈다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

sync·rebuild·bind mount 선택표다.

native dependency는 host와 container 사이에 공유하지 않는다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

develop.watch 규칙을 파일 종류별로 나눈다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

src는 sync, lockfile은 rebuild하는 예시다.

node_modules는 동기화에서 제외한다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

실행 뒤 이벤트를 확인한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

Watch 검증 명령이다.

소스 변경이 rebuild 없이 반영되는지 본다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

5. 주의사항과 리스크

Watch 경로는 project directory 기준이며 glob을 지원하지 않는다. target 쓰기 권한이 필요하며 pre-built image만 쓰는 서비스에는 맞지 않는다.

6. 결론

소스는 sync, 의존성은 rebuild로 분리하고 공유 데이터만 bind mount에 남기면 빠른 개발 루프와 플랫폼 일관성을 함께 지킬 수 있다. 변경 전후의 렌더링 결과와 런타임 로그를 함께 남기면 다음 장애에서도 같은 순서로 재현할 수 있다.

7. 참고 링크

1. https://docs.docker.com/compose/how-tos/file-watch/