Documentation

PRE_DEPLOYMENT_CHECKLIST

docs/PRE_DEPLOYMENT_CHECKLIST.md

Pre-Deployment Verification Checklist

Last Updated: 2026-02-17 Purpose: Comprehensive checklist to ensure successful deployment without schema drift, authentication issues, or onboarding failures

Critical Verification Steps

1. Database Schema Verification

  • Run health check locally

    npm run db:health
    

    Expected: All 6-7 checks pass (Organization table optional)

  • Verify authId column exists

    npm run db:verify-authid
    

    Expected: Column exists with type TEXT, nullable: YES, unique index present

  • Check migration status

    npx prisma migrate status
    

    Expected: "Database schema is up to date!" or list of applied migrations

  • Verify no pending migrations

    npx prisma migrate status | grep "pending"
    

    Expected: No output (no pending migrations)

2. Environment Variables Verification

  • Verify all critical environment variables are set in Vercel

    Go to Vercel Dashboard → Your Project → Settings → Environment Variables

    Required for Production:

    • DIRECT_DATABASE_URL - Direct PostgreSQL connection (non-pooled)
    • DATABASE_URL - Runtime database connection (can be pooled)
    • NEXT_PUBLIC_SUPABASE_URL - Supabase project URL
    • NEXT_PUBLIC_SUPABASE_ANON_KEY - Supabase anon key
    • SUPABASE_SERVICE_ROLE_KEY - Supabase service role key (SECRET!)
    • NEXT_PUBLIC_SITE_URL - Your production domain
  • Verify DIRECT_DATABASE_URL does NOT have connection pooling

    # Should NOT contain ?pgbouncer=true or similar
    echo $DIRECT_DATABASE_URL | grep -i pgbouncer
    

    Expected: No output (no pooling parameters)

  • Test database connection with DIRECT_DATABASE_URL

    DATABASE_URL="$DIRECT_DATABASE_URL" npx prisma db execute --stdin <<< "SELECT 1 as test;"
    

    Expected: Connection succeeds

  • Verify Supabase keys are not legacy keys

    • Check that keys were generated after 2024
    • If unsure, regenerate in Supabase Dashboard → Settings → API

3. Build Process Verification

  • Verify scripts/deploy-migrations.sh is executable

    ls -la scripts/deploy-migrations.sh | grep -E "^-rwxr"
    

    Expected: Shows executable permissions (-rwxr-xr-x)

  • Verify scripts/vercel-build.sh runs migrations

    grep -A 5 "🗄️  Database migrations" scripts/vercel-build.sh
    

    Expected: Shows migration code block that calls deploy-migrations.sh

  • Test migration deployment script locally

    DIRECT_DATABASE_URL="..." bash scripts/deploy-migrations.sh
    

    Expected: "✅ Migrations deployed successfully"

  • Verify build command in package.json or vercel.json

    cat vercel.json | grep buildCommand
    # OR
    cat package.json | grep "\"build\":"
    

    Expected: Uses pnpm exec next build or calls scripts/vercel-build.sh

4. Code Quality Verification

  • Run TypeScript type checking

    pnpm typecheck
    

    Expected: "Found 0 errors"

  • Run linting

    pnpm lint
    

    Expected: No critical errors

  • Verify all authId fallback logic is present

    grep -n "authId column not found" lib/auth/server.ts app/auth/callback/route.ts app/api/onboarding/init/route.ts
    

    Expected: Shows fallback messages in all three files

5. Authentication Flow Verification

  • Verify signup route has authId fallback

    grep -A 10 "authId column not found, creating user without authId" lib/auth/server.ts
    

    Expected: Shows complete fallback logic with retry

  • Verify OAuth callback has authId fallback

    grep -A 10 "authId column not found in OAuth callback" app/auth/callback/route.ts
    

    Expected: Shows complete fallback logic

  • Verify onboarding init has authId fallback

    grep -A 10 "authId column not found in auto-recovery" app/api/onboarding/init/route.ts
    

    Expected: Shows complete fallback logic

