[NestJS] PM2 소개부터 Docker + Github Action을 활용한 배포까지

📒 [NestJS] PM2 소개부터 Docker + Github Action을 활용한 배포까지

---

일반적으로 NestJS 혹은 NextJS는 Node.js의 런타임 위에서 동작하기 때문에 싱글 스레드 기반으로 작동합니다.

이러한 구조는 많은 요청이 들어올 경우 병목현상이 발생해 이벤트 루프가 차단되어 응답성이 저하됩니다.

이럴 때 여러 프로세스를 생성하여 멀티 코어를 활용하기 위해 주로 사용하는 프로세스 매니저가 있는데요, 바로 PM2입니다.

 

📌 PM2란

PM2는 Node.js 애플리케이션을 관리하기 위한 프로덕션 프로세스 매니저입니다.

애플리케이션의 실행, 모니터링, 로드 밸런싱, 무중단 배포 등을 지원하여, Node.js 애플리케이션을 안정적으로 운영할 수 있게 도와줍니다.

특히, 서버에서 Node.js 애플리케이션을 실행하고 관리할 때 필요한 여러 기능을 통합적으로 제공하여 개발자와 운영자의 편의성을 높입니다.

 

🔎 장점

주요한 특장점은 다음과 같습니다.

• 프로세스 관리
  • 애플리케이션을 시작, 중지, 재시작, 삭제 등의 작업을 명령어로 간단히 수행할 수 있습니다.
  • 프로세스 크래시 시 자동 재시작을 지원하여 서비스 안정성을 보장합니다.
• 클러스터 모드 지원
  • 멀티 코어 서버에서 클러스터 모드로 실행하면 CPU를 효율적으로 활용하여 성능을 최적화할 수 있습니다.
  • 단일 프로세스의 한계를 넘어서 더 많은 요청을 처리할 수 있습니다.
• 무중단 배포 (Zero Downtime Reload)
  • 애플리케이션을 재시작하지 않고도 새 코드를 적용할 수 있습니다.
  • pm2 reload 명령으로 서비스 중단 없이 업데이트가 가능합니다.
• 로그 관리 및 모니터링
  • 애플리케이션의 실행 로그(표준 출력 및 에러)를 자동으로 저장하고 관리합니다.
  • 실시간으로 로그를 확인하거나(pm2 logs), 로그 파일을 조회할 수 있습니다.
  • 애플리케이션 상태를 모니터링하는 CLI 또는 웹 대시보드를 제공합니다.
• 환경 변수 관리
  • JSON 또는 ecosystem.config.js 파일로 환경 변수를 정의하고 관리할 수 있습니다.
  • 다양한 실행 환경(dev, staging, production)을 쉽게 설정할 수 있습니다.
• 애플리케이션 상태 모니터링
  • pm2 monit 명령으로 CPU, 메모리 사용량, 실행 상태 등을 확인할 수 있습니다.
  • PM2 Plus와 같은 추가 서비스를 통해 더 상세한 모니터링과 알림 기능을 사용할 수 있습니다.
• 배포 자동화
  • pm2 deploy 명령을 사용해 애플리케이션을 원격 서버에 쉽게 배포할 수 있습니다.
  • Git 리포지토리와 연동하여 자동으로 코드를 가져와 배포하는 워크플로를 구축할 수 있습니다.

node 생태계에 너무나 필요한 기능들을 꽉꽉 채워 넣은 것을 확인할 수 있습니다.

 

🔎 주요 명령어

pm2를 사용하기 위해선 사전에 설치가 필요합니다.

$ npm i -g pm2

 

• 앱 실행

$ pm2 start app.js --name my-app

 

• 환경 파일을 사용한 앱 실행

$ pm2 start ecosystem.config.js

• 앱 중지

$ pm2 stop my-app
$ pm2 delete my-app

 

• pm2 종료

$ pm2 kill

• 실시간 모니터링

$ pm2 monit

• 실시간 로그 확인

$ pm2 logs

 

📌 환경 파일 (ecosystem.config.js)

PM2 환경 파일은 일반적으로 ecosystem.config.js 또는 ecosystem.json 이름으로 작성하며 프로젝트 루트에 위치합니다.

기본적인 속성은 다음과 같습니다.

 

