Docker Compose로 개발 환경 통일하고 온보딩 줄이기

“제 노트북에서는 되는데요”는 팀 생산성을 깎습니다. Docker는 만능은 아니지만, 앱+DB를 같은 방식으로 올리는 표준을 만들기 좋습니다.

준비물#

Docker Desktop (Windows/Mac) 또는 Linux 엔진
샘플 프로젝트 1개
소요: 첫 compose 1~2시간 (삽질 포함 정상)

최소 compose 예제#

docker-compose.yml (키 문법은 Docker Compose V2 기준, version 필드는 최신에서 생략 가능):

1
services:
2
  web:
3
    build: .
4
    ports:
5
      - "3000:3000"
6
    environment:
7
      DATABASE_URL: postgres://dev:devpass@db:5432/app
8
    volumes:
9
      - .:/app
10
    depends_on:
11
      - db
12
  db:
13
    image: postgres:16
14
    environment:
15
      POSTGRES_USER: dev
16
      POSTGRES_PASSWORD: devpass
17
      POSTGRES_DB: app
18
    ports:
19
      - "5432:5432"
20
    volumes:
21
      - pgdata:/var/lib/postgresql/data
22
volumes:
23
  pgdata:

1
# 예시 Dockerfile (Node)
2
FROM node:20-alpine
3
WORKDIR /app
4
COPY package*.json ./
5
RUN npm ci
6
COPY . .
7
CMD ["npm", "run", "dev"]

실행:

1
docker compose up --build

온보딩 README 체크리스트#

