Stripe-Stack 프로젝트 배포 가이드: 개발부터 운영 환경까지 전 과정 분석
【무료 다운로드 링크】stripe-stack는 사용자 구독, 인증 및 테스트를 통합한 Stripe 중심의 Remix 스택입니다. Prisma ORM 기반으로 제작되었으며, Fly.io에 배포됩니다. 프로젝트 주소: https://gitcode.com/gh_mirrors/st/stripe-stack
서론
Stripe-Stack는 Remix 프레임워크를 기반으로 한 SaaS 애플리케이션 템플릿으로, Stripe 결제 시스템과 현대적인 개발 도구 체인을 통합하고 있습니다. 본 문서에서는 Stripe-Stack 프로젝트를 로컬 개발 환경에서 Fly.io 운영 환경으로 배포하는 방법을 자세히 설명하여, 개발자가 전체 배포 절차와 핵심 설정 요소를 이해할 수 있도록 돕습니다.
배포 전 준비사항
배포 작업을 시작하기 전, 몇 가지 필수 준비 작업이 필요합니다:
1. 데이터베이스 마이그레이션 처리
Prisma 마이그레이션 파일이 완비되어 있어야 하며, 이는 배포 과정에서 매우 중요합니다. 개발 환경의 Stripe 테스트 데이터는 운영 환경 데이터에 영향을 주지 않도록 반드시 정리해야 합니다.
2. Stripe 웹훅 운영 환경 설정
웹훅은 Stripe와 애플리케이션 간 통신의 핵심 채널이며, 올바른 설정이 필수적입니다:
- Stripe 대시보드의 웹훅 관리 페이지로 이동합니다.
- 새 웹훅 엔드포인트를 생성합니다.
- URL 입력란에 배포 예정 애플리케이션 주소를 입력합니다 (예: https://your-app.fly.dev/api/webhook).
- 최신 Stripe API 버전을 선택합니다.
- 다음 주요 이벤트들을 구독하도록 설정합니다:
- checkout.session.completed (결제 세션 완료)
- customer.subscription.updated (사용자 구독 업데이트)
- customer.subscription.deleted (사용자 구독 취소)
- 생성된 서명 키(Signing Secret)를 얻습니다.
- 이 키를
.env파일의STRIPE_WEBHOOK_ENDPOINT변수로 설정합니다.
전문 팁: 웹훅 설정의 정확성은 결제 프로세스의 신뢰성을 좌우하므로, 배포 전 ngrok 등의 도구를 활용해 로컬에서 충분히 테스트하는 것을 권장합니다.
Fly.io 배포 상세 단계
1. 환경 설정
Fly.io 명령줄 도구를 설치하고 인증을 완료해야 합니다:
# 신규 사용자 등록
fly auth signup
# 기존 계정 로그인
fly auth login
2. 애플리케이션 초기화
다음 명령어를 실행하여 배포 절차를 시작합니다:
fly launch
이 명령어는 프로젝트 설정을 자동으로 감지하고 초기화 과정을 안내합니다. Fly CLI의 템플릿 이름이 프로젝트 내 fly.toml 파일과 일치하는지 확인하세요.
3. 환경 변수 설정
Fly.io는 secrets를 통해 민감한 환경 변수를 관리하며, 이는 애플리케이션 보안을 유지하는 데 중요한 역할을 합니다:
fly secrets set SESSION_SECRET="" \
ENCRYPTION_SECRET="" \
PROD_HOST_URL="https://my-app.fly.dev" \
RESEND_API_KEY="" \
STRIPE_SECRET_KEY="" \
STRIPE_WEBHOOK_ENDPOINT="" \
HONEYPOT_ENCRYPTION_SEED=""
중요 사항:
PROD_HOST_URL에는 프로토콜과 도메인 전체가 포함되어야 합니다.- 처음 배포 시 모든 변수를 설정할 필요 없으며, GitHub 관련 설정은 나중에 추가 가능합니다.
4. 데이터베이스 시드 처리
처음 배포 시 자동으로 데이터베이스 시드 스크립트가 실행되며, 이후 해당 기능은 비활성화해야 합니다:
- Fly 애플리케이션 로그를 확인하여 시드 스크립트 실행 여부를 확인합니다.
docker-entrypoint.js파일에서 시드 스크립트 실행 코드를 주석 처리합니다.- 애플리케이션을 다시 배포합니다.
// 처음 배포 후 해당 줄 주석 처리
// await exec('npx prisma db seed')
5. 배포 완료
최종 배포 명령어를 실행하고 확인합니다:
fly deploy
배포가 완료되면 https://your-app.fly.dev에 접속하여 운영 환경 애플리케이션을 확인할 수 있습니다.
배포 후 유지보수
애플리케이션 업데이트 절차
코드 변경 후에는 단순히 아래 명령어만 실행하면 됩니다:
fly deploy
운영 환경 모니터링 권장사항
본 문서에서는 CI/CD 파이프라인 구성은 다루지 않지만, 다음과 같은 조치를 권장합니다:
- Fly.io의 자동 상태 검사 설정
- 로그 모니터링 및 알림 구성
- 데이터베이스 백업 상태 정기 점검
일반적인 문제 해결
- 웹훅이 작동하지 않을 경우
- 서명 키가 정확한지 확인합니다.
- 운영 환경 URL이 Stripe 설정과 일치하는지 점검합니다.
- 네트워크 설정이 요청을 차단하지 않는지 확인합니다.
- 데이터베이스 연결 문제
- Fly.io의 Postgres 애드온 상태를 점검합니다.
- 데이터베이스 연결 문자열 설정을 확인합니다.
- 결제 프로세스 이상
- Stripe API 키가 적절한 환경(생산/테스트)에 맞게 설정되었는지 확인합니다.
- 이벤트 리스너 설정이 완전한지 점검합니다.
결론
본 문서를 따라 진행하면 Stripe-Stack 프로젝트를 운영 환경에 성공적으로 배포할 수 있습니다. 이 템플릿은 사용자 인증, 구독 관리, 결제 처리 등 SaaS 애플리케이션의 핵심 기능을 모두 포함한 완전한 아키텍처를 제공합니다. 배포는 시작점일 뿐이며, Fly.io의 확장 기능과 성능 최적화 방안을 탐색하여 더 견고한 운영 환경 애플리케이션을 구축하는 것을 권장합니다.
【무료 다운로드 링크】stripe-stack는 사용자 구독, 인증 및 테스트를 통합한 Stripe 중심의 Remix 스택입니다. Prisma ORM 기반으로 제작되었으며, Fly.io에 배포됩니다. 프로젝트 주소: https://gitcode.com/gh_mirrors/st/stripe-stack