Namecheap 공유 호스팅에 NestJS 배포하는 방법

Namecheap 공유 호스팅에 NestJS를 배포하는 것은 정적 사이트나 PHP 앱을 배포하는 것과는 다릅니다. 단순히 파일을 업로드한다고 해서 바로 작동하지 않습니다.

TypeScript를 JavaScript로 컴파일하고, 프로덕션 의존성을 설치하며, cPanel을 통해 Passenger로 프로세스를 관리해야 합니다.

올바른 방법을 찾기 전까지 빈 폴더, 빌드 파일 누락, Redis 연결 끊김 등의 문제를 겪었습니다. 여기 검증된 워크플로우를 소개합니다.

설정 로직

요청은 다음 경로를 따릅니다: • 브라우저 또는 API 클라이언트 • 도메인 및 HTTPS • Namecheap의 Apache / Passenger • app.js (브릿지) • dist/main.js (컴파일된 코드) • NestJS 애플리케이션

주요 요구 사항

• Node.js를 지원하는 Namecheap 호스팅 계정 • cPanel 및 SSH/터미널 접속 권한 • 정상 작동하는 NestJS 프로젝트 • 데이터베이스 또는 Redis용 프로덕션 자격 증명

1단계: 코드 준비하기

포트를 하드코딩하지 마세요. src/main.ts에서 process.env.PORT를 사용하세요:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT || 4000);
}

2단계: 의존성 정리하기

@nestjs/common 및 @nestjs/core와 같은 런타임 패키지를 package.json의 dependencies 섹션으로 이동하세요. 만약 devDependencies에 남아 있다면 프로덕션 환경에서 앱이 충돌할 것입니다.

3단계: 빌드 및 브릿지 생성하기

Namecheap은 TypeScript가 아닌 JavaScript를 실행합니다. • 로컬에서 npm run build를 실행합니다. • dist/main.js가 존재하는지 확인합니다. • 프로젝트 루트에 다음 코드가 포함된 app.js 파일을 생성합니다: require('./dist/main');

이 app.js는 Passenger의 엔트리 포인트(entry point) 역할을 합니다.

4단계: 배포 전략

가장 안전한 방법은 로컬에서 빌드한 후 결과물(artifacts)을 업로드하는 것입니다: • app.js 업로드 • dist/ 폴더 업로드 • package.json 및 package-lock.json 업로드 • Namecheap에서 다음 명령 실행: npm ci --omit=dev

로컬의 node_modules 폴더를 절대 업로드하지 마세요. 컴퓨터에서 빌드된 네이티브 모듈은 Linux 서버에서 작동하지 않습니다.

5단계: cPanel 설정하기

cPanel의 Setup Node.js App으로 이동합니다: • 올바른 Node.js 버전을 선택합니다. • 모드를 Production으로 설정합니다. • Application root를 해당 폴더로 설정합니다. • Application startup file을 app.js로 설정합니다.

6단계: 환경 변수

비밀 정보(예: DATABASE_URL 또는 API 키)를 cPanel Node.js 인터페이스에 직접 추가하세요. 루트에 .env 파일을 사용할 수도 있지만, 반드시 dist 폴더 안에 있지 않도록 주의하세요. 변경 사항을 적용한 후에는 앱을 재시작해야 합니다.

일반적인 문제 해결

• EADDRINUSE: 수동으로 실행 중인 프로세스가 있을 가능성이 높습니다. Passenger가 앱을 관리하도록 두세요. • Cannot find module: 빌드 파일이 누락되었거나 app.js의 경로가 잘못되었습니다. • Redis connection failed: Namecheap이 사용 중인 Redis 포트에 대한 아웃바운드 연결을 허용하는지 확인하세요. 필요하다면 Namecheap 고객 지원팀에 포트 개방을 요청해야 할 수도 있습니다.

출처: https://dev.to/adesoji/how-to-deploy-and-run-a-nestjs-app-on-namecheap-shared-hosting-5c45