module.exports = {
  apps: [
    {
      // 애플리케이션 이름 (PM2에서 사용할 이름)
      // PM2 명령어에서 이 이름을 사용하여 애플리케이션을 제어합니다.
      name: "my-app",

      // 실행할 스크립트 파일 경로
      // Node.js 파일뿐만 아니라, Bash, Python 등 다른 스크립트도 실행 가능합니다.
      script: "./dist/main.js",

      // 현재 작업 디렉토리 (기본값: 현재 디렉토리)
      // 애플리케이션 실행 기준이 되는 경로를 지정합니다.
      cwd: "/home/user/my-app",

      // 실행 모드: "fork" 또는 "cluster"
      // fork: 단일 프로세스 실행
      // cluster: 멀티 코어를 활용하여 여러 프로세스 실행
      exec_mode: "cluster",

      // 실행할 인스턴스 수
      // cluster 모드에서만 유효하며, "max"로 설정하면 모든 CPU 코어를 사용합니다.
      instances: "max",

      // 애플리케이션에 전달할 인수
      // 실행 시 커맨드라인 인수로 전달됩니다.
      args: ["--port", "3000"],

      // 기본 환경 변수 설정
      // NODE_ENV, PORT 등 실행 환경을 정의합니다.
      env: {
        NODE_ENV: "development", // 개발 환경
        PORT: 3000              // 기본 포트
      },

      // 프로덕션 환경에서 사용할 환경 변수 설정
      // "pm2 start ecosystem.config.js --env production"으로 실행 시 적용됩니다.
      env_production: {
        NODE_ENV: "production", // 프로덕션 환경
        PORT: 8000              // 프로덕션 포트
      },

      // 로그 파일 경로 설정 (표준 출력과 에러 로그 통합)
      log_file: "/var/logs/my-app-combined.log",

      // 표준 출력 로그 파일 경로
      out_file: "/var/logs/my-app-out.log",

      // 에러 로그 파일 경로
      error_file: "/var/logs/my-app-error.log",

      // 파일 변경 감지 (기본값: false)
      // true로 설정하면 파일 변경 시 애플리케이션을 자동으로 재시작합니다.
      watch: true,

      // 감시에서 제외할 파일/폴더 (watch가 true일 때 유효)
      ignore_watch: ["node_modules", "logs"],

      // 자동 재시작 여부 (기본값: true)
      // false로 설정하면 애플리케이션이 종료된 상태로 유지됩니다.
      autorestart: true,

      // 재시작 시도 횟수 (기본값: 무제한)
      // 특정 횟수 이상 실패하면 프로세스를 종료합니다.
      max_restarts: 10,

      // 최대 메모리 사용량 (기본값: 제한 없음)
      // 프로세스가 이 메모리 제한을 초과하면 재시작합니다.
      max_memory_restart: "300M",

      // 개발 중 디버깅을 위한 상세 로그 활성화 (기본값: false)
      // true로 설정하면 애플리케이션 디버그 로그를 더 많이 출력합니다.
      debug: false,

      // 실행 중인 프로세스의 CPU/메모리 사용량을 확인할 주기 (기본값: 10초)
      // PM2 Dashboard와 같은 모니터링 도구에서 사용됩니다.
      min_uptime: "1m",   // 최소 실행 시간 (프로세스가 이 시간 이전에 종료되면 비정상으로 간주)
      max_uptime: "24h",  // 최대 실행 시간 (이 시간이 지나면 프로세스를 재시작)

      // 사용자 정의 스크립트를 애플리케이션 실행 후 실행
      post_start_script: "./scripts/postStart.sh"
    }
  ]
};

 

📌 Github Action + Docker + PM2로  NestJS배포하기

아무래도 요즘은 배포할 때 도커를 사용하는 게 선택이 아닌 필수가 되어버렸습니다.

이번 프로젝트를 배포할 때 pm2와 도커를 사용한 것을 예시로 들어 소개드립니다.

 

🔎 ecosystem.config.js

