zellyy-finance/DEPLOYMENT.md

Zellyy Finance - Vercel 배포 가이드

개요

이 문서는 Zellyy Finance 프로젝트를 Vercel에서 자동 배포하는 방법에 대한 가이드입니다.

사전 준비사항

• GitHub 저장소가 생성되어 있어야 함
• Vercel 계정이 필요함
• Appwrite 프로젝트가 설정되어 있어야 함

1. Vercel 프로젝트 생성 및 연결

1.1 Vercel 계정 로그인

1. Vercel 웹사이트에 접속
2. GitHub 계정으로 로그인
3. "New Project" 버튼 클릭

1.2 GitHub 저장소 연결

1. Import Git Repository 섹션에서 GitHub 선택
2. zellyy-finance 저장소 선택
3. "Import" 버튼 클릭

1.3 프로젝트 설정

• Framework Preset: Vite (자동 감지됨)
• Root Directory: . (기본값)
• Build Command: npm run build (자동 설정됨)
• Output Directory: dist (자동 설정됨)
• Install Command: npm install (자동 설정됨)

2. 환경 변수 설정

2.1 필수 환경 변수

Vercel 대시보드의 Settings > Environment Variables에서 다음 변수들을 설정:

프로덕션 환경 (Production)

VITE_APPWRITE_ENDPOINT=https://your-appwrite-endpoint/v1
VITE_APPWRITE_PROJECT_ID=your-production-project-id
VITE_APPWRITE_DATABASE_ID=default
VITE_APPWRITE_TRANSACTIONS_COLLECTION_ID=transactions
VITE_APPWRITE_API_KEY=your-appwrite-api-key
VITE_DISABLE_LOVABLE_BANNER=true

프리뷰 환경 (Preview)

VITE_APPWRITE_ENDPOINT=https://your-appwrite-endpoint/v1
VITE_APPWRITE_PROJECT_ID=your-preview-project-id
VITE_APPWRITE_DATABASE_ID=default
VITE_APPWRITE_TRANSACTIONS_COLLECTION_ID=transactions
VITE_APPWRITE_API_KEY=your-appwrite-api-key
VITE_DISABLE_LOVABLE_BANNER=true

2.2 환경별 브랜치 매핑

• Production: main 브랜치
• Preview: develop 브랜치 및 PR 브랜치들

3. 배포 설정 최적화

3.1 Node.js 버전 설정

.nvmrc 파일에서 Node.js 버전 지정:

18.x

3.2 빌드 최적화

• 코드 스플리팅이 이미 구현되어 있음 (React.lazy)
• 정적 자산 캐싱 설정 (vercel.json에 포함됨)
• 브라우저 호환성 최적화

3.3 보안 헤더 설정

vercel.json에 다음 보안 헤더들이 설정됨:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 1; mode=block
• Referrer-Policy: strict-origin-when-cross-origin

4. 자동 배포 워크플로우

4.1 Production 배포

1. main 브랜치에 코드 푸시
2. Vercel이 자동으로 빌드 시작
3. 빌드 성공 시 Production 환경에 배포
4. 실패 시 이전 버전 유지

4.2 Preview 배포

1. develop 브랜치 또는 PR 생성
2. 자동으로 Preview 배포 생성
3. 고유한 URL로 미리보기 제공
4. PR에 배포 링크 자동 코멘트

4.3 배포 상태 모니터링

• Vercel 대시보드에서 실시간 빌드 로그 확인
• GitHub PR에 배포 상태 자동 업데이트
• 배포 실패 시 슬랙/이메일 알림 (선택사항)

5. 도메인 설정

5.1 커스텀 도메인 연결

1. Vercel 프로젝트 Settings > Domains
2. 원하는 도메인 입력
3. DNS 설정 업데이트 (CNAME 또는 A 레코드)
4. SSL 인증서 자동 설정

5.2 도메인 예시

• Production: zellyy-finance.vercel.app 또는 your-custom-domain.com
• Preview: zellyy-finance-git-develop-username.vercel.app

6. 성능 최적화

6.1 분석 도구

• Vercel Analytics 활성화
• Core Web Vitals 모니터링
• 번들 크기 분석

6.2 최적화된 설정

• 이미지 최적화 (Vercel Image Optimization)
• 정적 자산 CDN 캐싱
• 압축 및 minification 자동 적용

7. 트러블슈팅

7.1 일반적인 문제들

• 빌드 실패: Node.js 버전 호환성 확인
• 환경변수 오류: Vercel 대시보드에서 변수 설정 확인
• 라우팅 오류: SPA rewrites 설정 확인 (vercel.json)

7.2 디버깅 팁

• Vercel 빌드 로그 자세히 확인
• 로컬에서 npm run build 테스트
• 환경변수 값이 올바른지 확인

8. 추가 기능

8.1 Branch Protection

• main 브랜치에 대한 보호 규칙 설정
• PR 리뷰 필수화
• 배포 전 테스트 통과 필수

8.2 모니터링 및 알림

• 배포 상태 Slack 알림
• 성능 저하 감지 알림
• 에러 추적 (Sentry 연동 가능)

참고 자료

• Vercel 공식 문서
• Vite 배포 가이드
• React Router SPA 설정