Aller au contenu principal
HeartCoHeartCo/Documentation
FREN

Deployment Guide — HeartCo

Complete checklist to deploy HeartCo to production on Vercel with Supabase, Stripe, and supporting services.

Table of Contents

Prerequisites

  • GitHub repository set up and pushed
  • Node.js 22 LTS
  • Vercel account
  • Supabase account (PostgreSQL)
  • Stripe account
  • Resend account (for transactional emails)
  • Upstash Redis account (optional, for caching)
  • Sentry account (optional, for error tracking)

1. Vercel Deployment

Import Repository

  1. Go to vercel.com/new
  2. Select "Import Git Repository" → choose your HeartCo repo
  3. Click Import

Configure Build Settings

Under Settings > Build & Development Settings:

  • Build Command: (Use default)
  • Output Directory: (Use default — Next.js auto-detected)
  • Install Command: pnpm install

Under Settings > Functions:

Set environment variable for Node memory:

NODE_OPTIONS=--max-old-space-size=7168

Runtime: Node.js 22.x

Set Environment Variables

In Settings > Environment Variables, add all variables from .env.example:

# Database (from Supabase, see Step 2)
DATABASE_URL=postgresql://user:password@db.supabase.co/postgres
DIRECT_URL=postgresql://user:password@db.supabase.co/postgres

# Auth
NEXTAUTH_URL=https://yourdomain.com
AUTH_SECRET=<generate-with-openssl-rand-base64-32>

# Stripe (see Step 3)
STRIPE_SECRET_KEY=sk_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Resend (see Step 4)
RESEND_API_KEY=re_...

# Redis (optional, see Step 5)
UPSTASH_REDIS_REST_URL=https://xxxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=AXxxxx

# Sentry (optional, see Step 6)
SENTRY_DSN=https://...@sentry.io/...

# Branding
NEXT_PUBLIC_APP_NAME=HeartCo
NEXT_PUBLIC_APP_DOMAIN=yourdomain.com
NEXT_PUBLIC_APP_URL=https://yourdomain.com

Deploy

Click Deploy. Vercel will build and deploy automatically.

Custom Domain

  1. Go to Settings > Domains
  2. Add your custom domain (e.g., app.yourdomain.com)
  3. Follow DNS configuration steps (CNAME record)
  4. SSL is auto-provisioned via Let's Encrypt

2. Supabase — PostgreSQL Database

Create Project

  1. Go to supabase.com
  2. Click New Project
  3. Enter project name, password, region (closest to your users)
  4. Click Create new project (wait 2-3 minutes)

Get Connection Strings

In Settings > Database > Connection strings:

  • Copy URI → set as DATABASE_URL in Vercel
  • Copy URI with ?schema=public → set as DIRECT_URL

Example:

postgresql://postgres:password@db.supabase.co:5432/postgres

Run Migrations

In your local environment:

# Link to Supabase
pnpm dlx supabase link --project-ref <YOUR_PROJECT_ID>
 
# Run all pending migrations
npx prisma migrate deploy
 
# Verify
npx prisma studio

Enable Extensions (if needed)

In Supabase Dashboard → SQL Editor, run:

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pgcrypto";

Connection Pooling (Supavisor)

For serverless deployments, enable pooling:

  1. Settings > Database > Connection pooling
  2. Mode: Transaction (default)
  3. Pool size: 3-5 connections
  4. Use the Pooling Connection String in your serverless environment

3. Stripe Setup

Create Products & Prices

In Stripe Dashboard:

  1. Products → Create product

For each plan (FREE, STARTER, PRO, BUSINESS, ENTERPRISE):

  • Create product with name matching src/lib/config/branding.ts
  • Add 2 prices: Monthly and Annual
  • Set features via product metadata

Example pricing structure:

STARTER:
  - Monthly: $29/month (Price ID: price_starter_monthly)
  - Annual: $290/year (Price ID: price_starter_annual)

PRO:
  - Monthly: $79/month (Price ID: price_pro_monthly)
  - Annual: $790/year (Price ID: price_pro_annual)

