Node.js 설치¶

운영 서버(Production Server) 에서 Node.js 런타임을 안정적으로 설치하기 위한 표준 절차를 정의함. 개발 환경(nvm, 로컬 실행 등)은 다루지 않음.

1. 설치 방식 선정 기준¶

운영 서버에서는 다음 조건을 만족해야 함.

systemd / PM2와 완전 호환
사용자 쉘 환경에 의존하지 않음
전역 경로가 명확함
서버 재부팅 후에도 동일하게 동작함

따라서 운영 서버에서는:

NodeSource 기반 전역 Node.js 설치만 사용함

2. nvm을 사용하지 않는 이유 (운영 기준)¶

운영 서버에서 nvm을 사용하지 않음.

이유¶

nvm은 사용자 쉘 전용 도구임
systemd 서비스에서 nvm 환경이 로드되지 않음
root 계정에 설치 후 일반 사용자에게 공유하는 구조는
- 권한 충돌
- PM2 실행 실패
- 보안 문제를 유발함
root 계정에 nvm을 설치하고 일반 사용자에게 /root/.nvm/... 경로를 물려주는 방식은 권한 충돌, PM2/systemd 서비스 연동 실패, 보안 문제를 유발.
전역 Node.js(/usr/bin/node) 가 가장 안정적이다.

운영 서버에서는 Node.js 실행 경로가 /usr/bin/node 로 고정되어야 함

3. NodeSource 저장소 등록¶

NodeSource는 최신 LTS/Current Node.js를 RHEL 계열(Rocky, Alma, CentOS Stream)에 안정적으로 제공함.

3.1 설치 스크립트 실행¶

sudo dnf install -y curl ca-certificates

curl -fsSL https://rpm.nodesource.com/setup_current.x | sudo bash -

# 2026-06-10 기준
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -

LTS 고정이 필요한 경우 setup_18.x, setup_20.x, setup_22.x 등으로 변경 가능함.

4. Node.js 설치¶

sudo dnf install -y nodejs

설치 시 다음 패키지가 함께 설치됨.

node
npm

5. 설치 확인 (반드시 확인)¶

5.1 버전 확인¶

node -v
npm -v

5.2 실행 경로 확인¶

which node
which npm

정상 출력 예:

/usr/bin/node
/usr/bin/npm

이 경로가 아닐 경우 운영 기준에 맞지 않음

6. Node.js 실행 경로 확인 원칙¶

운영 서버에서 Node.js는 다음 조건을 만족해야 함.

/usr/bin/node 사용
사용자 홈 디렉터리 의존 없음
PM2 / systemd에서 동일 경로 사용

이 조건이 깨지면:

PM2 실행 실패
서비스 재시작 불가
서버 재부팅 후 장애 발생

7. 개발 경로와 운영 경로 분리¶

운영 서버에서는 개발 경로와 실행 경로를 분리함.

기본 구조¶

/home/[User]/[ProjectName] → 서버에서 직접 빌드가 필요할 때 사용하는 작업 경로
                         → 원격으로 접속해서 개발/수정하는 작업 경로
                         → 위 두 목적을 함께 사용하는 경로
/var/www/[ProjectName]/current → 운영 실행 경로

이유¶

운영 중인 파일을 실수로 수정하는 사고 방지
실행 경로와 배포 대상 경로를 명확히 고정
권한 및 SELinux 충돌 예방

운영 경로에서 직접 개발하지 않는 이유

/var/www 경로는 운영 실행 전용 영역임.

운영 경로에서 직접 개발할 경우 다음 문제가 발생함.

운영 중인 파일을 실수로 수정할 위험
권한 및 SELinux 충돌 발생
빌드 산출물과 실행 파일 혼재
장애 발생 시 롤백 어려움

따라서 다음 원칙을 반드시 유지함.

개발 / 검증: /home/[User]/[ProjectName]
운영 실행: /var/www

/home/[User]/[ProjectName] 경로는 다음 상황에서 사용하는 작업 경로임.

서버에서 직접 build가 필요한 경우
원격으로 접속해서 코드 수정/검증을 해야 하는 경우
위 두 가지를 함께 수행하는 경우

7-1. 운영 실행 경로 준비 (/var/www)¶

Node.js 애플리케이션은 반드시 /var/www/[ProjectName]/current 기준으로 실행됨.

디렉터리 생성¶

sudo mkdir -p /var/www/[ProjectName]
sudo chown -R [User]:[Group] /var/www/[ProjectName]
sudo chmod -R 0755 /var/www/[ProjectName]

이 단계에서는 실행 경로만 준비함.
애플리케이션 배포 및 실행은 이후 문서에서 다룸.

운영 배포 전에는 반드시 /home/[User]/[ProjectName] 또는 동등한 작업 경로에서 테스트 및 빌드 완료 후 배포함.

8. npm-check-updates (ncu) 사용 기준¶