Docker 설치 링크
cp .env.example .env
docker compose up --build
헬스 URL (예: http://localhost:3000/health)
자주 나는 오류 3개와 해결

흔한 실패와 해결#

문제	원인	해결
node_modules 충돌	호스트·컨테이너 바이너리 혼선	익명 볼륨 또는 컨테이너 안 설치, `.dockerignore`
포트 충돌	로컬에 이미 DB	ports 매핑 변경
권한 오류 (Linux)	UID	user 지정 또는 개발용 완화 (보안 검토)
느린 바인드 마운트 (Mac/Win)	파일 동기화	문서 캐시 옵션·필요한 경로만 마운트

.dockerignore 예:

1
node_modules
2
.git
3
.env
4
npm-debug.log

FAQ#

Q. 로컬 설치와 병행? 가능. 다만 팀 표준은 compose 한 가지로 통일하는 편이 온보딩에 유리.

Q. 프로덕션과 동일한가? 개발 compose는 편의 설정이 많음. 프로덕션은 이미지 태그 고정·시크릿·리소스 제한이 다름.

팀 온보딩 스크립트 예#

1
#!/usr/bin/env bash
2
set -euo pipefail
3
cp -n .env.example .env || true
4
docker compose pull
5
docker compose up --build -d
6
echo "open http://localhost:3000"

시크릿 관리#

.env는 git 제외
예시 값은 .env.example에만
프로덕션 시크릿을 개발 compose에 복사하지 않기

헬스체크 엔드포인트 예 (개념)#

앱이 뜨면 /health가 200을 반환하게 두고, README에 적어 온보딩자가 성공을 확인하게 합니다.

compose 로그 보기#

1
docker compose logs -f web
2
docker compose ps

추가 FAQ#

Q. Apple Silicon / Windows 차이? 이미지 플랫폼 경고가 뜨면 공식 멀티아키 이미지를 쓰거나 문서에 명시합니다.

주말 실습: 샘플 스택 기동#

docker compose up까지 진행한다. README에 명령 3줄·실패 사례 1개·헬스 URL을 적어 다른 PC 기준으로 읽히는지 검토한다.

한계와 현실적인 기대#

Docker는 은탄환이 아닙니다. GUI 설치 앱, 커널 모듈, GPU 개발처럼 컨테이너화가 비용 큰 영역도 있습니다. 그래도 웹+DB 조합의 “환경 불일치” 비용이 크다면 compose 표준화 이득이 큽니다. 온보딩 README에 실패 사례를 숨기지 마세요. 새 팀원은 성공 경로보다 실패 경로에서 시간을 잃습니다. 이미지 태그는 latest 대신 가능한 한 고정 태그를 쓰고, 보안 업데이트 주기를 팀 규칙으로 정하세요.

Docker Compose로 개발 환경 통일하고 온보딩 줄이기 본문 이미지

실습 체크리스트 (Docker Compose)#

docker compose up --build가 재현되는가
.env.example과 .dockerignore가 있는가
DB 볼륨·포트 충돌을 확인했는가
헬스 URL로 기동을 검증했는가
온보딩 README 5단계를 동료가 따라 할 수 있는가

온보딩 시나리오 테스트#

README가 좋은지 확인하는 가장 확실한 방법은 처음 보는 사람(또는 다른 팀 동료) 에게 타이머를 켜고 따라 하게 하는 것입니다. 20분 안에 health가 뜨지 않으면 문서 또는 compose가 부족한 것입니다.

체크 포인트:

사전 설치(도커) 링크가 맞는가
환경변수 예시가 실제 키 이름과 같은가
첫 기동 로그에서 자주 보는 경고를 문서화했는가
종료/초기화 명령이 있는가 (down -v 위험 고지 포함)

시크릿 다루기#

개발용 기본 비밀번호를 문서에 쓰더라도 운영 값과 동일한 패턴을 쓰지 마세요. .env는 git ignore, 예시는 .env.example만. 스크린샷에 토큰이 들어가지 않게 편집합니다.

팀 표준 명령 고정#

docker-compose와 docker compose가 섞이면 신입이 헤맵니다. 저장소 전역에서 한 가지 표기만 쓰고, Makefile 또는 패키지 스크립트로 감싸면 교육 비용이 줄어듭니다. Apple Silicon/Windows/Linux가 섞인 팀이면 알려진 이슈 절을 README 상단에 두는 것이 본문 튜토리얼보다 먼저입니다.

이 글을 끝내면 할 수 있는 것#

앱+DB를 docker compose up 한 번으로 올린다.
온보딩 README 5단계를 팀에 배포한다.
볼륨·포트·권한 실패를 표로 해결한다.

개발용 vs 운영용 경계#

개발: 바인드 마운트, 핫 리로드, 약한 비밀번호(로컬만).
운영: 이미지 태그 고정, 시크릿 주입, 읽기 전용 루트 FS 검토. 이 글은 로컬 개발 통일에 초점을 둡니다.

트러블슈팅 보강#

증상	원인	해결
빌드 캐시 꼬임	레이어 캐시	`build --no-cache` 1회
DB 데이터 증발	볼륨 미설정	named volume 확인
핫 리로드 안 됨	폴링 미설정	CHOKIDAR/WATCHPACK 등
Apple Silicon 이미지	플랫폼 불일치	platform 명시 또는 멀티아키
디스크 full	이미지 방치	`docker system prune` (주의)

FAQ 보강#

Q. Podman으로 대체 가능한가요? 많은 경우 호환됩니다. 팀 표준 명령을 README에 하나로 고정하세요.

Q. Windows에서 느려요. 파일 마운트 성능 이슈가 흔합니다. 소스 위치를 WSL2 파일시스템 쪽으로 두는 구성이 유리할 때가 많습니다.

Q. 프로덕션 배포에도 그대로? 아니요. 개발 compose를 그대로 운영에 쓰지 마세요.

현장에서 바로 쓰는 Docker Compose 운영 노트#

이 절은 Docker Compose 본문을 읽은 뒤 다음 영업일 안에 실행할 때 참고하는 운영 메모입니다. 도구 이름보다 중요한 것은 반복 가능한 순서와 실패 기록입니다. 처음 한 주는 완벽한 세팅보다 ‘최소 성공 1회’를 목표로 하세요. 성공 기준을 숫자나 체크박스로 적어 두면 나중에 회고할 때 감이 아니라 데이터로 판단할 수 있습니다.

첫 48시간 실행 계획 (Docker Compose)#

준비물 절을 보고 계정·설치·권한을 먼저 끝낸다. 본론 중간에서 설치하면 흐름이 끊긴다.
본문의 핵심 절차 중 가장 작은 단위 하나만 끝까지 재현한다.
트러블슈팅 표에서 해당 증상 행을 찾아 해결을 적용하고, 없으면 새 행을 메모한다.
FAQ에서 비용·보안·팀 도입 질문을 읽고 내 환경에 해당하는지 표시한다.
실습 체크리스트를 인쇄하거나 이슈 한 장에 옮겨 완료 표시를 남긴다.
동료가 있다면 5분 데모를 보여 주고, 설명 중 막힌 지점을 문서에 보완한다.

품질을 유지하는 주간 루틴#

Docker Compose 관련 설정과 문서는 한 번 만들고 방치하면 금방 낡습니다. 매주 15분만 투자해 다음을 점검하세요. 지난주에 새로 생긴 예외 상황, 팀원이 물은 질문, 실패한 명령, 유료 결제 여부, 보안 정책 변경 여부입니다. 변경이 있으면 본문 요약이 아니라 체크리스트와 트러블슈팅 표를 먼저 고칩니다. 긴 서론을 고치는 것보다 표 한 줄이 다음 독자를 더 많이 구합니다.

혼자 일할 때와 팀에서 쓸 때의 차이#

개인 사이드 프로젝트에서는 속도와 실험이 우선일 수 있습니다. 하지만 팀 저장소·고객 데이터·공통 인프라가 걸리면 Docker Compose 사용 방식이 달라져야 합니다. 권한, 감사 로그, 승인 단계, 공유 채널 공지 같은 사회적 절차가 기술적 절차만큼 중요합니다. 모호하면 보수적으로 선택하세요. 막힌 시간을 줄이려다 사고를 키우는 경우가 더 비쌉니다. 팀 합의 문장이 없다면 이 글의 체크리스트를 복사해 ‘우리 팀 버전’ 헤더만 바꿔 공유하는 것으로 충분합니다.

측정 지표 제안#

지표	측정 방법	해석
첫 성공까지 시간	타이머	온보딩 문서 개선 신호
주간 재사용 횟수	간단한 해시 체크	습관 정착 여부
실패 재발	같은 증상 메모	트러블슈팅 보강 필요
도움 요청 횟수	슬랙/구두	문서 공백 위치
중단 결정	2주 후 유지/폐기	도구 과잉 방지

폐기 기준 (중요)#

Docker Compose가 팀에 안 맞을 수도 있습니다. 실패를 인정하는 기준을 미리 정하세요. 예를 들어 2주 동안 핵심 절차를 3회 이상 재현하지 못했거나, 보안 검토에서 막혔거나, 기존 도구 대비 명확한 이득이 없으면 중단이 올바른 결정입니다. 중단할 때도 설정 내보내기·권한 회수·문서 보관 위치를 남겨 두면 다음에 재도전할 때 비용이 줄어듭니다. 생산성 글의 목적은 도구 수집이 아니라 더 적은 마찰로 같은 품질의 결과를 내는 것입니다.

독자가 자주 놓치는 디테일#

버전을 안 적으면 한 달 뒤 같은 글이 거짓이 됩니다. 환경 절에 버전을 남기세요.
스크린샷만 있고 텍스트 명령이 없으면 접근성과 검색성이 떨어집니다.
성공 로그만 남기고 실패 로그를 지우면 학습이 사라집니다.
다른 글과 주제가 비슷할 때는 이 글의 완료 정의만 다시 읽고 범위를 지키세요.
공유 전에 시크릿·사내 URL·고객명이 있는지 검색하세요.

정리#

Docker의 목표는 컨테이너 전문가 되기보다 신규 합류자가 반나절 안에 서버를 띄우는 것입니다.

참고: Docker 문서 · Compose