Documentation

VERCEL_ENV_MATRIX

docs/env/VERCEL_ENV_MATRIX.md

Vercel Environment Variables Matrix

This document provides a complete reference for setting environment variables in Vercel across different deployment environments.

For deployment agents A7, A8, A9, A11: Use this matrix to configure Vercel environment variables correctly.

Environment Scopes

Vercel supports three environment scopes:

  • Production: Live production deployment
  • Preview: PR/branch preview deployments
  • Development: Local development (pulled via vercel env pull)

Required Variables (Production)

These MUST be set in Vercel for production deployments to succeed.

VariableScopeValue SourceNotes for Deployment Agents
NEXT_PUBLIC_SUPABASE_URLProduction, Preview, DevelopmentSupabase DashboardUse production Supabase for prod, staging for preview
NEXT_PUBLIC_SUPABASE_ANON_KEYProduction, Preview, DevelopmentSupabase DashboardMatch the environment (prod/staging)
SUPABASE_SERVICE_ROLE_KEYProduction, Preview, DevelopmentSupabase DashboardSECRET - Use different keys per environment
DATABASE_URLProduction, Preview, DevelopmentSupabase Dashboard → DatabaseUse connection pooler URL for serverless
NEXT_PUBLIC_SITE_URLProductionhttps://app.petunia.gardenpatch.xyzUpdate to actual production domain
NEXT_PUBLIC_SITE_URLPreviewhttps://$VERCEL_URLAutomatic preview URL
NEXT_PUBLIC_SITE_URLDevelopmenthttp://localhost:3000Local development URL
SESSION_SECRETProduction, Preview, DevelopmentGenerate with openssl rand -base64 32SECRET - Different per environment

Optional Variables (Feature-Specific)

Set these only if the corresponding feature is enabled.

Yelp Integration

VariableScopeRequired IfNotes
YELP_API_KEYProduction, PreviewYelp integration enabledSECRET
YELP_CLIENT_IDProduction, PreviewYelp OAuth enabled
YELP_CLIENT_SECRETProduction, PreviewYelp OAuth enabledSECRET

Google Integration

VariableScopeRequired IfNotes
GOOGLE_CLIENT_IDProduction, PreviewGoogle OAuth enabled
GOOGLE_CLIENT_SECRETProduction, PreviewGoogle OAuth enabledSECRET
GOOGLE_API_KEYProduction, PreviewGoogle Business Profile enabledSECRET

Facebook Integration

VariableScopeRequired IfNotes
FACEBOOK_CLIENT_IDProduction, PreviewFacebook integration enabled
FACEBOOK_CLIENT_SECRETProduction, PreviewFacebook integration enabledSECRET

AI Services

VariableScopeRequired IfNotes
OPENAI_API_KEYProduction, PreviewOpenAI features enabledSECRET - Monitor usage
ANTHROPIC_API_KEYProduction, PreviewClaude features enabledSECRET - Monitor usage
PINECONE_API_KEYProduction, PreviewVector search enabledSECRET

Voice Services

VariableScopeRequired IfNotes
ELEVENLABS_API_KEYProduction, PreviewElevenLabs TTS enabledSECRET
CARTESIA_API_KEYProduction, PreviewCartesia voice enabledSECRET
RETELL_API_KEYProduction, PreviewRetell voice enabledSECRET
CARTESIA_VOICE_IDProduction, PreviewCartesia voice enabledVoice ID from Cartesia dashboard
NEXT_PUBLIC_RETELL_AGENT_IDProduction, PreviewRetell voice enabledAgent ID from Retell dashboard

Payments (Stripe)

VariableScopeRequired IfNotes
STRIPE_SECRET_KEYProductionBilling enabledSECRET - Use live key
STRIPE_SECRET_KEYPreviewBilling enabledSECRET - Use test key
STRIPE_PUBLISHABLE_KEYProductionBilling enabledUse live key
STRIPE_PUBLISHABLE_KEYPreviewBilling enabledUse test key
STRIPE_WEBHOOK_SECRETProductionStripe webhooks enabledSECRET - From Stripe webhook settings

Email

