Next.js 설치¶
Next.js는 Node.js 런타임 기반이며, 아래 내용은 Node.js 운영 기준을 Next.js에 적용한 정리임.
운영 서버(Production Server) 에서 Next.js 운영에 필요한
Node.js 런타임 설치와 Next.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]
이 단계에서는 실행 경로만 준비함.
애플리케이션 배포 및 실행은 이후 문서에서 다룸.
7-4. 이미지 최적화 도구 설치 (운영 서버)¶
Next.js 이미지 최적화 사용 시 서버에 아래 도구 설치를 권장함.
sudo dnf install -y ImageMagick
sudo dnf install -y optipng
sudo dnf install -y jpegoptim
운영 배포 전에는 반드시
/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은 개발 환경 전용 도구임
- Next.js는 PM2 기반으로 실행되는 전제에서 운영됨
- 개발(
/home)과 운영(/var/www) 경로 분리는 필수 원칙임
Next.js 운영 환경의 출발점임.