Rails 8 Monigon SaaS Boilerplate 로컬 환경 설정 및 Stripe 연동

이 가이드는 Monigon Rails 8 SaaS boilerplate 애플리케이션을 로컬 환경에 설정하고 Stripe 결제 시스템을 연동하는 과정을 단계별로 설명합니다.

1. Monigon 애플리케이션 초기 설정

• 저장소 클론 및 의존성 설치: GitHub 저장소를 로컬에 클론한 후, bundle 명령어를 실행하여 필요한 Gem들을 설치합니다.

• 데이터베이스 설정: Rails DB create, Rails DB migrate 명령어를 통해 데이터베이스를 생성하고 마이그레이션합니다. 기존 데이터가 있다면 Rails DB seed:replant를 사용하여 초기 데이터를 다시 심을 수 있습니다.

• 서버 실행 및 확인: bin/dev 명령어로 로컬 서버를 실행하고, 기본 사용자(예: example@example.com, password)로 로그인하여 애플리케이션의 기본 기능(조직 관리, 대시보드 등)을 확인합니다. 초기 상태에서는 결제 기능이 비활성화되어 있습니다.

2. Stripe API 키 및 웹훅 설정

• Stripe 계정 설정: 새로운 Stripe 계정을 생성하거나 기존 계정을 활용하여 개발자 대시보드에서 API 키를 확인합니다.

• Rails credentials 설정:
  • rails credentials edit 명령어를 사용하여 Rails credentials 파일을 엽니다. 저장소를 새로 클론한 경우 master.key 부재로 인한 암호화 해제 오류가 발생할 수 있습니다. 이 경우 기존 master.key와 credentials 파일을 삭제한 후 다시 rails credentials edit를 실행하여 새로운 키를 생성하고 빈 credentials 파일을 엽니다.
  • Stripe 대시보드에서 Publishable key와 Secret key를 복사하여 credentials 파일의 stripe_publishable_key와 stripe_secret_key에 각각 붙여넣습니다.
• Stripe 웹훅 설정 및 테스트:
  • Stripe CLI를 설치하고 stripe login을 통해 계정에 연결합니다.
  • 별도의 터미널에서 stripe listen --forward-to localhost:3000/hook/stripe 명령어를 실행하여 로컬 웹훅 리스너를 시작합니다.
  • 다른 터미널에서 stripe trigger payment_intent.succeeded와 같은 테스트 이벤트를 발생시켜 웹훅이 정상적으로 수신되는지 확인합니다.
  • 웹훅 서명 오류 해결: 초기 테스트 시 no signatures found matching the expected signature for payload 오류가 발생할 수 있습니다. 이는 웹훅 서명 시크릿이 credentials에 누락되었기 때문입니다. Stripe 대시보드의 ‘개발자’ -> ‘웹훅’ 섹션에서 엔드포인트를 추가하고 Signing secret을 복사하여 credentials 파일의 stripe_webhook_secret에 추가합니다. credentials 업데이트 후에는 Rails 서버를 재시작해야 합니다.

3. Stripe 제품 및 가격 연동

• Stripe 제품 및 가격 생성: Stripe 대시보드에서 새로운 제품(예: Monigon Pro)을 생성하고, 월간 및 연간 플랜에 대한 가격(예: 월 50유로, 연 500유로)을 설정합니다. 연간 플랜의 경우 할인율(예: 2개월 무료)을 고려할 수 있습니다.

• settings.yml 업데이트: 애플리케이션의 config/settings.yml 파일을 열어 Stripe 가격 ID와 표시 값을 업데이트합니다. Stripe에서 생성한 각 가격의 ID를 복사하여 settings.yml의 stripe_prices_monthly_id 및 stripe_prices_yearly_id에 개발 및 프로덕션 환경 모두에 적용합니다.

• 구독 테스트: 애플리케이션을 새로고침하면 업데이트된 가격 정보가 표시됩니다. 특정 조직을 선택하여 월간 또는 연간 플랜에 구독하고, 테스트용 카드 정보를 입력하여 결제를 완료합니다. 웹훅이 정상적으로 처리되면 조직의 구독 상태가 ‘활성’으로 변경되고 다음 청구일이 표시되는 것을 확인할 수 있습니다.