VariableScopeRequired IfNotes
MAILGUN_API_KEYProduction, PreviewMailgun email enabledSECRET
MAILGUN_DOMAINProduction, PreviewMailgun email enabledYour sending domain
MAILGUN_REGIONProduction, PreviewMailgun email enabledeu or us (default: eu)
SMTP_HOSTProduction, PreviewSMTP email enabled
SMTP_PORTProduction, PreviewSMTP email enabledUsually 587 or 465
SMTP_USERProduction, PreviewSMTP email enabled
SMTP_PASSWORDProduction, PreviewSMTP email enabledSECRET

SMS (Twilio)

VariableScopeRequired IfNotes
TWILIO_ACCOUNT_SIDProduction, PreviewTwilio SMS enabled
TWILIO_AUTH_TOKENProduction, PreviewTwilio SMS enabledSECRET
TWILIO_PHONE_NUMBERProduction, PreviewTwilio SMS enabledE.164 format

Monitoring

VariableScopeRequired IfNotes
SENTRY_DSNProduction, PreviewSentry monitoring enabled
SENTRY_AUTH_TOKENProductionSentry releases enabledSECRET

Redis/Caching

VariableScopeRequired IfNotes
UPSTASH_REDIS_REST_URLProduction, PreviewRedis caching enabledUpstash dashboard
UPSTASH_REDIS_REST_TOKENProduction, PreviewRedis caching enabledSECRET
RATE_LIMIT_REDIS_URLProduction, PreviewRate limiting enabledRedis connection string

Security

VariableScopeRequired IfNotes
CSRF_SECRETProduction, PreviewCSRF protection enabledSECRET - 32+ chars
WEBSOCKET_ENCRYPTION_KEYProduction, PreviewWebSocket encryption enabledSECRET - 32+ chars

Deployment Agent Instructions

For A7 (Production Deployment)

  1. Set ALL required variables in Vercel → Settings → Environment Variables
  2. Set scope to "Production" for production-only values
  3. Set scope to "Production, Preview, Development" for shared values
  4. Verify all SECRET variables are properly hidden
  5. Test deployment with vercel --prod

For A8 (Staging Deployment)

  1. Use "Preview" scope for staging-specific variables
  2. Use test/staging keys for third-party services (Stripe test mode, etc.)
  3. Use staging Supabase project
  4. Test with preview deployment

For A9 (Feature Branch Deployment)

  1. Use "Preview" scope for branch deployments
  2. Consider using demo services for expensive APIs (AI, Voice)
  3. Use minimal feature flags

For A11 (Rollback Deployment)

  1. Ensure environment variables are versioned in 1Password/Vault
  2. Have backup of all production environment variables
  3. Test rollback in preview environment first

Verification Checklist

Before deploying, verify:

  • All required variables are set
  • All SECRET variables are hidden in Vercel UI
  • Production uses production keys, Preview uses test keys
  • NEXT_PUBLIC_SITE_URL matches deployment environment
  • Database URLs use connection pooling
  • Webhook secrets match configured webhooks
  • API keys have appropriate rate limits
  • SESSION_SECRET is 32+ characters
  • No development secrets in production

Troubleshooting

Build fails with "Missing required variable"

Check Vercel build logs for the specific variable. Add it to Vercel environment variables with correct scope.

Runtime error: "Invalid Supabase URL"

Verify NEXT_PUBLIC_SUPABASE_URL is set for the correct environment (Production/Preview).

500 errors after deployment

Check Vercel function logs. Often caused by missing DATABASE_URL or service role keys.

Webhooks not working

Verify webhook secrets match Vercel deployment URL. Update webhook URLs in third-party services (Stripe, etc.).

Security Notes

  1. Never commit .env files with real values to git
  2. Use Vercel's built-in secrets management - values are encrypted at rest
  3. Rotate secrets regularly - see ENV_GUIDE.md for rotation schedule
  4. Use different keys per environment - never share production keys with staging
  5. Monitor for leaked secrets - enable GitHub secret scanning

Contact

For questions about Vercel deployment:

  • Vercel configuration: Platform Team
  • Environment variable issues: See ENV_GUIDE.md for variable owners
  • Deployment failures: Check Vercel logs first, then contact Platform Team