NestJS · Docker

NestJS 컨테이너 이미지의 빌드 경계

Docker 컨테이너화는 로컬 앱을 그대로 포장하는 일이 아니라, 빌드 단계와 실행 단계를 분리해 작고 재현 가능한 런타임 이미지를 만드는 과정이다.

01

의존성 설치

lockfile 기준으로 재현 가능한 npm ci 또는 pnpm install을 수행한다.

02

소스 빌드

TypeScript를 dist로 컴파일하고 테스트 또는 lint를 별도 단계에서 검증한다.

03

런타임 축소

최종 이미지는 dist, package metadata, production dependency만 담는다.

04

실행 설정

PORT와 NODE_ENV는 컨테이너 실행 시 주입하고 health endpoint를 연결한다.

Multi-stage
이미지 크기 축소 빌드 도구를 최종 이미지에서 제거
복사 경로 확인
npm ci
잠금 파일 재현 CI와 Docker build에서 같은 dependency tree 설치
lockfile 필수
non-root
권한 최소화 컨테이너 프로세스를 root가 아닌 사용자로 실행
파일 권한 조정 필요
healthcheck
healthcheck 상태 판정 오케스트레이터가 죽은 인스턴스를 교체
준비와 생존을 구분

비밀값 · 크기 · 포트 점검

비밀값 Dockerfile ARG나 ENV에 비밀을 고정하지 않는다.
크기 개발 의존성과 소스 맵 노출을 의도적으로 결정한다.
포트 Nest listen 포트와 컨테이너 노출 포트가 맞다.
종료 SIGTERM 수신 시 연결을 정리하고 graceful shutdown 한다.