zellyy-finance/docs/SUPABASE_ONPREM_MIGRATION_PLAN.md

Supabase Cloud → On-Premise Migration Plan

이 문서에는 기존 Supabase Cloud 프로젝트를 On-Premise Self-Host 환경으로 이전하기 위한 단계별 절차를 정리합니다.

1. 개요

• 목적: 클라우드 종속성을 제거하고 자체 운영 가능하도록 Supabase 스택을 온프레미스 환경에 배포
• 범위: 인증(Gotrue), 실시간(Realtime), 스토리지(Storage), 데이터베이스(Postgres)

2. 사전 준비

1. 현재 환경 문서화
   • 프로젝트 구조, 스키마, RLS 규칙, 함수, 트리거 등
   • 사용 중인 Supabase CLI/SDK 버전 및 환경 변수 목록
2. 인프라 준비
   • Docker 엔진 또는 Kubernetes 클러스터
   • 도메인, TLS 인증서 준비
   • 최소 요구 사양 확인 (CPU, 메모리, 디스크)
3. 백업 계획 수립
   • Cloud DB Dump 스케줄링 방법
   • 백업 보관 위치 및 암호화 방침

3. On-Premise Supabase Self-Host 배포

1. Supabase CLI 설치

   npm install -g supabase
   

2. 초기화 및 컨테이너 실행

   supabase init    # 프로젝트 디렉토리에 구성 파일 작성
   supabase start   # Postgres, Kong, Realtime, GoTrue, Storage 컨테이너 실행
   

3. 버전 호환성 확인
   • supabase version으로 CLI, API, DB 버전 일치 여부 점검

4. 데이터 마이그레이션

1. Cloud DB Dump

   supabase db dump --project-ref <PROJECT_REF> --file cloud_dump.sql
   

2. On-Premise DB Restore

   supabase db restore --file cloud_dump.sql
   

3. 데이터 무결성 검증
   • 주요 테이블 row 수 체크
   • RLS 규칙·함수 정상 동작 여부 테스트

5. 애플리케이션 구성 변경

1. 환경 변수 업데이트

   SUPABASE_URL=http://<ONPREM_HOST>:8000
   SUPABASE_ANON_KEY=<새_ANON_KEY>
   SUPABASE_SERVICE_KEY=<새_SERVICE_KEY>
   

2. SDK 초기화 점검
   • client = createClient(SUPABASE_URL, SUPABASE_ANON_KEY) 정상 연결 확인

6. 테스트 및 검증

1. 로컬 개발서버 테스트
   • 프론트·백엔드 실행 후 CRUD 기능 확인
2. 스테이징 환경 배포
   • Blue-Green 또는 Canary 배포로 트래픽 분할
   • 모니터링(로그, 메트릭) 이상 유무 확인

7. 프로덕션 전환

1. DNS 레코드 변경 또는 로드밸런서 설정
2. SSL/TLS 인증서 적용
3. 전환 후 롤백 플랜 준비

8. 롤백 계획

• 문제가 발생 시 이전 Cloud 인스턴스로 트래픽 리디렉션
• 신규 데이터 백업 및 차분 마이그레이션

9. 모니터링 및 운영

• 백그라운드 컨테이너 상태 감시 (Prometheus, Grafana)
• 정기 백업·복원 테스트 자동화
• 보안 패치 및 버전 업데이트 정책 수립

---

문서 위치: docs/SUPABASE_ONPREM_MIGRATION_PLAN.md