Docker Compose는 프로젝트 루트의 .env 파일을 자동으로 읽어 docker-compose.yml 안의 변수(${DB_PASSWORD} 등)를 치환합니다. 문제는 이 파일에 DB 비밀번호, API 키, JWT 시크릿 같은 민감한 값이 들어있다는 점입니다. 실수로 Git에 커밋하면 퍼블릭 레포라면 즉시 유출, 프라이빗 레포도 협력사 초대 등으로 언제든 위험해집니다.

확대

두 파일로 역할을 분리한다

.env.example 예시:

# 실습 디렉토리 준비
mkdir -p /tmp/docker/part3/exam_12 && cd /tmp/docker/part3/exam_12

# 앱 설정
APP_PORT=3000
NODE_ENV=development

# 데이터베이스
DB_HOST=db
DB_PORT=5432
DB_NAME=myapp
DB_USER=myuser
DB_PASSWORD=change_me_locally   # ← 예시값, 실제값은 .env에서 변경

# 외부 API
STRIPE_SECRET_KEY=sk_test_REPLACE_WITH_YOUR_KEY

.gitignore 설정

# .gitignore
.env
.env.local
.env.*.local

팀 온보딩 컨벤션

새 팀원이 레포를 클론하면 README에 딱 한 줄이 있습니다.

cp .env.example .env
# .env를 열어 DB_PASSWORD, STRIPE_SECRET_KEY 등을 실제 값으로 채우세요
# (값은 팀 1Password / Notion 비밀 문서에 있습니다)

이 패턴의 장점은 .env.example이 필요한 변수 목록 문서 역할을 한다는 것입니다. 새 변수를 추가하면 코드 변경과 함께 .env.example도 업데이트해 PR에 포함시키는 것이 팀 컨벤션이 됩니다. 코드를 보면 어떤 환경변수가 필요한지 바로 알 수 있어, "저만 알고 있었네요" 상황이 반복되지 않습니다.

Dockerfile 하나로 개발 환경과 프로덕션 환경을 모두 커버하는 것이 팀 표준의 핵심입니다. 멀티 스테이지 빌드(이전 모듈에서 학습)를 활용하면 FROM ... AS dev와 FROM ... AS final 두 타겟을 한 파일에 선언하고, 빌드 시 어떤 타겟을 쓸지 선택합니다.

확대

개발 vs 프로덕션 이미지의 차이

Node.js 예시 — 단일 Dockerfile, 두 타겟

# -- 공통 베이스 --
FROM node:20-alpine AS base
WORKDIR /app
COPY package*.json ./

# -- 개발 스테이지 --
FROM base AS dev
# devDependencies 포함 (nodemon, ts-node 등)
RUN npm install
COPY . .
# 소스는 볼륨/watch로 오버라이드되므로 COPY는 fallback
CMD ["npm", "run", "dev"]    # nodemon 등 hot reload 실행

# -- 프로덕션 스테이지 --
FROM base AS final
RUN npm ci --only=production
COPY . .
RUN npm run build            # 빌드 아티팩트 생성
CMD ["node", "dist/index.js"]

타겟 지정 빌드

# 개발 이미지 빌드 (Compose가 target: dev를 보고 자동 처리)
docker build --target dev -t myapp:dev .

# 프로덕션 이미지 빌드
docker build --target final -t myapp:prod .

docker-compose.yml에서 target: dev로 선언하면 make dev 실행 시 항상 개발 스테이지로 빌드됩니다. CI/CD 파이프라인은 target: final을 사용하거나 docker build --target final을 직접 호출합니다. 파일은 하나, 목적에 따라 다른 결과물을 얻는 구조입니다.

앞서 배운 요소들을 조합하면 온보딩이 단 두 단계로 압축됩니다.

확대

git clone https://github.com/myorg/myapp.git
cd myapp
cp .env.example .env        # 비밀값 채우기 (팀 문서 참고)
make dev                    # 끝

전체 파일 구조

팀 표준 개발 환경을 위한 최소 파일 세트입니다.

myapp/의 최소 파일 세트입니다.

• Makefile — 진입점 표준화
• docker-compose.yml — 서비스 정의 (develop.watch 포함)
• Dockerfile — dev / final 멀티 타겟
• .env.example — 필요한 변수 목록 (커밋)
• .env — 실제 비밀값 (.gitignore)
• .gitignore
• src/

README에 넣는 딱 세 줄

## 개발 환경 시작하기

git clone ... && cd myapp
cp .env.example .env  # .env 파일에 팀 문서의 값을 채워주세요
make dev

이 구조가 해결하는 문제

신입이 환경을 올리는 데 두 시간 걸리던 것이 15분으로 줄어듭니다. 더 중요한 것은 시니어가 옆에 앉아줄 필요가 없다는 점입니다.

리눅스 노트북에선 볼륨 마운트만으로 hot reload가 잘 되다가, 유독 맥·윈도우 팀원에게서만 "저장했는데 nodemon이 안 뜬다"는 제보가 옵니다. 같은 코드인데 OS에 따라 갈리는 이유는 파일 변경을 누가 감지하느냐에 있습니다.

• 컨테이너 안 도구는 inotify로 변경을 감지합니다. nodemon·webpack 같은 도구는 커널의 inotify 이벤트로 "파일이 바뀌었다"를 통지받습니다. 그런데 Docker Desktop에서 소스는 호스트(맥/윈도우) 파일시스템에 있고 컨테이너는 그 위에 얹힌 리눅스 VM 안에서 돕니다. 파일 내용은 virtiofs/gRPC-FUSE로 공유되지만, inotify 이벤트는 그 경계를 넘어오지 않습니다. 그래서 파일 내용은 바뀌어 있는데 컨테이너 안 nodemon은 "바뀐 줄 모릅니다".
• 리눅스 네이티브에선 이 문제가 없습니다. 바인드 마운트가 커널 레벨이라 inotify가 그대로 전달됩니다. 즉 이건 Docker 버그가 아니라 VM 경계의 구조적 한계이고, 그래서 "내 리눅스에선 되는데" 재현이 안 되는 것입니다.
• watch가 우회하는 방식이 핵심입니다. docker compose watch는 감시를 컨테이너 안이 아니라 호스트 쪽에서 수행하고, 변경을 감지하면 파일을 컨테이너로 push(sync)합니다. inotify 통지에 의존하지 않으니 OS와 무관하게 동작합니다.
• 한계도 알아야 씁니다. sync는 즉시가 아니라 짧은 지연이 있고, 시작 시 1회 전체 복사가 일어나며, ignore 규칙에 걸린 경로는 아예 감시되지 않습니다. rebuild 액션을 자주 트리거하는 경로를 잘못 걸면 매 저장마다 이미지가 다시 빌드돼 오히려 볼륨보다 느려집니다 — 어떤 파일에 sync를, 어떤 파일에 rebuild를 걸지는 설계의 문제입니다.