Docker를 이용한 컨테이너화

11장에서는 NestJS 애플리케이션의 배포와 운영을 다룹니다. 첫 글인 이 글에서는 Docker를 이용한 컨테이너화를 설명합니다.

개발 환경과 운영 환경의 차이는 흔히 “내 컴퓨터에서는 잘 되는데” 하는 문제로 드러납니다. Docker는 애플리케이션과 그 실행에 필요한 사용자 공간의 의존성을 하나의 이미지로 묶어 이 차이를 줄입니다.

컨테이너란

컨테이너는 애플리케이션 코드, 런타임, 시스템 도구와 라이브러리를 묶어 실행하는 단위입니다. Linux 컨테이너는 네임스페이스와 cgroup 같은 커널 기능으로 프로세스와 자원을 어느 정도 격리하지만, VM처럼 별도의 게스트 커널을 넣지 않고 호스트(또는 Docker Desktop VM)의 커널을 함께 씁니다. 네임스페이스와 cgroup이 각각 무엇을 나누고 제한하는지는 컨테이너와 Docker에서 자세히 볼 수 있습니다.

• 격리성: 프로세스, 파일 시스템, 네트워크를 나눌 수 있습니다. 다만 권한, 마운트, 커널 취약점에 따라 격리의 강도가 달라지므로 절대적인 보안 장벽으로 여기지 않습니다.
• 이식성: 대상 OS, CPU 아키텍처, 런타임 조건이 같다면 같은 이미지를 여러 환경에 일관되게 배포할 수 있습니다. 다른 아키텍처까지 지원하려면 멀티 플랫폼 이미지를 빌드해야 합니다.
• 경량성: 게스트 OS 전체를 담는 VM보다 대체로 시작이 빠르고 이미지가 작습니다.
• 일관성: 이미지로 고정한 사용자 공간의 의존성 덕분에 개발, 테스트, 운영 환경의 차이가 줄어듭니다.

컨테이너와 가상 머신(VM)은 다음과 같이 비교할 수 있습니다.

Docker란

Docker는 컨테이너 이미지를 빌드하고, 배포하고, 실행하고, 관리하는 도구와 서비스를 제공합니다.

• Dockerfile: 이미지를 빌드하는 명령을 적은 텍스트 파일입니다.
• 이미지(image): 컨테이너를 만드는 읽기 전용 이미지입니다.
• 컨테이너(container): 이미지를 바탕으로 실행되는 프로세스 집합입니다.
• Docker Daemon: 이미지와 컨테이너를 관리하는 백그라운드 서비스입니다.
• Docker CLI: Docker Daemon과 상호작용하는 명령줄 도구입니다.
• 레지스트리(registry): 이미지를 저장하고 배포하는 저장소이며, Docker Hub가 대표적인 공개 레지스트리입니다.

위 그림은 소스에서 운영까지 이어지는 안전한 빌드·배포 경로를 보여 줍니다. 작업 폴더의 입력을 .dockerignore로 걸러 빌드에 넘기고, builder 단계와 프로덕션 의존성 단계를 거쳐 실행용 이미지를 만듭니다. 레지스트리에 올린 이미지의 digest를 기록하고, 검증과 운영 승인을 받은 바로 그 digest로 컨테이너를 배포합니다. 실행 시점의 설정과 비밀, 헬스 확인과 재시도, 표준 출력 로그는 이미지 바깥의 운영 영역으로 분리되어 있습니다.

NestJS 애플리케이션 컨테이너화

Dockerfile 작성

프로젝트 루트에 Dockerfile을 만듭니다. 다음 예시는 이 교재의 기준인 Node.js 24 LTS의 공식 Alpine 이미지를 쓰며, 빌드, 프로덕션 의존성, 실행 단계를 나눕니다.

먼저 같은 프로젝트에서 npm ci와 npm run build가 성공하고 실행 파일이 dist/main.js에 생기는지 확인합니다. 모노레포나 다른 출력 폴더를 쓴다면 아래 COPY와 CMD가 그 결과물을 가리켜야 합니다. Docker가 연결되지 않은 Nest 모듈이나 빠진 환경 설정을 대신 만들어 주지는 않습니다. 데이터베이스가 꼭 필요한 프로젝트는 뒤의 Compose 예제로 실행하고, 단일 컨테이너 예제는 필요한 외부 연결과 설정이 준비된 경우에 씁니다.

# syntax=docker/dockerfile:1
FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:24-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

FROM node:24-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --chown=node:node --from=deps /app/node_modules ./node_modules
COPY --chown=node:node --from=builder /app/dist ./dist
COPY --chown=node:node package*.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]

