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