6. Voice & Onboarding Service Verification

  • Verify voice service environment variables are set

    Required for Voice Onboarding:

    • OPENAI_API_KEY - OpenAI API key for text chat
    • CARTESIA_API_KEY - Cartesia TTS for voice synthesis
    • CARTESIA_VOICE_ID - Voice ID for Petunia voice
    • TWILIO_ACCOUNT_SID - Twilio account identifier
    • TWILIO_AUTH_TOKEN - Twilio authentication
    • TWILIO_PHONE_NUMBER - Outbound phone number for calls
  • Test onboarding availability endpoint

    curl -s http://localhost:3000/api/onboarding/availability | jq
    

    Expected: Returns JSON with voice, text, quickSetup availability status

  • Verify onboarding service health

    curl -s http://localhost:3000/api/onboarding/health | jq
    

    Expected: Returns { "status": "healthy" } or detailed health report

  • Verify Cartesia TTS is responsive

    curl -s -X POST https://api.cartesia.ai/tts/bytes \
      -H "X-API-Key: $CARTESIA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"transcript": "test", "voice": {"mode": "id", "id": "'$CARTESIA_VOICE_ID'"}, "output_format": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 16000}}' \
      -o /dev/null -w "%{http_code}"
    

    Expected: 200

  • Verify Twilio credentials are valid

    curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
      "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json" | jq '.status'
    

    Expected: "active"

  • Verify onboarding completion endpoint exists

    grep -n "export async function POST" app/api/onboarding/complete/route.ts
    

    Expected: Shows POST handler line number

  • Verify onboarding has service availability awareness

    grep -n "useOnboardingAvailability" app/\(client\)/onboarding/page.tsx components/onboarding/OnboardingErrorFallback.tsx
    

    Expected: Shows availability hook usage in both files

7. Real-Time Server Verification (Optional)

