nextjs-deployment은(는) 무엇을 하나요?
Next.js 애플리케이션을 프로덕션에 배포하기 위한 포괄적인 패턴을 제공합니다. Docker 컨테이너 구성, GitHub Actions CI/CD 파이프라인 설정, 환경 변수 관리, 프리뷰 배포 구현, 또는 Next.js 애플리케이션 모니터링 및 로깅 설정 시 사용하세요. 독립형 출력, 다단계 Docker 빌드, 헬스 체크, OpenTelemetry 계측, 프로덕션 모범 사례를 다룹니다.
주요 내용
- 독립형 출력: Next.js의
output: 'standalone'모드를 활용하여 최소한의 의존성으로 배포 가능한 애플리케이션 번들 생성 - 다단계 Docker 빌드: 빌드 단계와 실행 단계를 분리하여 이미지 크기 최적화 및 보안 강화
- 헬스 체크: 컨테이너 오케스트레이션 환경에서 애플리케이션 상태를 지속적으로 모니터링
- OpenTelemetry 계측: 분산 추적 및 성능 메트릭 수집을 통한 애플리케이션 성능 모니터링
- 환경 변수 관리: 런타임 환경 변수를 안전하게 주입하고 관리하는 방법
- GitHub Actions CI/CD: 자동화된 테스트, 빌드, 배포 파이프라인 구성
- 프리뷰 배포: PR 기반 프리뷰 환경을 통한 변경 사항 사전 검증
사용 예시
Dockerfile 예시
# 빌드 단계
FROM node:18-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci
COPY . .
RUN npm run build
# 실행 단계
FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV production
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
EXPOSE 3000
ENV PORT 3000
CMD ["node", "server.js"]
docker-compose.yml 예시
version: '3.8'
services:
nextjs:
build:
context: .
dockerfile: Dockerfile
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DATABASE_URL=${DATABASE_URL}
- OPENAI_API_KEY=${OPENAI_API_KEY}
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
GitHub Actions 워크플로우 예시
name: Deploy Next.js
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm run test
- name: Build application
run: npm run build
env:
NEXT_PUBLIC_API_URL: ${{ secrets.NEXT_PUBLIC_API_URL }}
- name: Build Docker image
run: |
docker build -t myapp:latest .
docker tag myapp:latest myregistry.azurecr.io/myapp:${{ github.sha }}
- name: Deploy to production
run: |
# 배포 스크립트 실행 (예: SSH, Kubernetes, 등)
echo "Deploying to production..."
환경 변수 구성
| 변수명 | 설명 | 필수 여부 |
|---|---|---|
DATABASE_URL | 데이터베이스 연결 문자열 | 예 |
OPENAI_API_KEY | OpenAI API 키 | 아니오 (해당 기능 사용 시) |
NEXT_PUBLIC_API_URL | 클라이언트 측 API URL | 예 |
SENTRY_DSN | Sentry 오류 추적 DSN | 아니오 |
OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry 수집기 엔드포인트 | 아니오 |
모니터링 및 로깅
OpenTelemetry 설정
// instrumentation.ts
import { registerOTel } from '@vercel/otel';
export function register() {
registerOTel({
serviceName: 'nextjs-app',
});
}
헬스 체크 엔드포인트
// app/api/health/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
return NextResponse.json({
status: 'healthy',
timestamp: new Date().toISOString(),
uptime: process.uptime(),
});
}
프로덕션 모범 사례
- 보안: 비밀 환경 변수는 Secrets Manager를 통해 관리
- 성능: CDN 캐싱, 이미지 최적화, 정적 페이지 사전 생성 활용
- 확장성: 수평 확장을 고려한 Stateless 애플리케이션 설계
- 모니터링: APM 도구와 연계하여 실시간 성능 모니터링
- 백업: 정기적인 데이터베이스 백업 및 복구 계획 수립