자동 기동 기준 (PM2 startup + systemd)¶

운영 서버(Production Server) 에서
Node.js 를
서버 부팅 시 자동으로 기동하기 위한 systemd 연동 기준을 정의함.

PM2 운영에서 가장 사고가 많이 발생하는 구간이므로, 반드시 본 문서의 계정·순서·명령을 그대로 준수해야 함.

⚠️ 모든 PM2 startup 관련 작업은 운영 사용자 계정의 홈 디렉터리(/home/[User])에서 수행하는 것을 원칙으로 함

1. 기본 전제 조건¶

PM2는 root 권한으로 전역 설치되어 있음
Node.js 애플리케이션은 운영 사용자 계정으로 실행 중
ecosystem.config.cjs 기반으로 서비스가 정상 실행 중
모든 명령은 운영 사용자 계정에서 실행함
(root ❌, sudo ❌ — 단, systemd 설정 출력에 포함된 sudo env ... 명령은 예외)

cd /home/[User]

2. PM2 프로세스 상태 저장 (필수 선행)¶

PM2 startup 설정 전에 반드시 현재 프로세스 상태를 저장해야 함.

pm2 save --force

왜 필요한가¶

systemd는 이 시점에 저장된 PM2 프로세스 목록만 복구함
이 단계를 건너뛰면
- 서버 부팅 후 아무 서비스도 기동되지 않거나
- 이전/잘못된 서비스가 복구됨

⚠️ pm2 startup 이전에 pm2 save는 필수

3. systemd Boot Script 등록 (startup)¶

운영 사용자 기준으로 PM2를 systemd에 등록함. pm2 startup 설정은 서버 최초 1회 수행이 원칙이며, 이후에는 pm2 save만 수행함 (단, unstartup 수행 후에는 예외적으로 재수행함)

pm2 startup systemd -u [User] --hp /home/[User]

명령 실행 후 아래와 같은 출력이 반드시 나타나야 함.

[PM2] Init System found: systemd
[PM2] To setup the Startup Script, copy/paste the following command:

sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u [User] --hp /home/[User]

4. 출력된 sudo env 명령 실행 (중요)¶

위 단계에서 출력된 sudo env ... 명령을 그대로 복사하여 실행함.

sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u [User] --hp /home/[User]

⚠️ 중요 주의사항

명령을 절대 수정하지 말 것
PATH에는 반드시 node, npm, pm2가 포함되어야 함
NodeSource 기반 환경에서는 /usr/bin 포함으로 충분함

이 단계는 root 권한이 필요하지만,
명령은 PM2가 생성한 그대로 실행해야 함

5. PM2 상태 재저장¶

startup 등록 후 현재 PM2 앱 목록이 정상인지 확인한 뒤 다시 저장함.

pm2 list
pm2 save --force

startup 과 save 는 항상 한 세트임.
단, PM2 앱 목록이 비어 있거나 예상 앱이 누락된 상태에서는 절대 저장하지 않음.

6. systemd 서비스 등록 확인 (반드시 확인)¶

pm2 startup systemd 실행 후 출력된 sudo env ... 명령을 그대로 실행했을 때, 아래와 같은 안내가 반드시 포함되어야 함.

⚠️ 이 확인 단계를 건너뛰면 “설정은 했는데 재부팅 후 서비스가 안 뜨는” 사고가 발생할 수 있음

6.1 startup 출력에서 확인해야 할 항목¶

출력 예시:

[PM2] Target path
/etc/systemd/system/pm2-[User].service

이 경로는 PM2가 systemd에 등록된 실제 서비스 파일 위치임.

이 경로가 출력되지 않으면 systemd 등록이 정상적으로 이루어지지 않은 상태임.

6.2 systemd 서비스 상태 확인¶

위 출력에 표시된 사용자 기준으로 다음 명령을 실행하여 실제 서비스 상태를 확인함.

sudo systemctl status pm2-[User].service

정상 상태 기준¶

Loaded: loaded
Active: active (running)

상태가 위와 같다면 부팅 시 자동 기동 설정 완료임.

6.3 문제가 발생하는 흔한 원인¶

pm2 save --force 누락
root 계정으로 pm2 startup 실행
--hp /home/[User] 옵션 누락
출력된 sudo env 명령을 수정하여 실행

systemd 등록 문제의 90%는 계정 또는 순서 오류

6.4 systemd unit 보정 기준¶

PM2 startup 명령이 생성한 systemd unit은 서버 환경, PM2 버전, 실행 당시 PATH에 따라 일부 항목이 다르게 생성될 수 있음.

따라서 startup 등록 후 반드시 다음 파일을 확인함.