• npm ci는 package-lock.json 같은 lockfile을 기준으로 의존성을 똑같이 설치합니다.
• builder 단계에는 TypeScript와 빌드 도구가 있지만, runtime 단계에는 프로덕션 의존성과 dist만 복사합니다.
• USER node는 공식 Node 이미지에 있는 root가 아닌 사용자를 씁니다. 애플리케이션이 쓰기 폴더를 필요로 한다면 그 경로의 소유권도 명시적으로 줍니다.
• EXPOSE 3000은 이미지의 메타데이터일 뿐이며, 호스트 포트를 열려면 docker run -p나 Compose의 ports가 필요합니다.
• CMD의 exec 형식은 Node 프로세스가 종료 신호를 직접 받게 합니다.

node:24-alpine 같은 주 버전 태그는 다시 빌드할 때 가리키는 이미지가 바뀔 수 있습니다. 실제 릴리스 파이프라인에서는 검증한 @sha256:... digest로 고정하고, 보안 업데이트가 나오면 새 digest를 검증해 의도적으로 갱신합니다.

.dockerignore 작성

.dockerignore는 빌드 컨텍스트가 빌더로 전송되기 전에 필요 없는 입력을 뺍니다. 빌드 컨텍스트(build context)는 docker build 명령의 마지막 인자 .가 가리키는 폴더이며, Dockerfile의 COPY . .는 이 파일로 걸러지고 남은 것만 복사합니다. 아래 목록은 다시 만들 수 있는 결과물, 비밀이 담길 수 있는 파일, 저장소 기록을 빼는 최소한의 예입니다.

node_modules
dist
.env
.git
*.log

node_modules와 dist는 컨테이너 안에서 다시 설치하거나 만듭니다. .env를 빼 두면 실수로 복사되는 일을 줄일 수 있지만, .dockerignore가 비밀 저장소나 완전한 보안 장치는 아닙니다. 빌드 중에 비밀이 필요하다면 ARG나 ENV에 넣지 말고 BuildKit의 secret mount를 씁니다.

이미지 빌드

docker build --pull -t nestjs-app:1.0.0 .

--pull은 캐시에 같은 태그가 있어도 최신 기반 이미지를 확인합니다. 태그는 사람이 읽는 릴리스 이름일 뿐이므로, 실제 배포 후보는 테스트한 이미지의 digest까지 함께 기록해야 같은 이미지를 다시 배포하고 감사할 수 있습니다.

컨테이너 실행

docker run -d --name my-nestjs-container \
  -p 3000:3000 \
  nestjs-app:1.0.0

-p 3000:3000은 호스트의 3000번 포트를 컨테이너의 3000번 포트에 연결하고, -d는 백그라운드에서 실행합니다.

실행 시점 설정과 비밀 주입

이미지에는 환경별 설정을 넣지 않고, 실행할 때 주입합니다. 일반 설정은 다음처럼 환경 변수로 넘길 수 있습니다.

다음 명령은 앞의 docker run에 설정을 더한 대안입니다. 두 명령을 차례로 실행하면 같은 이름 my-nestjs-container로 컨테이너를 두 번 만들 수 없으므로, 아직 컨테이너를 만들지 않았다면 필요한 명령 하나만 고르고, 이미 실행했다면 기존 컨테이너를 정리할지 다른 이름으로 시험할지 먼저 정합니다. db.internal도 예시 주소이므로 실제로 연결할 수 있는 호스트가 있어야 합니다.

docker run -d --name my-nestjs-container \
  -p 3000:3000 \
  -e DATABASE_HOST=db.internal \
  -e DATABASE_PORT=5432 \
  -e NODE_ENV=production \
  nestjs-app:1.0.0

환경 변수와 평문 .env 파일은 비밀 저장소가 아닙니다. 비밀번호와 토큰은 운영 플랫폼의 secret 기능이나 전용 비밀 관리자로 최소 권한만 주어 주입하고, 애플리케이션이 그 값을 로그에 남기지 않게 합니다.

헬스 확인, 재시도, 종료, 로그

헬스 엔드포인트는 프로세스가 살아 있는지와 트래픽을 받을 준비가 되었는지를 구분해서 알려야 합니다. 데이터베이스나 Redis 연결은 실행 중에도 끊길 수 있으므로, 애플리케이션 안에서 횟수가 제한된 재시도, 지수 백오프, 타임아웃을 설계합니다.

NestJS의 종료 hook은 기본으로 켜져 있지 않습니다. SIGTERM을 받아 연결과 진행 중인 작업을 정리하려면 bootstrap에서 명시적으로 켭니다.

const app = await NestFactory.create(AppModule);
app.enableShutdownHooks();
await app.listen(process.env.PORT ?? 3000);