npm-check-updates는 패키지 업데이트 가능 여부를 확인하기 위한 도구임.
운영 서버에서는 확인 용도로만 사용하며, 실제 업데이트는 /home/[User]/[ProjectName] 또는 동등한 작업 경로에서 수행함.

8.1 npm-check-updates 설치 (전역)¶

sudo npm install -g npm-check-updates

전역 도구이므로 1회 설치로 충분함
/usr/bin/ncu 경로에 설치됨

8.2 로컬(프로젝트) 패키지 업데이트 확인¶

현재 프로젝트(package.json) 기준으로
업데이트 가능한 패키지를 확인만 함.

ncu

package.json 기준 최신 버전 비교
❌ 파일 변경 없음
❌ 실제 설치 없음
✅ 운영 서버에서 허용되는 명령

8.3 로컬 패키지 버전 범위 변경 (운영 서버 ❌)¶

ncu -u

package.json의 버전 범위를 최신으로 변경함
실제 설치는 수행하지 않음
이후 npm install 필요

⚠️ 운영 서버에서는 사용 금지
→ /home/[User]/[ProjectName] 또는 동등한 작업 경로에서만 수행함

8.4 전역 패키지 업데이트 확인¶

전역으로 설치된 npm 패키지 기준 업데이트 확인.

ncu -g

전역 패키지 목록만 출력
❌ 변경 없음
운영 서버에서는 확인만 허용함

8.5 전역 패키지 버전 범위 변경 (운영 서버 ❌)¶

ncu -u -g

전역 패키지 버전 정보 변경
실제 설치는 수행하지 않음

⚠️ 운영 서버에서는 사용 금지

8.6 실제 패키지 업데이트 적용 (운영 서버 ❌)¶

npm install
sudo npm install -g

실제 코드 및 의존성 변경 발생
장애 위험 있음

❌ 운영 서버에서는 절대 수행하지 않음

8.7 운영 기준 요약¶

구분	확인	버전 변경	실제 설치	운영 서버
로컬 패키지	`ncu`	`ncu -u`	`npm install`	확인만 허용
전역 패키지	`ncu -g`	`ncu -u -g`	`sudo npm install -g`	확인만 허용

운영 서버에서는
“업데이트 여부 확인”까지만 허용하고 변경 및 설치는 /home/[User]/[ProjectName] 또는 동등한 작업 경로에서만 수행함.

9. SELinux 컨텍스트 설정¶

Nginx가 특정 디렉터리에 대해 읽기/쓰기 권한이 필요한 경우 : httpd_sys_rw_content_t ex) uploads 읽기 전용 권한이 필요한 경우 : httpd_sys_content_t ex) public

확인¶

sudo semanage fcontext -l | grep /var/www/[ProjectName]

설정¶

위 목록에서 없으면 -a 있으면 -m

ex)

없을때

sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/[ProjectName]/uploads(/.*)?"
sudo restorecon -Rv /var/www/[ProjectName]/uploads

sudo semanage fcontext -a -t httpd_sys_content_t "/var/www/[ProjectName]/public(/.*)?"
sudo restorecon -Rv /var/www/[ProjectName]/public

있을때

sudo semanage fcontext -m -t httpd_sys_rw_content_t "/var/www/[ProjectName]/uploads(/.*)?"
sudo restorecon -Rv /var/www/[ProjectName]/uploads

sudo semanage fcontext -m -t httpd_sys_content_t "/var/www/[ProjectName]/public(/.*)?"
sudo restorecon -Rv /var/www/[ProjectName]/public

ex)

PROJECT="ProjectName"
PROJECT_ROOT="/var/www/${PROJECT}"
FOLDER="${PROJECT_ROOT}/uploads"
PATTERN="(/.*)?"

sudo semanage fcontext -a -t httpd_sys_rw_content_t "${FOLDER}${PATTERN}" 2>/dev/null || sudo semanage fcontext -m -t httpd_sys_rw_content_t "${FOLDER}${PATTERN}"
sudo restorecon -Rv "${FOLDER}"

sudo semanage fcontext -l | grep "^${FOLDER}(\s|$)"

PROJECT="ProjectName"
PROJECT_ROOT="/var/www/${PROJECT}"
FOLDER="${PROJECT_ROOT}/public"
PATTERN="(/.*)?"

sudo semanage fcontext -a -t httpd_sys_content_t "${FOLDER}${PATTERN}" 2>/dev/null || sudo semanage fcontext -m -t httpd_sys_content_t "${FOLDER}${PATTERN}"
sudo restorecon -Rv "${FOLDER}"

sudo semanage fcontext -l | grep "^${FOLDER}(\s|$)"

10. 정리¶

운영 서버에서는 전역 Node.js 설치만 사용함
nvm은 개발 환경 전용 도구임
Node.js는 PM2 기반으로 실행되는 전제에서 운영됨
개발(/home)과 운영(/var/www) 경로 분리는 필수 원칙임

Node.js 운영 환경의 출발점임.