PM2

PM2는 Node.js application을 background에서 실행하고 상태, restart, log와 cluster worker를 관리하는 daemon 기반 process manager다. Linux의 systemd 자체를 대체하기보다, application process는 PM2가 관리하고 PM2 daemon의 boot lifecycle은 systemd 같은 init system에 연결하는 계층으로 이해하는 편이 정확하다.

Node.js와 npm을 먼저 설치한 뒤 application을 운영할 일반 사용자 계정에서 PM2를 전역 설치한다.

npm install pm2@latest --global
pm2 --version

공식 PM2 문서는 npm 또는 Yarn 전역 설치를 안내한다. Debian / Ubuntu와 RHEL / Fedora에서도 배포판별 PM2 APT·DNF repository 대신 위 npm 설치 방식을 사용한다. macOS와 Windows도 Node.js/npm을 준비한 뒤 같은 명령을 사용하며, 공식 문서가 별도의 Homebrew formula 또는 winget PM2 package를 기본 설치 경로로 안내하지는 않는다.

• application을 daemonize하고 비정상 종료 시 자동 restart한다.
• process list, CPU·memory 상태와 stdout/stderr log를 한 CLI에서 확인한다.
• Node.js network application을 여러 worker로 실행하는 cluster mode를 제공한다.
• 저장된 process list를 init system과 연결해 재부팅 후 복원할 수 있다.
• 여러 application과 환경별 값을 ecosystem.config.js로 선언할 수 있다.

pm2 start app.js --name my-api
pm2 status
pm2 logs my-api
pm2 restart my-api

• pm2 start SCRIPT [–name NAME]: application을 등록하고 시작한다.
• pm2 status: 관리 중인 process 상태를 표시한다. list와 ls도 사용할 수 있다.
• pm2 show APP: 특정 application의 상세 정보와 restart 통계를 표시한다.
• pm2 logs [APP] [–lines N]: 실시간 또는 최근 log를 표시한다.
• pm2 monit: terminal dashboard를 연다.
• pm2 stop|restart|reload|delete APP|all: process 상태를 변경한다.

pm2 start app.js --name my-api
pm2 show my-api
pm2 restart my-api
pm2 stop my-api
pm2 delete my-api

stop은 process를 중지하지만 PM2 목록에는 남긴다. delete는 process를 중지하고 목록에서도 제거하므로, boot 복원 목록을 확정하기 전에 의도한 application만 남았는지 pm2 status로 확인한다.

환경 변수를 바꾼 뒤 기존 process에 반영할 때는 명시적으로 갱신한다.

NODE_ENV=production pm2 restart my-api --update-env

pm2 status
pm2 show my-api
pm2 logs my-api --lines 200
pm2 monit

PM2 기본 log는 application 실행 사용자의 ~/.pm2/logs/ 아래에 쌓인다. 장기 운영에서는 filesystem 용량, 보존 기간과 log rotation을 별도로 설계하고, secret이나 credential이 stdout/stderr에 출력되지 않도록 application logging도 함께 점검한다.

Node.js network application을 CPU 수에 맞춰 여러 worker로 실행할 수 있다.

pm2 start app.js --name my-api --instances max
pm2 scale my-api 4
pm2 reload my-api

reload는 지원되는 network application에서 worker를 순차 교체해 중단 시간을 줄인다. in-memory session, scheduled job, singleton worker나 local filesystem state가 있다면 단순히 worker 수를 늘리기 전에 외부 state 저장소와 중복 실행 방지 구조를 마련한다.

Linux에서는 PM2가 감지한 init system용 startup 설정을 생성하고 현재 process list를 저장한다.

pm2 startup
# 출력된 sudo 명령을 검토한 뒤 그대로 실행
pm2 save
 
systemctl status pm2-USER
journalctl -u pm2-USER -b

pm2 startup 자체를 무조건 root로 다시 실행하지 말고, PM2가 출력한 사용자·home·PATH가 포함된 명령을 검토한다. pm2 save는 그 시점의 process list를 dump에 저장하며, 이후 application 구성을 바꾸면 다시 실행해야 다음 boot에 반영된다.

pm2 resurrect
pm2 unstartup

• resurrect: 마지막으로 저장한 process list를 수동 복원한다.
• unstartup: 현재 platform의 startup 설정 제거 명령을 안내하거나 실행한다.
• nvm 등으로 Node.js version을 바꾸면 startup unit의 PATH가 이전 Node 경로를 가리킬 수 있다. 공식 절차대로 pm2 unstartup 후 pm2 startup을 다시 수행하고 pm2 save 상태를 확인한다.
• macOS에서는 launchd를 감지할 수 있다. 공식 startup generator는 Windows를 직접 지원 목록에 넣지 않고 별도 installer를 안내하므로, 검증되지 않은 third-party service wrapper를 production에 도입하기 전에 유지보수 상태와 권한 모델을 확인한다.

여러 process, working directory, cluster 수, restart policy와 환경별 값을 관리할 때는 ecosystem.config.js 작성 가이드를 사용한다.

pm2 init simple
pm2 start ecosystem.config.js --env production
pm2 save

package와 memory에서 실행 중인 PM2 daemon을 순서대로 갱신한다.

npm install pm2@latest --global
pm2 update
pm2 --version

Node.js 자체를 upgrade했다면 Boot Startup 절의 startup 설정 재생성도 함께 수행한다.

• pm2 status 결과가 사용자마다 다르면 같은 application 계정인지, PM2_HOME이 달라지지 않았는지 확인한다.
• 재부팅 후 application이 뜨지 않으면 systemctl status pm2-USER, journalctl -u pm2-USER -b, startup unit의 Node.js PATH, 마지막 pm2 save 시점을 확인한다.
• 반복 restart 상태이면 pm2 show APP와 pm2 logs APP에서 exit code, signal, working directory, environment와 memory limit을 확인한다.
• port가 이미 사용 중이면 PM2와 직접 작성한 systemd unit, container 또는 다른 사용자 PM2 daemon이 같은 application을 중복 실행하는지 확인한다.
• watch는 production에서 대량 file 변경과 deploy 중 연속 restart를 일으킬 수 있으므로 ignore pattern과 운영 필요성을 검토한다.

• PM2는 Node.js application에 최적화되어 있지만 shell script, Python script와 binary도 실행할 수 있다.
• cluster mode의 automatic load balancing은 Node.js network application을 대상으로 한다.
• init system 지원과 생성되는 service 내용은 platform, PM2와 Node.js 설치 경로에 따라 달라진다.
• 이 환경에는 PM2가 설치되어 있지 않아 실제 pm2 –help 출력은 수집하지 않았다. 명령은 2026-07-23 기준 공식 PM2 문서를 확인했다.

pm2 --help

PM2가 설치된 환경에서 pm2 --help로 현재 버전의 도움말을 확인한다.

• PM2 ecosystem.config.js
• Node.js
• npm
• nvm
• systemctl
• PM2 Quick Start
• PM2 Startup Script

• codex:: 2026-07-23 PM2 process lifecycle, systemd 역할 구분, 공식 설치, boot 복원과 운영 troubleshooting을 추가했다.