애플리케이션 로그는 컨테이너 안의 파일보다 stdout과 stderr로 내보내 수집기가 가져가게 하고, 요청 ID 같은 상관 필드와 구조화된 형식을 씁니다.

더 깊이: PID 1로 실행된 Node가 SIGTERM을 무시하는 경우

컨테이너에서 CMD로 시작한 프로세스는 그 컨테이너의 PID 네임스페이스에서 PID 1, 즉 init 프로세스가 됩니다. Linux의 pid_namespaces 문서에 따르면 init 프로세스에는 그 프로세스가 처리기(handler)를 등록한 신호만 전달되며, 바깥 네임스페이스에서 보낸 신호도 마찬가지입니다. 예외는 바깥에서 보낸 SIGKILL과 SIGSTOP뿐입니다. 그래서 SIGTERM 처리기가 없는 Node 프로세스가 PID 1이면 docker stop이 보낸 SIGTERM은 아무 효과가 없고, Docker는 Linux 컨테이너의 기본 유예 시간인 10초를 기다린 뒤 SIGKILL로 강제 종료합니다.

이 글의 enableShutdownHooks()는 Nest가 종료 신호의 리스너를 등록하게 하므로, 켜 두면 PID 1이어도 SIGTERM을 받아 종료 hook을 실행합니다. 공식 Node 이미지의 모범 사례 문서도 Node.js가 PID 1로 실행되도록 설계되지 않았다고 설명하며, 그 예로 PID 1인 Node 프로세스가 SIGINT(Ctrl+C)에 반응하지 않는 경우를 듭니다. 직접 처리기를 두기 어렵다면 docker run --init으로 작은 init 프로세스를 PID 1에 두는 방법도 있습니다. Docker 문서에 따르면 이 init은 tini 기반의 docker-init이며, 신호를 자식 프로세스에 전달하고 좀비 프로세스를 거두는 일을 맡습니다.

Docker Compose로 여러 컨테이너 관리하기

Docker Compose는 앱, 데이터베이스, 캐시처럼 여러 컨테이너로 이루어진 애플리케이션을 하나의 모델로 정의하고 실행합니다.

위 그림은 Compose의 기본 네트워크에 app, db, redis 서비스를 두고, 외부에는 앱의 3000번 포트만 여는 구조입니다. 앱은 서비스 이름을 DNS 이름으로 삼아 db:5432, redis:6379처럼 내부 포트로 데이터 서비스에 연결합니다. 데이터베이스와 Redis의 healthcheck는 앱을 만들기 전의 초기 확인만 제공하며, 이름 있는 볼륨은 컨테이너의 수명과 상관없이 데이터를 유지한다는 점이 함께 표시되어 있습니다.

compose.yaml 작성

프로젝트 루트에 compose.yaml을 만듭니다. 이 예시는 공식 이미지의 Node 24 LTS, PostgreSQL 18, Redis 8 주 버전 태그를 씁니다. PostgreSQL 18부터 공식 이미지의 볼륨 대상이 /var/lib/postgresql로 바뀌었으므로, 예전 /var/lib/postgresql/data 경로를 그대로 쓰지 않습니다.

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      DATABASE_HOST: db
      DATABASE_PORT: 5432
      DATABASE_USER: ${DB_USER:?set DB_USER}
      DATABASE_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
      DATABASE_NAME: ${DB_NAME:?set DB_NAME}
      REDIS_HOST: redis
      REDIS_PORT: 6379
      JWT_SECRET: ${JWT_SECRET:?set JWT_SECRET}
      NODE_ENV: production
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: ${DB_USER:?set DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME:?set DB_NAME}
    volumes:
      - db_data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:8-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  db_data:
  redis_data:

• Compose의 기본 네트워크에서 app은 db:5432, redis:6379처럼 서비스 이름과 컨테이너 포트로 연결합니다. IP 주소는 다시 만들 때 바뀔 수 있으므로 고정 IP에 기대지 않습니다.
• db와 redis에는 호스트 ports를 열지 않았습니다. 호스트의 도구가 직접 접근해야 하는 개발 상황에서만 명시적으로 엽니다.
• condition: service_healthy는 앱 컨테이너를 처음 만들기 전의 준비 확인입니다. 실행 중에 의존 서비스가 계속 살아 있음을 보장하거나 연결을 자동으로 복구하지 않으므로, 앱의 재연결과 재시도 정책이 따로 필요합니다.
• 이름 있는 볼륨은 컨테이너와 상관없이 데이터를 유지하지만 백업과 복구를 대신하지 않습니다. docker compose down -v처럼 볼륨을 명시적으로 지우면 데이터도 사라집니다.
• ${VAR} 치환은 값을 넘기는 방법일 뿐 비밀 저장소가 아닙니다. 위 예시는 로컬 학습용이며, 운영에서는 Compose secrets나 배포 플랫폼의 secret 기능을 씁니다.

