웹 호스팅 가이드 (Crypto Wallet Core API)

NestJS API 서버와 Swagger 문서를 웹에서 접속 가능하게 배포하는 방법입니다.

1. 배포 전 준비

1.1 프로덕션 빌드

# 루트에서
npm install
npm run build

API 서버만 빌드하려면:

cd apps/api && npm run build

빌드 결과물: apps/api/dist/ (여기서 node dist/main.js로 실행)

1.2 환경 변수 (.env)

배포 서버에도 .env를 두고, 다음 항목을 설정합니다.

• PORT – 서버 포트 (기본 3000)
• NODE_ENV=production
• BITCOIN_NODES, ETHEREUM_NODES, SOLANA_NODES, BNB_NODES – RPC URL (쉼표로 여러 개 가능)

2. 호스팅 방법

방법 A: VPS(가상 서버)에서 Node로 실행

대상: AWS EC2, DigitalOcean, Naver Cloud, GCP 등 Linux 서버

1. 서버에 Node.js 18+ 설치

   # Ubuntu 예시 (Node 20 LTS)
   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt-get install -y nodejs
   

2. 프로젝트 업로드

   • Git clone 또는 rsync/scp로 apps/api와 packages/core 등 필요한 디렉터리 복사

3. 의존성 설치 및 빌드

   cd /path/to/crypto-wallet-core
   npm ci
   npm run build
   

4. 프로세스 매니저(PM2)로 실행

   npm install -g pm2
   cd apps/api
   pm2 start dist/main.js --name crypto-api
   pm2 save && pm2 startup   # 재부팅 후 자동 실행
   

5. 외부 접속

   • 방화벽에서 PORT(예: 3000) 열기
   • 브라우저: http://서버IP:3000 → API, http://서버IP:3000/api → Swagger UI

6. (선택) Nginx 리버스 프록시 + HTTPS

   • 80/443 포트만 열고 Nginx가 3000으로 프록시
   • Let’s Encrypt로 SSL 적용 후 https://도메인/api 로 Swagger 접속

방법 B: Docker로 배포

대상: Docker를 지원하는 호스팅(AWS ECS, Railway, Fly.io, 자체 서버 등)

프로젝트 루트에 Dockerfile과 .dockerignore가 포함되어 있습니다.

1. 이미지 빌드 및 실행

   docker build -t crypto-wallet-api .
   docker run -p 3000:3000 --env-file .env crypto-wallet-api
   

2. 환경 변수만 넘기기

   docker run -p 3000:3000 -e PORT=3000 -e NODE_ENV=production \
     -e BITCOIN_NODES=https://bitcoin-rpc.publicnode.com \
     -e ETHEREUM_NODES=https://ethereum-rpc.publicnode.com \
     -e SOLANA_NODES=https://solana-rpc.publicnode.com \
     -e BNB_NODES=https://bsc-rpc.publicnode.com \
     crypto-wallet-api
   

3. 호스팅
   해당 서비스의 “컨테이너 실행” 방식에 맞춰 이미지와 포트(3000), 환경 변수만 설정하면 됩니다.

방법 C: PaaS(플랫폼 서비스)

대상: 코드만 올리면 서비스가 알아서 빌드·실행해 주는 곳

무료로 오래 쓸 때 추천 순서: Fly.io(24/7 무료) → Render(슬립 있지만 핑으로 유지 가능) → Railway(실질 유료).

Vercel은 가능한가?

가능합니다. Vercel은 NestJS를 공식 지원하며(Zero-config), Git 푸시만으로 배포할 수 있습니다. 다만 서버리스(함수 단위) 로 동작합니다.

• 장점: 설정 간단, 무료 티어, 트래픽에 따라 자동 스케일, 프리뷰 배포
• 단점: 요청당 실행 시간 제한(무료 10초·Pro 60초), 콜드 스타트 가능, 함수 번들 크기 250MB 제한. RPC 호출·블록체인 연동처럼 응답이 늦어질 수 있는 API는 타임아웃이 걸릴 수 있음.
• 정리: Swagger 문서 확인·간단한 API 테스트용으로는 적합. 상시 실행이 필요하거나 응답이 오래 걸리는 작업이 많다면 Fly.io·Render 같은 상시 실행 서버가 더 적합합니다.

공통 설정 요점 (Fly.io / Render / Railway)

• Root/빌드 디렉터리: 모노레포이므로 보통 루트를 기준으로 하고, 빌드 스크립트에서 npm run build (또는 cd apps/api && npm run build) 지정
• 시작 명령: node apps/api/dist/main.js 또는 cd apps/api && node dist/main.js
• 환경 변수: 대시보드에서 PORT, NODE_ENV, RPC 관련 변수 입력

배포 후 제공되는 URL 예: https://your-app.up.railway.app → API 루트, https://your-app.up.railway.app/api → Swagger UI.

5. Vercel 배포 단계별 안내

이 프로젝트는 모노레포(루트 package.json + apps/api, packages/core) 구조라서, Vercel에서 Root Directory와 빌드 명령을 지정해야 합니다.

5.1 사전 준비

• GitHub(또는 GitLab/Bitbucket)에 저장소 푸시
• Vercel 계정 (GitHub 연동 권장)

