배포 - 🌲 Sonamu

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

빌드와 배포

프로덕션 빌드를 만들려면?

API 서버 빌드:

cd api
pnpm build

빌드 결과물은 api/dist 디렉터리에 생성됩니다.Web 프론트엔드 빌드:

cd web
pnpm build

빌드 결과물은 web/dist 디렉터리에 생성됩니다.

프로덕션 환경에서 실행하려면?

API 서버:

cd api
NODE_ENV=production node dist/index.js

또는 PM2 사용:

pm2 start dist/index.js --name sonamu-api

Web 서버:Nginx나 Apache로 정적 파일 서빙:

# nginx.conf
server {
  listen 80;
  server_name example.com;

  root /var/www/sonamu/web/dist;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /api {
    proxy_pass http://localhost:34900;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }
}

환경 변수

환경 변수를 설정하려면?

Sonamu는 NODE_ENV에 따라 .env.{environment} 파일을 자동으로 로드합니다..env.production 파일 생성:

# api/.env.production

# Database (SONAMU_DB_ 접두사 사용)
SONAMU_DB_HOST=prod-db.example.com
SONAMU_DB_PORT=5432
SONAMU_DB_NAME=myapp_production
SONAMU_DB_USER=postgres
SONAMU_DB_PASSWORD=secure_password

# Server
PORT=34900

# CORS
CORS_ORIGIN=https://example.com

# Cache (Redis)
REDIS_HOST=redis.example.com
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

Sonamu가 SONAMU_DB_* 환경변수를 읽어 DB 연결을 자동으로 구성하므로, sonamu.config.ts에서 직접 연결 정보를 지정할 필요가 없습니다. 기본값을 오버라이드하고 싶다면 database.defaultOptions를 사용합니다:

import { defineConfig } from "sonamu";

export default defineConfig({
  // ...
  database: {
    database: "pg",
    defaultOptions: {
      pool: { min: 2, max: 10 },
    },
  },
  server: {
    listen: {
      port: Number(process.env.PORT) || 34900,
    },
    // ...
  },
});

민감한 정보를 안전하게 관리하려면?

방법 1: 환경 변수

# .env 파일은 .gitignore에 추가
echo ".env" >> .gitignore
echo ".env.*" >> .gitignore

방법 2: Secret 관리 도구

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault

// AWS Secrets Manager 예시
import { SecretsManager } from "@aws-sdk/client-secrets-manager";

const client = new SecretsManager({ region: "us-east-1" });

async function getSecret(secretName: string) {
  const response = await client.getSecretValue({ SecretId: secretName });
  return JSON.parse(response.SecretString!);
}

const dbSecret = await getSecret("prod/database");

데이터베이스

프로덕션 데이터베이스 마이그레이션을 실행하려면?

1. 마이그레이션 상태 확인:

NODE_ENV=production pnpm sonamu migrate status

2. Shadow DB에서 테스트 (권장):

NODE_ENV=production pnpm sonamu migrate shadow-test

3. 실제 DB에 적용:

NODE_ENV=production pnpm sonamu migrate run

4. 롤백 (필요시):

NODE_ENV=production pnpm sonamu migrate rollback

데이터베이스 백업을 설정하려면?

PostgreSQL 백업:

# 수동 백업
pg_dump -h prod-db.example.com -U postgres -d sonamu_prod > backup.sql

# 압축 백업
pg_dump -h prod-db.example.com -U postgres -d sonamu_prod | gzip > backup.sql.gz

# 복원
gunzip < backup.sql.gz | psql -h prod-db.example.com -U postgres -d sonamu_prod

자동 백업 (Cron):

# crontab -e
# 매일 새벽 2시 백업
0 2 * * * /usr/bin/pg_dump -h prod-db.example.com -U postgres sonamu_prod | gzip > /backups/sonamu_$(date +\%Y\%m\%d).sql.gz

# 30일 이상 된 백업 삭제
0 3 * * * find /backups -name "sonamu_*.sql.gz" -mtime +30 -delete

모니터링과 로깅

로그를 설정하려면?

Sonamu는 LogTape 기반의 구조화된 로깅을 제공합니다. sonamu.config.ts의 logging 옵션으로 설정합니다:

// sonamu.config.ts
import { defineConfig } from "sonamu";

export default defineConfig({
  // ...
  logging: {
    sinks: {
      console: { type: "console" },
      file: { type: "file", path: "logs/app.log" },
    },
    filters: {
      all: { sinkId: "console", level: "info" },
      fileAll: { sinkId: "file", level: "warning" },
    },
  },
});

로그 사용:

class UserModelClass extends BaseModelClass {
  @api({ httpMethod: "POST" })
  async createUser(params: UserSaveParams): Promise<User> {
    this.logger.info("Creating user", { email: params.email });

    try {
      const user = await this.save(params);
      this.logger.info("User created", { userId: user.id });
      return user;
    } catch (error) {
      this.logger.error("Failed to create user", { error, params });
      throw error;
    }
  }
}

자세한 설정은 LogTape 설정을 참고하세요.

헬스체크 엔드포인트를 만들려면?

// health.frame.ts
import { BaseFrameClass, api } from "sonamu";

class HealthFrameClass extends BaseFrameClass {
  @api({ httpMethod: "GET" }) // guards 생략 = 공개 API
  async healthCheck(): Promise<{
    status: string;
    timestamp: Date;
    uptime: number;
    database: string;
  }> {
    // DB 연결 확인
    let databaseStatus = "ok";
    try {
      await this.getPuri("r").raw("SELECT 1");
    } catch (error) {
      databaseStatus = "error";
    }

    return {
      status: databaseStatus === "ok" ? "healthy" : "unhealthy",
      timestamp: new Date(),
      uptime: process.uptime(),
      database: databaseStatus,
    };
  }
}

export const HealthFrame = new HealthFrameClass();

에러 모니터링을 설정하려면?

Sentry 통합:

// sonamu.config.ts
import * as Sentry from "@sentry/node";
import { defineConfig } from "sonamu";

if (process.env.NODE_ENV === "production") {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV,
    tracesSampleRate: 1.0,
  });
}