Configure Webhooks

  1. Developers > Webhooks → Add endpoint

  2. Endpoint URL: https://yourdomain.com/api/stripe/webhook

  3. Events to listen:

    • checkout.session.completed
    • invoice.paid
    • invoice.payment_failed
    • customer.subscription.updated
    • customer.subscription.deleted

  4. Copy Signing secret → set as STRIPE_WEBHOOK_SECRET in Vercel

Get API Keys

In Settings > API keys:

  • Copy Secret key → set as STRIPE_SECRET_KEY
  • Copy Publishable key → set as STRIPE_PUBLISHABLE_KEY

Customer Portal

  1. Settings > Billing portal settings → Customize
  2. Enable:
    • Switch plans
    • Cancel subscriptions
    • Update payment methods
  3. Save customization

4. Resend — Transactional Email

Create API Key

  1. Go to resend.com
  2. API Keys → Create
  3. Copy → set as RESEND_API_KEY in Vercel

Verify Domain

For custom domain emails (e.g., noreply@yourdomain.com):

  1. Domains → Add domain
  2. Add your custom domain
  3. Add DNS records (CNAME + DKIM)
  4. Verify once records propagate (10-30 min)

5. Redis (Upstash) — Optional

Create Database

  1. Go to upstash.com
  2. Console > Create database
  3. Region: closest to your Vercel deployment
  4. Select Single-Zone

Get Connection String

  1. Copy the REST API URL → set as UPSTASH_REDIS_REST_URL
  2. Copy the REST token → set as UPSTASH_REDIS_REST_TOKEN
  3. Keep both secret — used for RBAC cache, rate limiting, realtime

6. Sentry — Error Tracking (Optional)

Create Project

  1. Go to sentry.io
  2. Projects → Create Project
  3. Platform: Next.js
  4. Alert rule: (keep defaults)

Get DSN

Copy DSN → set as SENTRY_DSN in Vercel

The app automatically captures errors via the Sentry SDK.

Pre-Launch Checklist

Before going live, verify:

  • All environment variables set in Vercel
  • Supabase migrations deployed (npx prisma migrate deploy)
  • Stripe test mode active (use test keys first)
  • Stripe webhooks configured and tested
  • Resend domain verified (if using custom domain)
  • Database backup configured (Supabase → Backups)
  • Email templates tested
  • Authentication flow tested
  • Stripe products match frontend pricing
  • Custom domain DNS propagated
  • SSL certificate valid (Vercel auto-manages)
  • Sentry alerts configured (if enabled)
  • Rate limiting tested
  • Monitoring/logging in place

Launch to Production

1. Test Payment Flow

  1. Switch Stripe to Live mode
  2. Run test payment with real card (will charge $1, auto-refunded)
  3. Verify webhook delivery in Stripe Dashboard

2. Enable Production in Vercel

  1. Go to Settings > Git > Production Branch
  2. Set to main
  3. All pushes to main auto-deploy

3. Monitor First 24 Hours

  • Watch Sentry for errors
  • Monitor Stripe for failed payments
  • Check database performance
  • Review logs for anomalies

4. Communication

  • Announce launch to early users
  • Provide support contact (SUPPORT_EMAIL)
  • Monitor customer feedback

Scaling Considerations

As you grow:

  1. Database: Add read replicas in Supabase
  2. CDN: Enable Vercel Edge Network for faster delivery
  3. Redis: Scale connections for high-traffic features
  4. API: Monitor tRPC performance; consider caching layer
  5. Email: Monitor Resend quota; consider backup provider

Troubleshooting

Database Connection Timeout

  • Check DIRECT_URL has correct credentials
  • Verify Supabase IP whitelist (should be open for Vercel)
  • Enable connection pooling (Supisor) for serverless

Stripe Webhooks Not Firing

  • Verify endpoint URL is public (not localhost)
  • Check STRIPE_WEBHOOK_SECRET matches Stripe Dashboard
  • Test with Stripe CLI: stripe listen --forward-to localhost:3000/api/stripe/webhook

Resend Emails Not Sending

  • Verify domain is verified (if using custom domain)
  • Check RESEND_API_KEY is correct
  • View email logs in Resend Dashboard

Sentry Not Capturing Errors

  • Verify SENTRY_DSN is set
  • Check that SENTRY_ENVIRONMENT matches deployment
  • Ensure errors aren't silently caught without re-throwing

Contact & Support