Docker Compose 실행

필수 변수를 안전한 실행 환경에서 넣은 뒤, 현재의 docker compose CLI로 실행합니다. 앞 파일의 ${DB_USER:?set DB_USER}는 셸 환경이나 프로젝트 폴더의 .env에 DB_USER가 없거나 비어 있으면 set DB_USER라는 오류 메시지를 내고 명령을 멈추게 합니다. 그래서 변수를 넣지 않고 실행하면 컨테이너가 만들어지기 전에 실패합니다. 아래 명령은 설정 확인, 빌드와 시작, 상태 확인, 로그 따라가기, 정리의 순서입니다.

docker compose config
docker compose up --build -d
docker compose ps
docker compose logs -f app
docker compose down

docker compose config로 변수 치환과 최종 모델을 먼저 확인하고, ps와 로그로 상태를 지켜봅니다. 비밀 값이 들어 있는 출력이나 로그를 공유하지 않도록 주의합니다.

브라우저에서 http://localhost:3000으로 보낸 요청은 호스트의 3000번 포트를 거쳐 app의 3000번 포트로 들어갑니다. 그 앱이 PostgreSQL에 연결할 때는 db:5432를 씁니다. 앱 컨테이너 안의 localhost는 앱 자신이므로 이 Compose의 데이터베이스가 아닙니다. db와 redis가 healthy가 된 뒤 앱이 시작하더라도, 필수 변수가 비었거나 Nest 초기화가 실패하면 앱 로그를 따로 확인해야 합니다.

docker compose logs -f app은 로그를 계속 따라가는 명령이므로, 다 본 뒤에는 따라가기를 끝내고 다음 명령을 실행합니다. 일반 docker compose down과, 이름 있는 볼륨까지 지우는 명령은 구분해서 씁니다.

Docker 기반 컨테이너화의 핵심은 이미지를 만드는 데서 끝나지 않습니다. 빌드 입력을 제한하고, 빌드 도구를 실행 이미지에서 빼며, 승인된 이미지 digest를 배포하고, 설정·비밀·헬스·재시도·종료·로그를 이미지 바깥에서 분명하게 관리해야 반복할 수 있는 운영 단위가 됩니다.

정리

• 컨테이너는 호스트 커널을 함께 쓰며 프로세스와 자원을 격리하는 실행 단위이고, Docker는 그 이미지를 빌드·배포·실행하는 도구입니다.
• 다단계 Dockerfile로 빌드 도구는 builder 단계에만 두고, 실행 이미지에는 프로덕션 의존성과 dist만 복사하며 USER node로 실행합니다.
• 이미지 태그는 바뀔 수 있으므로, 배포할 때는 검증한 digest를 기록하고 고정합니다.
• 설정과 비밀은 이미지에 넣지 않고 실행 시점에 주입하며, 빌드 중 비밀이 필요하면 BuildKit secret mount를 씁니다.
• Compose의 서비스는 이름으로 서로 연결하고, depends_on의 healthcheck 조건은 시작 전 확인일 뿐 실행 중 재연결을 대신하지 않습니다.

연습 문제

1. 게시 포트만 바꾸면

별도의 시험 환경에서 호스트 게시 포트만 8080:3000으로 바꾸고 데이터 서비스 설정은 그대로 두었습니다. 브라우저의 접속 주소와 앱이 쓰는 데이터베이스 주소는 각각 무엇일까요? 앱이 시작된 뒤 데이터베이스 연결이 끊기면 depends_on이 연결을 복구해 줄까요?

2. 정리하다 지운 데이터

개발 중인 동료가 Compose 환경을 깨끗이 다시 시작하려고 docker compose down -v를 실행한 뒤 docker compose up -d로 다시 띄웠습니다. 데이터베이스에 넣어 둔 테스트 데이터는 어떻게 되었을까요? -v 없이 down만 실행했다면 어땠을까요?

3. 빌드할 때 필요한 토큰

사설 npm 레지스트리의 패키지를 설치하려고 Dockerfile에 ARG NPM_TOKEN을 두고 RUN echo "//registry.example.com/:_authToken=${NPM_TOKEN}" > .npmrc && npm ci로 설치했습니다. 최종 이미지는 다단계 빌드의 runtime 단계라 .npmrc가 복사되지 않았습니다. 이 토큰은 안전할까요?

다음 글 CI/CD 파이프라인 구축에서는 이 이미지를 자동으로 빌드하고 검증해 배포하는 파이프라인을 만듭니다.