@kood/claude-code 0.1.1 → 0.1.3

package/templates/tanstack-start/docs/deployment/railway.md

@@ -1,52 +1,102 @@
 # Railway 배포
 
 > **상위 문서**: [배포](./index.md)
+> **Version**: Nitro 3.x
 
 Railway는 Node.js 서버를 간편하게 배포할 수 있는 플랫폼입니다.
 
-## 빠른 시작
+---
 
-### 1. Nitro 설정
+## 🚀 Quick Reference (복사용)
 
 ```typescript
 // nitro.config.ts
 import { defineNitroConfig } from 'nitro/config'
 
 export default defineNitroConfig({
-  preset: 'node-server',
+  preset: 'node',
+  compatibilityDate: '2024-09-19',
 })
 ```
 
-### 2. Vite 설정
+```json
+// package.json scripts
+{
+  "scripts": {
+    "build": "vite build && tsc --noEmit",
+    "start": "node .output/server/index.mjs"
+  }
+}
+```
+
+```bash
+# Railway CLI 배포
+railway login
+railway init
+railway up
+```
+
+---
+
+## Nitro 설정
+
+### nitro.config.ts
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  // Node.js 서버 preset
+  preset: 'node',
+
+  // 호환성 날짜 (Nitro v3 필수)
+  compatibilityDate: '2024-09-19',
+})
+```
+
+---
+
+## Vite 설정
 
 ```typescript
 // vite.config.ts
 import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
 import { tanstackStart } from '@tanstack/react-start/plugin/vite'
 import { nitro } from 'nitro/vite'
+import viteReact from '@vitejs/plugin-react'
 
 export default defineConfig({
   plugins: [
     tanstackStart(),
     nitro(),
-    react(),
+    viteReact(),
   ],
 })
 ```
 
-### 3. 빌드 스크립트
+---
+
+## package.json 설정
 
 ```json
-// package.json
 {
+  "name": "tanstack-start-app",
+  "type": "module",
   "scripts": {
-    "build": "vite build",
-    "start": "node .output/server/index.mjs"
+    "dev": "vite dev",
+    "build": "vite build && tsc --noEmit",
+    "start": "node .output/server/index.mjs",
+    "preview": "vite preview"
+  },
+  "engines": {
+    "node": ">=20.0.0"
   }
 }
 ```
 
+---
+
 ## Railway 설정
 
 ### railway.json
@@ -56,46 +106,70 @@ export default defineConfig({
   "$schema": "https://railway.app/railway.schema.json",
   "build": {
     "builder": "NIXPACKS",
-    "buildCommand": "yarn install && yarn build"
+    "buildCommand": "pnpm install && pnpm build"
   },
   "deploy": {
     "startCommand": "node .output/server/index.mjs",
-    "healthcheckPath": "/",
-    "healthcheckTimeout": 100,
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 300,
     "restartPolicyType": "ON_FAILURE",
-    "restartPolicyMaxRetries": 10
+    "restartPolicyMaxRetries": 3
   }
 }
 ```
 
-### nixpacks.toml (선택사항)
+### railway.toml (선택)
+
+```toml
+# railway.toml
+[build]
+builder = "nixpacks"
+buildCommand = "pnpm install && pnpm build"
+
+[deploy]
+startCommand = "node .output/server/index.mjs"
+healthcheckPath = "/health"
+healthcheckTimeout = 300
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 3
+```
+
+### nixpacks.toml (선택)
 
 ```toml
 [phases.setup]
 nixPkgs = ["nodejs_20"]
 
 [phases.install]
-cmds = ["yarn install"]
+cmds = ["corepack enable pnpm", "pnpm install"]
 
 [phases.build]
-cmds = ["yarn build"]
+cmds = ["pnpm build"]
 
 [start]
 cmd = "node .output/server/index.mjs"
 ```
 
-## 환경변수
+---
 
-### Railway 대시보드에서 설정
+## 배포 방법
 