5.2 프로젝트 연결

1. Vercel 대시보드 → Add New… → Project
2. Import Git Repository에서 해당 저장소 선택 후 Import
3. Configure Project 화면에서 아래 설정 적용

5.3 빌드 설정 (필수)

Root Directory를 어디서 바꾸나요?

• 처음 프로젝트 Import 시: "Configure Project" 화면에 Root Directory가 있으면 옆 Edit 클릭 → apps/api 입력 → Save.
• 이미 만들어 둔 프로젝트이거나 Edit이 안 보일 때:
  1. Vercel 대시보드에서 해당 프로젝트 클릭
  2. 상단 Settings 탭 클릭
  3. 왼쪽 또는 본문에서 Build and Deployment (또는 General) 섹션으로 이동
  4. Root Directory 항목 찾기 → Edit 또는 Override 클릭
  5. 값에 apps/api 입력 후 저장
• 한 번도 설정한 적 없으면 기본값이 비어 있어서 저장소 루트로 인식됩니다. 반드시 apps/api로 바꿔야 NestJS가 인식되고, 아래 Install/Build 명령이 올바르게 동작합니다.
• 첫 배포는 루트로 했다가 나중에 바꿔도 됩니다. Settings에서 Root Directory만 apps/api로 수정한 뒤 Redeploy 하면 됩니다.
• UI가 다르면: Vercel 문서 - Configure a Build에서 "Root Directory" 항목 위치를 확인할 수 있습니다.

설정 요약

이유: API가 packages/core 워크스페이스에 의존하므로, 설치와 빌드는 저장소 루트에서 해야 합니다. Root Directory를 apps/api로 두면 작업 디렉터리는 apps/api인데, cd ../..로 루트로 올라가서 npm ci·npm run build를 실행합니다.

5.4 환경 변수

Settings → Environment Variables에서 다음 변수 추가 (프로덕션·프리뷰 모두 필요한 것만 적용):

.env에 있던 값을 그대로 넣으면 됩니다. PORT는 Vercel이 지정하므로 넣지 않아도 됩니다.

5.5 배포 실행

1. Deploy 버튼 클릭
2. 빌드·배포가 끝나면 Visit 또는 배포 URL로 접속
3. 접속 경로:
   • API 루트: https://<프로젝트명>.vercel.app/
   • Swagger UI: https://<프로젝트명>.vercel.app/api

5.6 CLI로 배포 (선택)

# Vercel CLI 설치 (최소 48.4.0)
npm i -g vercel

# 프로젝트 루트에서
cd /path/to/crypto-wallet-core
vercel

# 첫 실행 시 로그인·프로젝트 연결 후, Root Directory를 apps/api로 설정하라는 안내가 나오면 대시보드에서 설정

이후에는 vercel --prod 로 프로덕션 배포가 가능합니다.

5.7 문제 해결

• / 또는 /api 접속 시 빈 화면 / 응답 없음
  → 진입점은 src/main.ts 하나이며, Vercel은 Fluid compute로 app.listen(PORT) 방식으로 앱을 실행합니다. 별도 서버리스 핸들러 export는 사용하지 않습니다. Root Directory가 apps/api인지, 빌드 결과물에 dist/main.js가 생성되는지 확인하세요.

• 빌드 실패: Cannot find module '@crypto-wallet-core/core'
  → Install Command와 Build Command에 cd ../.. 가 들어가 있는지, Root Directory가 apps/api인지 확인.

• 타임아웃 (10초/60초 초과)
  → RPC 호출이 길어지면 서버리스 제한에 걸립니다. 이런 API가 많다면 Fly.io·Render 등 상시 실행 서버 사용을 권장.

• 250MB 초과
  → 함수 번들 크기 제한. 불필요한 의존성 제거 또는 상시 실행 서버로 이전을 고려.

• Swagger UI(/api) 빈 페이지·CSS/JS 404
  → 서버리스에서는 swagger-ui-dist 정적 파일이 로드되지 않을 수 있습니다. 이 프로젝트는 빌드 시 scripts/copy-swagger-ui-dist.cjs로 swagger-ui-dist를 dist/swagger-ui-dist에 복사하고, main.ts에서 customSwaggerUiPath로 해당 경로를 지정합니다. Vercel 배포 시 Build Command에 nest build && node scripts/copy-swagger-ui-dist.cjs가 포함되어야 하며(또는 npm run build가 해당 스크립트를 실행), Root Directory가 apps/api이면 빌드 결과에 dist/swagger-ui-dist가 포함됩니다.
  → 대안: Swagger 설정에서 CDN 사용 — customCssUrl·customJs에 cdnjs 등 URL을 지정하면 정적 파일을 CDN에서 불러올 수 있습니다. (버전은 @nestjs/swagger가 사용하는 swagger-ui-dist와 맞추는 것이 좋습니다.)

3. 접속 경로 정리

4. 보안 참고

• .env는 절대 Git에 올리지 말고, 배포 환경에서만 설정
• 프로덕션에서는 CORS를 필요한 도메인으로만 제한하는 것이 좋음
• RPC URL에 API 키가 들어가면 환경 변수로만 관리하고 코드에 하드코딩하지 않기