module.exports = {
  apps: [
    {
      name: 'franchise-backend',
      script: './dist/main.js',
      exec_mode: 'cluster',
      instances: '2', // CPU 코어 수
      max_memory_restart: '1000M', // 프로세스의 메모리가 1000MB에 도달하면 reload 실행
      merge_logs: true, // 클러스터 모드 사용 시 각 클러스터에서 생성되는 로그를 한 파일로 합침
      autorestart: true, // 프로세스 실패 시 자동으로 재시작할지 선택
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000,
        DATABASE_URL: 'VAL_DATABASE_URL',
        OPENAPI_KEY: 'VAL_OPENAPI_KEY',
        DEFAULT_YEAR: 'VAL_DEFAULT_YEAR',
      },
    },
  ],
};

먼저 백앤드 앱을 어떻게 실행할지 pm2 설정파일을 작성합니다.

필요한 환경 변수가 있다면 env_production 블럭 안에 추가적으로 작성해 줍니다.

저는 처리량이 크게 많을 것 같지 않아 우선 코어를 2개 정도만 사용하도록 했습니다.

 

🔎 Dockerfile

FROM node:22-alpine AS base

FROM base AS builder
  RUN apk add --no-cache libc6-compat
  WORKDIR /app
  COPY package.json pnpm-lock.yaml ./
  RUN corepack enable pnpm 
  RUN pnpm i --frozen-lockfile
  COPY . .
  ARG VAL_DATABASE_URL
  ARG VAL_OPENAPI_KEY
  ARG VAL_DEFAULT_YEAR
  RUN sed -i "s|VAL_DATABASE_URL|$VAL_DATABASE_URL|" ecosystem.config.js
  RUN sed -i "s|VAL_OPENAPI_KEY|$VAL_OPENAPI_KEY|" ecosystem.config.js
  RUN sed -i "s|VAL_DEFAULT_YEAR|$VAL_DEFAULT_YEAR|" ecosystem.config.js
  RUN pnpm build

FROM base AS runner
  WORKDIR /app
  RUN npm install -g pm2
  COPY --from=builder /app .
  RUN npm run prisma:generate
  EXPOSE 3000
  CMD ["pm2-runtime", "start", "ecosystem.config.js", "--env", "production"]

pnpm 패키지 매니저를 이용한 빌드 방법입니다.

• sed 명령어로 배포 스크립트에서 주입받은 환경변수를 ecosystem에 치환해 주었습니다.
• 실행 부분에서 pm2를 설치해 주었습니다.
• pm2 start가 아닌 컨테이너 환경에 최적화되어
  데몬 없이 프로세스를 실행하는 pm2-runtime start명령어를 이용해 실행합니다.

 

🔎 Github Action Workflow

name: deploy

on:
  push:
    branches: [main]

jobs:
  app-build:
    runs-on: ubuntu-latest
    env:
      DOCKER_IMAGE_TAG: ${{ secrets.DOCKER_REPOSITORY }}/${{secrets.DOCKER_IMAGENAME}}:latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login docker hub
        uses: docker/login-action@v3
        with:
          registry: ${{ secrets.DOCKER_REPOSITORY }}
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ env.DOCKER_IMAGE_TAG }}
          build-args: |
            VAL_DATABASE_URL=${{secrets.VAL_DATABASE_URL}}
            VAL_OPENAPI_KEY=${{secrets.VAL_OPENAPI_KEY}}
            VAL_DEFAULT_YEAR=${{secrets.VAL_DEFAULT_YEAR}}

      - name: execute remote ssh
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USERNAME }}
          port: ${{ secrets.SERVER_PORT }}
          key: ${{ secrets.SERVER_KEY }}
          script: |
            docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}
            docker pull ${{ env.DOCKER_IMAGE_TAG }}
            docker stop ${{secrets.DOCKER_IMAGENAME}} || true
            docker rm ${{secrets.DOCKER_IMAGENAME}} || true
            docker run -d --restart=always --name ${{secrets.DOCKER_IMAGENAME}} -p 3001:3000 ${{ env.DOCKER_IMAGE_TAG }}

이미지를 빌드 및 docker private repository에 push 하고, ssh 명령어로 배포 서버에서 이미지를 받은 후 컨테이너를 실행시키는 과정을 포함하고 있습니다.

필요한 환경변수들은 docker/build-push-action에서 build-args를 통해 도커 파일로 전달해 주면 됩니다.

 

🔎 결과

컨테이너에 exec 명령어로 접속 후 pm2 monit을 통해 모니터링해보니 여러 요청을 정상적으로 각 프로세스에 분배해서 처리하는 것을 확인할 수 있었습니다.