-1. Railway 대시보드 → 프로젝트 선택
-2. Variables 탭 클릭
-3. 환경변수 추가:
-   - `NODE_ENV=production`
-   - `DATABASE_URL=...`
-   - `API_SECRET=...`
+### 방법 1: GitHub 연동 (권장)
 
-### Railway CLI 사용
+1. **Railway 프로젝트 생성**
+   - [Railway 대시보드](https://railway.app) 접속
+   - "New Project" → "Deploy from GitHub repo" 선택
+   - 저장소 연결
+
+2. **자동 감지**
+   - Railway가 자동으로 Node.js 프로젝트 감지
+   - `package.json`의 `build`, `start` 스크립트 사용
+
+3. **환경 변수 설정**
+   - Railway 대시보드에서 Variables 탭 선택
+   - 필요한 환경 변수 추가
+
+### 방법 2: Railway CLI
 
 ```bash
 # Railway CLI 설치
@@ -104,113 +178,148 @@ npm install -g @railway/cli
 # 로그인
 railway login
 
-# 환경변수 설정
-railway variables set DATABASE_URL=postgresql://...
-railway variables set API_SECRET=your-secret
+# 프로젝트 초기화
+railway init
 
-# 환경변수 확인
-railway variables
+# 배포
+railway up
+
+# 환경 변수 설정
+railway variables set DATABASE_URL="postgresql://..."
+railway variables set API_SECRET="your-secret"
+
+# 로그 확인
+railway logs
 ```
 
-## 데이터베이스 연결
+### 방법 3: Docker 배포
+
+Railway는 Dockerfile을 자동으로 감지합니다.
+
+```dockerfile
+# Dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable pnpm && pnpm install
+COPY . .
+RUN pnpm build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/.output ./.output
+ENV PORT=3000 NODE_ENV=production
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
 
-### PostgreSQL
+---
 
-Railway에서 PostgreSQL 서비스 추가 후:
+## 환경변수
 
-```bash
-# 자동 생성된 환경변수 사용
-DATABASE_URL=${{ Postgres.DATABASE_URL }}
+### Railway 대시보드에서 설정
+
+```
+DATABASE_URL=postgresql://user:pass@host:5432/db
+API_SECRET=your-secret-key
+NODE_ENV=production
 ```
 
-### Prisma와 함께 사용
+### 코드에서 사용
 
 ```typescript
-// server/db.ts
-import { PrismaClient } from './generated/prisma'
+// server/api/health.ts
+import { defineHandler } from 'nitro/h3'
 
-const prisma = new PrismaClient({
-  datasources: {
-    db: {
-      url: process.env.DATABASE_URL,
+export default defineHandler(() => {
+  return {
+    status: 'ok',
+    environment: process.env.NODE_ENV,
+    // Railway 자동 제공 변수
+    railway: {
+      environment: process.env.RAILWAY_ENVIRONMENT,
+      service: process.env.RAILWAY_SERVICE_NAME,
     },
-  },
+  }
 })
-
-export default prisma
 ```
 
-## 포트 설정
+### Railway 자동 제공 변수
 
-Railway는 `PORT` 환경변수를 자동 제공합니다:
+| 변수 | 설명 |
+|------|------|
+| `PORT` | 서버 포트 (자동 할당) |
+| `RAILWAY_ENVIRONMENT` | 환경 (production, staging 등) |
+| `RAILWAY_SERVICE_NAME` | 서비스 이름 |
+| `RAILWAY_PROJECT_ID` | 프로젝트 ID |
+| `RAILWAY_DEPLOYMENT_ID` | 배포 ID |
 
-```typescript
-// nitro.config.ts
-import { defineNitroConfig } from 'nitro/config'
+---
 
-export default defineNitroConfig({
-  preset: 'node-server',
-  // Railway의 PORT 환경변수 사용
-})
-```
+## 데이터베이스 연동
 
-서버 코드에서:
+### PostgreSQL 추가
 
-```typescript
-// .output/server/index.mjs (자동 생성됨)
-// Nitro가 자동으로 PORT 환경변수를 사용
-```
+1. Railway 대시보드에서 "New" → "Database" → "PostgreSQL" 선택
+2. 자동으로 `DATABASE_URL` 환경 변수 연결
 
-## 배포 방법
+```typescript
+// server/lib/db.ts
+import { PrismaClient } from '@prisma/client'
 
-### GitHub 연동 (권장)
+// Railway의 DATABASE_URL 자동 사용
+export const prisma = new PrismaClient()
+```
 
-1. Railway 대시보드에서 "New Project" 클릭
-2. "Deploy from GitHub repo" 선택
-3. 저장소 선택 및 연결
-4. 자동 배포 설정 완료
+### Redis 추가
 
-### Railway CLI
+1. Railway 대시보드에서 "New" → "Database" → "Redis" 선택
+2. `REDIS_URL` 환경 변수 자동 연결
 
-```bash
-# 프로젝트 초기화
-railway init
+```typescript
+// server/lib/redis.ts
+import { createClient } from 'redis'
 
-# 배포
-railway up
+const client = createClient({
+  url: process.env.REDIS_URL,
+})
 
-# 로그 확인
-railway logs
+export default client
 ```
 
-## 커스텀 도메인
+---
 
-### Railway 대시보드에서
+## 도메인 설정
 
-1. 프로젝트 Settings 탭
-2. Domains 섹션
-3. "Generate Domain" 또는 "Custom Domain" 추가
+### 자동 도메인
 
-### CLI 사용
+Railway는 자동으로 도메인을 생성합니다:
+- `your-app-production.up.railway.app`
 
-```bash
-# 도메인 추가
-railway domain add example.com
+### 커스텀 도메인
 
-# 도메인 확인
-railway domain
-```
+1. Railway 대시보드 → Settings → Domains
+2. "Add Custom Domain" 클릭
+3. DNS 설정:
+   ```
+   CNAME your-domain.com → your-app-production.up.railway.app
+   ```
+
+---
 
 ## 헬스체크
 
-### 기본 헬스체크 엔드포인트
+### 헬스체크 엔드포인트
 
 ```typescript
 // server/api/health.ts
 import { defineHandler } from 'nitro/h3'
 
 export default defineHandler(() => {
-  return { status: 'ok', timestamp: new Date().toISOString() }
+  return {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+  }
 })
 ```
 
@@ -220,60 +329,51 @@ export default defineHandler(() => {
 {
   "deploy": {
     "healthcheckPath": "/api/health",
-    "healthcheckTimeout": 100
+    "healthcheckTimeout": 300
   }
 }
 ```
 
-## 스케일링
+---
 
-### 수평 스케일링
-
-Railway 대시보드에서:
-1. Settings → Scaling
-2. 인스턴스 수 조정
+## CI/CD 설정
 
-### 리소스 설정
+### GitHub Actions
 
-```json
-// railway.json
-{
-  "deploy": {
-    "numReplicas": 2
-  }
-}
-```
+```yaml
+# .github/workflows/railway.yml
+name: Deploy to Railway
 
-## 로깅 및 모니터링
+on:
+  push:
+    branches: [main]
 
-### 로그 확인
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
-```bash
-# 실시간 로그
-railway logs -f
+      - name: Install Railway CLI
+        run: npm install -g @railway/cli
 
-# 최근 로그
-railway logs --lines 100
+      - name: Deploy
+        run: railway up
+        env:
+          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
 ```
 
-### 메트릭 확인
-
-Railway 대시보드에서:
-- CPU 사용량
-- 메모리 사용량
-- 네트워크 트래픽
-- 요청 수
-
-## CI/CD 설정
-
-### GitHub Actions
+### 환경별 배포
 
 ```yaml
-name: Deploy to Railway
+# .github/workflows/railway-env.yml
+name: Deploy to Railway (Multi-Environment)
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
+      - staging
 
 jobs:
   deploy:
@@ -284,33 +384,92 @@ jobs:
       - name: Install Railway CLI
         run: npm install -g @railway/cli
 
-      - name: Deploy
-        run: railway up
+      - name: Deploy to Production
+        if: github.ref == 'refs/heads/main'
+        run: railway up --environment production
         env:
           RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+
+      - name: Deploy to Staging
+        if: github.ref == 'refs/heads/staging'
+        run: railway up --environment staging
+        env:
+          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+```
+
+---
+
+## 모니터링
+
+### 로그 확인
+
+```bash
+# CLI로 로그 확인
+railway logs
+
+# 실시간 로그
+railway logs -f
+
+# 특정 서비스 로그
+railway logs --service my-service
 ```
 
-### Railway 토큰 생성
+### 메트릭 확인
+
+Railway 대시보드에서 확인 가능:
+- CPU 사용량
+- 메모리 사용량
+- 네트워크 트래픽
+- 요청 수
+
+---
+
+## 비용 최적화
 
-1. Railway 대시보드 → Account Settings
-2. Tokens 섹션에서 새 토큰 생성
-3. GitHub Secrets에 `RAILWAY_TOKEN`으로 저장
+### Hobby Plan 활용
+
+```toml
+# railway.toml
+[deploy]
+# 유휴 시 슬립 (Hobby Plan)
+sleepAfterInactivity = 300  # 5분 후 슬립
+```
+
+### 리소스 제한
+
+Railway 대시보드에서 설정:
+- Memory Limit: 512MB (시작점)
+- Replicas: 1 (시작점)
+
+---
 
 ## 트러블슈팅
 
-### 빌드 실패
+### 일반적인 문제
+
+| 문제 | 원인 | 해결 |
+|------|------|------|
+| 빌드 실패 | 의존성 오류 | `pnpm-lock.yaml` 커밋 확인 |
+| 포트 바인딩 실패 | 하드코딩된 포트 | `process.env.PORT` 사용 |
+| 메모리 초과 | 메모리 누수 | 리소스 제한 증가 또는 코드 최적화 |
+| 헬스체크 실패 | 엔드포인트 없음 | `/health` 엔드포인트 추가 |
+
+### 디버깅
 
 ```bash
-# 로컬에서 빌드 테스트
-NITRO_PRESET=node-server yarn build
+# 로컬에서 Railway 환경 시뮬레이션
+railway run pnpm dev
 
-# 시작 명령 테스트
-node .output/server/index.mjs
+# 환경 변수 확인
+railway variables
+
+# 서비스 상태 확인
+railway status
 ```
 
-### 포트 바인딩 오류
+### 포트 바인딩
 
-Railway는 `PORT` 환경변수를 자동 설정합니다. 하드코딩된 포트가 없는지 확인:
+Railway는 `PORT` 환경변수를 자동 설정합니다:
 
 ```typescript
 // ❌ 잘못된 예
@@ -320,19 +479,7 @@ const port = 3000
 const port = process.env.PORT || 3000
 ```
 
-### 메모리 초과
-
-```json
-// railway.json
-{
-  "deploy": {
-    "restartPolicyType": "ON_FAILURE",
-    "restartPolicyMaxRetries": 10
-  }
-}
-```
-
-Node.js 메모리 제한 설정:
+### 메모리 설정
 
 ```json
 // package.json
@@ -343,6 +490,8 @@ Node.js 메모리 제한 설정:
 }
 ```
 
+---
+
 ## 프로젝트 구조
 
 ```
@@ -357,8 +506,11 @@ my-app/
 └── railway.json
 ```
 
+---
+
 ## 참고 자료
 
+- [TanStack Start Hosting](https://tanstack.com/start/latest/docs/framework/react/hosting)
 - [Railway 공식 문서](https://docs.railway.app)
 - [Railway CLI](https://docs.railway.app/reference/cli-api)
-- [Nitro Node Server Preset](https://nitro.build/deploy/providers/node)
+- [Nitro Node Preset](https://nitro.build/deploy/providers/node)