Note: The realtime-server is optional and deployed separately from the main Next.js app.

  • Verify realtime-server builds successfully

    cd realtime-server && pnpm install && pnpm build
    

    Expected: TypeScript compiles successfully, dist/ directory created

  • Verify realtime-server environment variables

    Required for Production:

    • JWT_SECRET or NEXTAUTH_SECRET - Must match main app secret
    • ALLOWED_ORIGINS - Comma-separated list of allowed origins (e.g., https://yourdomain.com)
    • REALTIME_PORT - Port for WebSocket server (default: 3001)

    Optional for Horizontal Scaling:

    • REDIS_URL - Redis connection string for multi-instance deployments
  • Test realtime-server locally

    cd realtime-server && pnpm start
    

    Expected: Server starts on configured port, health check responds at http://localhost:3001

  • Verify Docker image builds (if using Docker deployment)

    cd realtime-server && docker build -t petunia-realtime:test .
    

    Expected: Multi-stage build completes successfully

  • Document deployment platform

    • Using Heroku/Railway/Render (uses Procfile)
    • Using Docker/Kubernetes (uses Dockerfile)
    • Using dedicated VM (systemd service)
    • Not deploying realtime-server (optional component)

8. Middleware and Homepage Verification

  • Verify middleware handles homepage redirect

    grep -A 5 "Redirect logged-in users from homepage to dashboard" proxy.ts
    

    Expected: Shows server-side redirect logic

  • Verify homepage has mounted check for CloudBackground

    grep -B 2 -A 2 "mounted &&" "app/(public)/page.tsx"
    

    Expected: Shows conditional rendering with mounted check

9. Git and Version Control

  • Verify all changes are committed

    git status
    

    Expected: "nothing to commit, working tree clean"

  • Verify you're on the correct branch

    git branch --show-current
    

    Expected: "main" or your deployment branch

  • Verify latest changes are pushed

    git status -sb
    

    Expected: Shows "Your branch is up to date with 'origin/main'"

  • Verify commit history is clean

    git log --oneline -5
    

    Expected: Shows recent commits including schema drift fix

10. Documentation Verification

  • Verify DATABASE_MIGRATIONS.md exists

    test -f docs/DATABASE_MIGRATIONS.md && echo "EXISTS" || echo "MISSING"
    

    Expected: "EXISTS"

  • Verify Vercel environment matrix exists

    test -f docs/env/VERCEL_ENV_MATRIX.md && echo "EXISTS" || echo "MISSING"
    

    Expected: "EXISTS"

  • Verify this checklist is up to date

    head -3 docs/PRE_DEPLOYMENT_CHECKLIST.md | grep "2026"
    

    Expected: Shows current year

Pre-Deployment Test (Local Build)

Run a complete build locally to catch any issues:

# 1. Clean previous builds
rm -rf .next node_modules/.prisma

# 2. Install dependencies
pnpm install

# 3. Run migrations
DIRECT_DATABASE_URL="..." bash scripts/deploy-migrations.sh

# 4. Generate Prisma Client
npx prisma generate

# 5. Build Next.js
pnpm exec next build

# 6. Check build output
test -d .next && echo "✅ Build succeeded" || echo "❌ Build failed"

Expected: All steps complete without errors, .next directory exists

Deployment Steps

Step 1: Final Verification

  • All checklist items above are complete
  • No failing tests
  • No TypeScript errors
  • No critical lint errors
  • All environment variables set in Vercel

Step 2: Deploy to Preview

# Push to preview branch (or create PR)
git checkout -b preview/schema-drift-fix
git push origin preview/schema-drift-fix
  • Preview deployment succeeded in Vercel
  • Check Vercel build logs for migration success
  • Test signup flow in preview environment
  • Test OAuth flow in preview environment
  • Test homepage rendering in preview environment

Step 3: Deploy to Production

# Merge to main and push
git checkout main
git merge preview/schema-drift-fix
git push origin main
  • Production deployment succeeded in Vercel
  • Check Vercel build logs for migration success
  • Monitor error logs for first 10 minutes
  • Test signup flow in production
  • Test OAuth flow in production
  • Test homepage rendering in production

Post-Deployment Verification

Immediate Checks (0-10 minutes after deployment)

  • Homepage loads correctly

    • Visit https://your-domain.com
    • Verify no glitchy clouds
    • Verify smooth animations
    • If logged in, verifies redirect to dashboard works
  • Email signup works

    • Visit /auth/signup
    • Enter email, password, name
    • Click "Create Account"
    • Verify no errors
    • Verify redirect to onboarding
    • Check email for verification link
  • Google OAuth signup works

    • Visit /auth/signup
    • Click "Sign up with Google"
    • Complete OAuth flow
    • Verify no errors
    • Verify redirect to onboarding
  • Database has correct schema

    # Run health check against production
    DIRECT_DATABASE_URL="production_url" npm run db:health
    

    Expected: All checks pass

Extended Checks (1 hour after deployment)

  • Monitor error logs in Vercel

    • Go to Vercel Dashboard → Your Project → Logs
    • Filter for errors
    • Verify no schema-related errors
    • Verify no auth-related errors
  • Check Sentry (if configured)

    • Review error rate
    • Check for new error types
    • Investigate any spikes
  • Test complete user journey

    1. Sign up with email
    2. Verify email
    3. Complete onboarding
    4. Access dashboard
    5. Create a portal/organization
    6. Verify all features work

Rollback Plan

If issues occur after deployment:

Option 1: Quick Rollback (Vercel)

# Via Vercel CLI
vercel rollback

# Or via Vercel Dashboard
# Go to Deployments → Select previous working deployment → Promote to Production

Option 2: Revert Git Changes

# Identify the commit to revert to
git log --oneline -10

# Revert to previous working commit
git revert <commit-sha>
git push origin main

Option 3: Emergency Database Fix

If schema is broken and rollback isn't working:

# Run migrations manually
DIRECT_DATABASE_URL="..." bash scripts/deploy-migrations.sh

# Or apply specific migration
DIRECT_DATABASE_URL="..." npx prisma migrate deploy

Success Criteria

Deployment is considered successful when:

  • All checklist items are verified ✅
  • Build completed without errors
  • Migrations ran successfully
  • Homepage loads without glitches
  • Email signup completes successfully
  • OAuth signup completes successfully
  • Users can access dashboard
  • No schema-related errors in logs
  • No auth-related errors in logs
  • Health checks pass
  • Error rate is normal (< 1%)

Common Issues and Solutions

Issue: Build fails with "Database URL not configured"

Solution: Verify DIRECT_DATABASE_URL is set in Vercel environment variables

Issue: Migrations fail during build

Solution:

  1. Check DIRECT_DATABASE_URL is not using connection pooling
  2. Verify database credentials are correct
  3. Run migrations manually: DIRECT_DATABASE_URL="..." bash scripts/deploy-migrations.sh

Issue: "Column authId does not exist" after deployment

Solution:

  1. Check Vercel build logs - did migrations run?
  2. Run database health check: npm run db:health
  3. If migrations didn't run, run manually
  4. If migrations ran but column missing, check Prisma schema matches database

Issue: Users can't sign up after deployment

Solution:

  1. Check browser console for errors
  2. Check Vercel logs for server errors
  3. Verify Supabase keys are correct and not expired
  4. Test with curl to isolate client vs server issue

Issue: OAuth fails after deployment

Solution:

  1. Verify NEXT_PUBLIC_SITE_URL matches actual domain
  2. Check Supabase Dashboard → Authentication → URL Configuration
  3. Ensure redirect URLs are whitelisted in Supabase
  4. Check OAuth callback route has authId fallback logic

Contact and Support

If issues persist:

  1. Check DATABASE_MIGRATIONS.md for migration help
  2. Check VERCEL_ENV_MATRIX.md for env var help
  3. Review Vercel build logs for detailed errors
  4. Check Supabase logs for auth issues

Changelog

  • 2025-12-03: Added Real-Time Server Verification section (Section 7)
  • 2025-12-02: Added Voice & Onboarding Service Verification section (Section 6)
  • 2025-11-14: Initial version - comprehensive checklist for schema drift fix deployment