export default defineConfig({
  // ...
  server: {
    // ...
    lifecycle: {
      async onStart() {
        console.log("Server started");
      },
      async onError(error: Error) {
        if (process.env.NODE_ENV === "production") {
          Sentry.captureException(error);
        }
      },
    },
  },
});

성능 최적화

프로덕션 성능을 최적화하려면?

1. Connection Pool 설정:

import { defineConfig } from "sonamu";

export default defineConfig({
  // ...
  database: {
    database: "pg",
    defaultOptions: {
      pool: {
        min: 2,
        max: 10,
      },
    },
  },
});

2. 캐싱 활성화:

import { defineConfig } from "sonamu";
import { drivers, store } from "sonamu/cache";

export default defineConfig({
  // ...
  server: {
    // ...
    cache: {
      default: "redis",
      stores: {
        redis: store().useL1Layer(
          drivers.redis({
            connection: {
              host: process.env.REDIS_HOST,
              port: Number(process.env.REDIS_PORT) || 6379,
            },
          }),
        ),
      },
    },
  },
});

3. 압축 활성화:

import { defineConfig } from "sonamu";

export default defineConfig({
  // ...
  server: {
    // ...
    plugins: {
      compress: true,
    },
  },
});

정적 파일 캐싱을 설정하려면?

Nginx 설정:

server {
  # ...

  location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

Docker

Docker로 배포하려면?

Dockerfile 생성:

# api/Dockerfile
FROM node:18-alpine

WORKDIR /app

# pnpm 설치
RUN npm install -g pnpm

# Dependencies 복사 및 설치
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 소스 코드 복사
COPY . .

# 빌드
RUN pnpm build

# 프로덕션 모드로 실행
ENV NODE_ENV=production
EXPOSE 34900

CMD ["node", "dist/index.js"]

docker-compose.yml:

version: "3.8"

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: sonamu_production
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${SONAMU_DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  api:
    build: ./api
    environment:
      NODE_ENV: production
      SONAMU_DB_HOST: postgres
      SONAMU_DB_PORT: 5432
      SONAMU_DB_NAME: sonamu_production
      SONAMU_DB_USER: postgres
      SONAMU_DB_PASSWORD: ${SONAMU_DB_PASSWORD}
      REDIS_HOST: redis
      REDIS_PORT: 6379
    ports:
      - "34900:34900"
    depends_on:
      - postgres
      - redis

  web:
    build: ./web
    ports:
      - "80:80"
    depends_on:
      - api

volumes:
  postgres_data:

실행:

docker-compose up -d

CI/CD

GitHub Actions로 자동 배포를 설정하려면?

.github/workflows/deploy.yml:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install pnpm
        run: npm install -g pnpm

      - name: Install dependencies
        run: pnpm install

      - name: Run tests
        run: pnpm test

      - name: Build
        run: pnpm build

      - name: Deploy to server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/sonamu
            git pull
            pnpm install
            pnpm build
            pm2 restart sonamu-api

보안

HTTPS를 설정하려면?

Let’s Encrypt + Nginx:

# Certbot 설치
sudo apt install certbot python3-certbot-nginx

# 인증서 발급
sudo certbot --nginx -d example.com -d www.example.com

# 자동 갱신 테스트
sudo certbot renew --dry-run

Nginx HTTPS 설정:

server {
  listen 443 ssl http2;
  server_name example.com;

  ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_ciphers HIGH:!aNULL:!MD5;

  # ...
}

# HTTP to HTTPS 리다이렉트
server {
  listen 80;
  server_name example.com;
  return 301 https://$server_name$request_uri;
}

CORS를 설정하려면?

// sonamu.config.ts
import { defineConfig } from "sonamu";

export default defineConfig({
  // ...
  server: {
    // ...
    plugins: {
      cors: {
        origin: process.env.CORS_ORIGIN || "http://localhost:5173",
        credentials: true,
        methods: ["GET", "POST", "PUT", "DELETE", "PATCH"],
      },
    },
  },
});

Rate Limiting을 설정하려면?

import rateLimit from "@fastify/rate-limit";
import { defineConfig } from "sonamu";

export default defineConfig({
  // ...
  server: {
    // ...
    plugins: {
      custom: async (server) => {
        await server.register(rateLimit, {
          max: 100,
          timeWindow: "1 minute",
        });
      },
    },
  },
});

Best Practices

프로덕션 체크리스트

보안:성능:모니터링:

헬스체크 엔드포인트
에러 모니터링 (Sentry)
로그 수집 (LogTape)
DB 백업 자동화

배포:

프로덕션 환경 변수 설정
마이그레이션 테스트 (Shadow DB)
CI/CD 파이프라인
롤백 계획

​빌드와 배포

​환경 변수

​데이터베이스

​모니터링과 로깅

​성능 최적화

​Docker

​CI/CD

​보안

​Best Practices

​관련 문서

빌드와 배포

환경 변수

데이터베이스

모니터링과 로깅

성능 최적화

Docker

CI/CD

보안

Best Practices

관련 문서