Docker Compose Examples for Node.js Apps (2025)

Context

Node.js 애플리케이션 개발 시 PostgreSQL, Redis 등 의존성 서비스를 로컬 머신에 직접 설치·관리하면 팀원 간 환경 불일치가 발생하고 설정에 소요되는 시간이 늘어난다.

Technical Solution

• 단일 컨테이너 Node.js 앱 구성: Dockerfile에서 node:20-alpine 기반으로 /app 경로에서 npm ci --only=production 실행 후 포트 3000 노출
• depends_on with service_healthy 패턴 적용: DB 서비스의 healthcheck(pg_isready)가 통과할 때까지 애플리케이션 시작 지연으로 연결 실패 방지
• PostgreSQL 통합: postgres:16-alpine 이미지 사용, 데이터 영속성을 위해 postgres_data 네임드 볼륨 설정, ./db/init.sql을 docker-entrypoint-initdb.d에 마운트해 초기화 스크립트 자동 실행
• Redis 캐싱 계층 추가: redis:7-alpine 이미지 사용, REDIS_URL 환경변수를 통해 Node.js 앱에서 ioredis 클라이언트로 연결, healthcheck(redis-cli ping)로 준비 상태 확인
• 핫 리로드 개발 환경 구성: Dockerfile.dev에서 nodemon을 전역 설치하고 ./src:/app/src 볼륨 마운트해 파일 변경 시 자동 재시작

Key Takeaway

docker-compose.yml에서 service_healthy 조건과 healthcheck를 조합하면 다중 서비스 간 부팅 순서 문제를 자동으로 해결하고, 네임드 볼륨과 환경변수를 통해 팀 전체가 동일한 로컬 개발 환경을 유지할 수 있다.