Node.js 앱은 VPS에서만 돌릴 수 있다고 생각하기 쉽습니다. 그렇지 않습니다. Rivervo의 모든 공유 호스팅 요금제는 웹사이트 메뉴에 Node.js 및 Python이 있으며, 다른 사이트를 서비스하는 같은 Apache 프런트엔드 뒤에서 앱용 Phusion Passenger 프로세스를 실행합니다.
이 가이드는 가장 많이 쓰이는 두 프레임워크 Next.js와 Nuxt 3의 전체 과정을 다룹니다. 최종 결과는 https://hoesa.co.kr(또는 원하는 서브도메인)에서 실제 Node.js 프로세스로 동작하고, 재부팅 후에도 살아 있으며, 클릭 한 번으로 재시작할 수 있는 앱입니다.
공유 호스팅에 Node 앱을 배포해 본 적이 없다면 모두가 막히는 부분은 시작 파일입니다. Passenger는 프레임워크를 부팅하는 진입 스크립트 하나가 필요합니다. 아래에 프레임워크별로 준비해 두었으니 수정 없이 복사해 붙여 넣으면 됩니다.
시작하기 전에 필요한 것
- Rivervo 호스팅 요금제 (어떤 요금제든 — Node.js 앱은 모든 요금제에서 동작합니다)
- 앱을 빌드할 로컬 Node.js v20 이상
- 업로드할 빌드 결과물 (프레임워크별로 설명합니다)
- 계정에 대한 파일 관리자 또는 SFTP 접근 (둘 다 가능)
root, sudo, systemd, 리버스 프록시 설정은 필요 없습니다. Passenger가 모두 처리합니다.
1단계 — 로컬에서 앱 빌드
소스가 아니라 빌드된 앱을 올립니다. 관리 패널은 의존성을 설치하지만 React를 컴파일하거나 Vite 빌드를 실행하지는 않습니다. 먼저 내 컴퓨터에서 빌드하세요.
Next.js:
npm ci
npm run build.next/(빌드 결과물)가 생성됩니다. 여기서 next start는 실행하지 마세요. 잠시 뒤 시작 파일에서 실행합니다.
Nuxt 3:
npm ci
npm run build.output/(Nuxt의 범용 빌드 디렉터리)가 생성됩니다. 마찬가지로 아직 아무것도 실행하지 마세요.
2단계 — 올바른 파일 업로드
node_modules/는 올릴 필요가 없습니다. 관리 패널이 의존성을 설치해 줍니다. git이나 빌드 캐시도 필요 없습니다.
계정에 업로드하되, 가능하면 public_html 바깥 경로(예: /home/<account>/myapp/)에 올리세요. 왜 바깥일까요? Passenger가 public_html을 URL 루트에 자동으로 연결하기 때문에 그 안에 앱 코드를 두면 코드가 노출됩니다.
| 프레임워크 | 업로드할 것 | 제외할 것 |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, server.cjs (아래 참고) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, server.cjs (아래 참고) | node_modules/, .nuxt/, .git/, 소스 pages/, components/ |
파일을 올리는 방법은 두 가지입니다.
- 웹사이트 → 파일 → zip 업로드 → 압축 해제: 연결이 불안정할 때 가장 쉽습니다.
- SFTP (FileZilla, Cyberduck,
rsync): 반복 배포에 더 빠릅니다. 서버, 포트, 사용자, 비밀번호는 웹사이트 → SSH 및 SFTP에 있습니다.
3단계 — 시작 파일 추가
요청이 들어오면 Passenger가 실행하는 파일입니다. 앱 폴더의 package.json 옆에 두세요.
Next.js용 — server.cjs
const next = require('next')
const http = require('http')
const port = process.env.PORT || 3000
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev, dir: __dirname })
const handle = app.getRequestHandler()
app.prepare().then(() => {
http.createServer((req, res) => handle(req, res)).listen(port, () => {
console.log(`Next.js server listening on port ${port}`)
})
})하는 일:
- Next를 불러와 현재 디렉터리(
.next/와package.json이 있는 곳)를 가리킵니다. - Next 내부 라우터로 요청 핸들러를 만듭니다.
- Passenger가 지정한 포트(
process.env.PORT)로 HTTP 서버를 시작합니다. - 로컬 테스트용으로
3000을 기본값으로 씁니다.
dev는 NODE_ENV에서 자동으로 정해집니다. 관리 패널에서 Production 모드를 설정하면(4단계에서 합니다) Next가 프로덕션 모드로 실행됩니다.
Nuxt 3용 — server.cjs
import('./.output/server/index.mjs').then(({ createApp }) => {
createApp().then(({ app }) => {
const port = process.env.PORT || 3000
app.listen(port, () => {
console.log(`Nuxt server listening on port ${port}`)
})
})
})하는 일:
- Nuxt의
.output/server/index.mjs(npm run build가 만든 진입점)를 동적으로 가져옵니다. createApp()으로 H3 서버 인스턴스를 만듭니다.- Passenger가 지정한 포트에서 대기합니다.
동적 import()는 의도된 것입니다. .mjs 모듈은 require()할 수 없지만 .cjs 파일은 동적으로 가져올 수 있습니다. Passenger 런처 안에서 동작하는 가장 깔끔한 방식입니다.
4단계 — 관리 패널에서 애플리케이션 만들기
프로젝트 → 웹사이트 → Node.js 및 Python → Node.js application을 여세요.
| 항목 | 값 |
|---|---|
| Version | 20 이상 |
| Mode | Production |
| Folder | 홈 폴더의 myapp (파일을 올린 곳) |
| Address | hoesa.co.kr (또는 app.hoesa.co.kr 같은 서브도메인) |
| Start file | server.cjs |
만들기를 클릭하세요. ~/nodevenv/myapp/20/ 아래에 Node.js 환경이 만들어집니다.
의존성 설치
앱이 만들어지면 **Install dependencies (npm install)**을 클릭하고 출력을 지켜보세요. 실패하면:
package.json이 애플리케이션 루트에 있는지(하위 폴더가 아닌지) 확인하세요.- Next.js:
next가devDependencies가 아니라dependencies에 있는지 확인하세요 (프로덕션 설치는 dev 의존성을 건너뜁니다). - Nuxt:
nuxt자체도 일반 의존성이어야 합니다.
환경 변수 추가
앱의 설정 → Environment variables → Add a variable. Production 모드는 이미 NODE_ENV=production을 설정합니다.
런타임에 값을 읽는 Next.js 앱(데이터베이스 URL, API 키)이라면 여기에 추가하세요. 비밀 정보가 담긴 .env 파일은 올리지 마세요. 앱의 환경 변수가 올바른 위치입니다.
설정을 저장하면 앱이 재시작되어 새 변수가 바로 적용됩니다.
5단계 — 확인
애플리케이션 URL에 접속하세요. 앱이 보여야 합니다.
Passenger 오류 페이지가 보이면 펼쳐서 아래쪽을 보세요. 거의 항상 명확한 스택 트레이스가 있습니다. 가장 흔한 두 가지:
Error: Cannot find module 'next' — npm install이 실행되지 않았거나 잘못된 폴더에서 실행되었습니다. **Install dependencies (npm install)**을 다시 클릭하세요.
Error: ENOENT: no such file or directory, open '.next/...' — 소스만 올리고 빌드된 .next/ 디렉터리는 올리지 않았습니다. 로컬에서 빌드해 다시 올리세요.
업데이트 배포 방법
1, 2단계를 반복하고 앱에서 Restart를 클릭하세요. 구체적으로:
1. 로컬 빌드 npm run build
2. 업로드 .next/ 또는 .output/, 변경된 소스/설정
3. 관리 패널 앱 재시작package.json을 바꿨다면 재시작 전에 **Install dependencies (npm install)**을 클릭하세요. 명령줄이 편하다면 웹사이트 → 터미널: 앱 카드에 앱 환경으로 들어가는 명령이 표시됩니다.
흔한 함정
WebSocket: Passenger는 HTTP/1.1과 HTTP/2를 처리합니다. Next.js와 Nuxt의 내장 라우트에서는 WebSocket 업그레이드가 동작합니다. 별도 WebSocket 서버(ws, socket.io)를 쓴다면 같은 포트를 공유하고 같은 server.cjs로 시작합니다. 추가 설정은 없습니다.
파일 업로드 / next.config.js body-parser 제한: Passenger의 기본 요청 본문 제한은 10 MB입니다. 큰 파일을 업로드한다면 public_html의 .htaccess로 passenger_max_request_size를 높이세요.
PassengerMaxRequestSize 52428800(바이트 단위로 50 MB입니다.)
크론 작업: 앱에 백그라운드 작업(뉴스레터 발송, 예약 내보내기)이 필요하면 웹 프로세스 안에서 돌리지 마세요. 웹사이트 → 크론 작업에서 Node 스크립트를 직접 실행하세요.
/home/<account>/nodevenv/myapp/20/bin/node /home/<account>/myapp/scripts/send-newsletter.js프로세스 메모리: 앱이 계정별 RAM 한도(요금제에 따라 다름)를 넘으면 Passenger가 재시작합니다. 일반적인 Next.js / Nuxt 앱은 유휴 상태에서 100 MB 미만입니다. 한도에 걸린다면 더 큰 요금제가 필요하다고 판단하기 전에 process.memoryUsage()로 프로파일링해 누수를 찾아보세요.
사용자 도메인과 HTTPS: 앱에 설정한 주소가 Passenger가 연결하는 주소입니다. SSL은 자동이며 추가 설정이 없습니다. 다른 도메인이나 서브도메인을 쓰려면 먼저 웹사이트 → 도메인에서 추가한 뒤 앱 주소로 선택하세요.
Node 버전: Version 목록에 설치된 모든 버전이 표시됩니다. 앱의 설정에서 바꾸세요.
Node에 공유 호스팅을 쓰지 말아야 할 때
솔직히 말해 공유 호스팅의 Node.js는 포트폴리오 사이트, 블로그, 마케팅 페이지, 소규모 SaaS 프런트엔드, 사내 도구에 아주 잘 맞습니다. 다음에는 어렵습니다.
- 처리량이 높은 API (지속적으로 초당 50건 초과) — 계정별 CPU 한도를 체감하게 됩니다
- 동시 연결이 수천 개인 WebSocket 중심 앱
- 워커 프로세스를 포크하는 앱(큐 워커, 스크레이퍼) — Passenger의 계정별 프로세스 한도 때문에 불편합니다
- systemd, Docker, root 접근이 필요한 모든 것
이런 경우에는 Rivervo VPS가 맞습니다. 완전한 root 권한, 자체 커널, 원하는 무엇이든 실행할 수 있습니다. 하지만 엄청난 트래픽을 받지 않는 대부분의 Next.js와 Nuxt 앱이라면 이 가이드로 충분합니다.
요약
- 로컬에서
npm run build .next/(Next) 또는.output/(Nuxt) +package.json+server.cjs업로드- 웹사이트 → Node.js 및 Python → Node.js application → 폴더, 시작 파일
server.cjs, 모드 Production - Install dependencies (npm install) 후 Restart
문제가 생기면 문의를 남겨 주세요. Passenger 오류 페이지를 붙여 넣으면 원인이 되는 줄을 짚어 드립니다.
— Rivervo 팀