sudo systemctl cat pm2-[User].service --no-pager

정상 기준은 다음과 같음.

User=[User]
Environment=PM2_HOME=/home/[User]/.pm2
ExecStart=/usr/lib/node_modules/pm2/bin/pm2 resurrect

다음 항목이 포함되어 있으면 보정 대상임.

PIDFile=/home/[User]/.pm2/pm2.pid

일부 RHEL 계열 환경에서는 systemd가 사용자 홈 디렉터리의 PM2 pid 파일을 검증하지 못해 다음 오류가 발생할 수 있음.

Can't open PID file /home/[User]/.pm2/pm2.pid (yet?) after start: Operation not permitted
Can't convert PID files /home/[User]/.pm2/pm2.pid O_PATH file descriptor to proper file descriptor: Permission denied
Failed with result 'protocol'

이 경우 PM2와 애플리케이션은 정상 기동되었더라도 systemd service 상태가 실패로 판정될 수 있음.

따라서 PIDFile= 항목은 제거함.

sudo sed -i '/^PIDFile=/d' /etc/systemd/system/pm2-[User].service

또한 sudo env PATH=$PATH:/usr/bin ... 실행 당시 root 또는 불필요한 PATH가 systemd unit에 포함될 수 있음.

예시:

Environment=PATH=/home/[User]/.local/bin:/home/[User]/bin:/root/.local/bin:/root/bin:...

운영 기준상 PATH는 필요한 실행 경로만 남기도록 정리함.

sudo sed -i \
  's|^Environment=PATH=.*|Environment=PATH=/home/[User]/.local/bin:/home/[User]/bin:/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/bin|' \
  /etc/systemd/system/pm2-[User].service

수정 후 systemd 설정을 다시 로드함.

sudo systemctl daemon-reload
pm2 list
# 현재 PM2 앱 목록이 정상인지 List 확인 후 Save.
pm2 save --force

startup 등록 후에는 반드시 generated unit을 확인함.
PIDFile= 항목이 있거나 Environment=PATH에 /root 계열 경로가 포함된 경우, 운영 기준에 맞게 보정한 뒤 systemctl daemon-reload를 수행함.

7. Boot Script 등록 해제 (unstartup)¶

PM2 startup 설정을 제거해야 하는 경우 다음 절차를 따름.

⚠️ 이 명령은 운영 사용자 계정에서 실행

7.1 등록 해제 명령 확인¶

pm2 startup 실행 시 출력에 다음 안내가 포함됨.

[PM2] Remove init script via:
$ pm2 unstartup systemd

7.2 등록 해제 실행¶

pm2 unstartup systemd

8. startup 해제 후 재등록 시 주의 사항 (중요)¶

startup을 해제한 뒤 다시 등록하려는 경우, 반드시 아래 순서를 지켜야 함.

pm2 save --force
pm2 startup systemd -u [User] --hp /home/[User]

이유¶

이전 PM2 상태 정보가 남아 있으면
- 잘못된 프로세스가 복구되거나
- systemd 등록이 꼬일 수 있음

startup 재등록 전 pm2 save는 초기화 개념

9. 운영 기준 요약¶

PM2 startup 설정은 운영 사용자 기준
작업 위치는 /home/[User]
절차 요약:

1. pm2 list 로 현재 앱 상태 확인
2. pm2 save --force
3. pm2 startup systemd -u [User] --hp /home/[User]
4. 출력된 sudo env ... 명령 실행
5. sudo systemctl cat pm2-[User].service --no-pager 로 generated unit 확인
6. 필요한 경우 PIDFile 제거 및 PATH 보정
7. sudo systemctl daemon-reload
8. pm2 list 로 앱 상태 재확인
9. 앱 목록이 정상일 때만 pm2 save --force 실행
10. sudo systemctl start pm2-[User].service
11. sudo systemctl status pm2-[User].service -n 100 --no-pager -l 확인

10. 절대 금지 사항¶

root 계정으로 pm2 startup 실행 ❌
pm2 save 없이 startup 수행 ❌
sudo로 pm2 명령 직접 실행 ❌
ecosystem 없이 startup 설정 ❌
PM2 앱 목록이 비어 있는 상태에서 pm2 save --force 실행 ❌

이 중 하나라도 어기면 재부팅 후 서비스 미기동 사고 확정

11. 정리¶

PM2 startup은 운영 자동화의 핵심
설정 자체보다 계정과 순서가 더 중요
이 문서를 그대로 따르면
- 재부팅 후 자동 기동
- 예측 가능한 운영 상태 유지 가능

PM2 startup은 한 번만 제대로 설정하면, 이후 운영 사고를 절반 이상 줄여준다.