​
Deploying to Production

This guide provides step-by-step instructions for deploying your Kaizen application to production using Vercel and transitioning all services from development to production environments.

You’ll need a custom domain for production deployment. Services like Clerk and Polar require verified domains for production environments. Purchase a domain from providers like Namecheap, Porkbun, or GoDaddy before proceeding.

​
Prerequisites

  • ✅ A custom domain (purchased and ready)
  • ✅ Your code committed and pushed to GitHub/GitLab/Bitbucket
  • ✅ All development features working locally
  • ✅ Production accounts for your enabled services

​
Step 1: Configure Production Services

​
Clerk Authentication

For Email/Password Only (Simplest):

  1. In your existing Clerk application, go to Configure → Instance Settings
  2. Switch from “Development” to “Production” mode
  3. Update your domain settings:
    • Add your production domain (e.g., https://yourdomain.com)
    • Remove localhost URLs
  4. Copy your new production API keys:
    • VITE_CLERK_PUBLISHABLE_KEY (starts with pk_live_)
    • CLERK_SECRET_KEY (starts with sk_live_)

For OAuth Providers (Google, etc.):

  1. Follow the Clerk OAuth setup guide for each provider
  2. Update OAuth callback URLs to your production domain
  3. For Google OAuth specifically:
    • Update “Authorized JavaScript origins” to your production domain
    • Update “Authorized redirect URIs” to use your production Clerk instance
    • Ensure your Google OAuth app is set to “In production” status (not “Testing”)

​
Polar.sh Payments

  1. Switch to production Polar:

    • Log out of sandbox.polar.sh
    • Log into polar.sh (production)
    • Create your production organization
    • Set up your subscription plans with real pricing

  2. Get production API keys:

    • Go to Settings → API Keys
    • Copy your POLAR_ACCESS_TOKEN (starts with polar_)
    • Copy your POLAR_ORGANIZATION_ID (starts with org_)

​
Resend Email Service

  1. Create production API key:

    • In Resend dashboard, go to API Keys
    • Create new key with “Full Access”
    • Copy the API key (starts with re_)

  2. Set up custom domain (Recommended):

    • Go to Domains → Add Domain
    • Enter your domain (e.g., yourdomain.com)
    • Add the required DNS records to your domain registrar
    • Wait for verification (can take up to 24 hours)
    • Use noreply@yourdomain.com as your sender email

​
OpenAI (If Enabled)

  1. Use existing API key or create a new production key
  2. Ensure sufficient credits for production usage

​
Step 2: Set Up Convex Production Environment

​
Add Environment Variables to Convex Production

  1. Go to your Convex Dashboard → Switch to Production environment
  2. Navigate to Settings → Environment Variables
  3. Add the following variables:
# Frontend Configuration
FRONTEND_URL=https://yourdomain.com

# Company Configuration  
COMPANY_NAME=Your Company Name
SENDER_EMAIL=noreply@yourdomain.com

# Clerk JWT Integration
VITE_CLERK_FRONTEND_API_URL=https://your-app.clerk.accounts.dev

# Polar.sh (Production)
POLAR_ACCESS_TOKEN=polar_...
POLAR_ORGANIZATION_ID=org_...
POLAR_WEBHOOK_SECRET=whsec_...

# Resend (Production)
RESEND_API_KEY=re_...
RESEND_WEBHOOK_SECRET=whsec_...

# OpenAI (If enabled)
OPENAI_API_KEY=sk-...

Webhook secrets will be generated in Step 5 when you configure webhooks. Add placeholders for now.

​
Step 3: Deploy Backend to Convex Production

Now that your production environment variables are configured, deploy your Convex backend:

  1. Deploy your Convex backend to production:

    npx convex deploy

  2. Note your production deployment URL (e.g., https://posh-cassowary-60.convex.cloud)

  3. Configure Convex for Vercel deployment (one-time setup):

    npx convex deploy --cmd-url-env-var-name VITE_CONVEX_URL --cmd 'npm run build'

Convex will now deploy successfully since all required environment variables are configured.

​
Step 4: Deploy Frontend to Vercel

  1. Connect your repository to Vercel:

    • Go to vercel.com and create new project
    • Import your Git repository
    • Select your framework preset as Vite

  2. Configure build settings:

    • Build Command: npm run build
    • Output Directory: dist
    • Install Command: npm install --legacy-peer-deps

  3. Add environment variables in Vercel:

    Required for all deployments:

    VITE_CONVEX_URL=https://your-project.convex.cloud
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...

  4. Deploy the project - Vercel will automatically deploy

  5. Set up custom domain:

    • In Vercel dashboard, go to Settings → Domains
    • Add your custom domain
    • Follow DNS setup instructions

​
Step 5: Configure Production Webhooks

​
Polar.sh Webhooks

  1. In Polar dashboard:

    • Go to Settings → Webhooks
    • Click Add Endpoint
    • URL: https://your-project.convex.cloud/payments/webhook
    • Format: Raw
    • Events: Select all events
    • Click Generate new secret and copy it

  2. Update Convex environment variable:

    • Add POLAR_WEBHOOK_SECRET=whsec_... to your Convex production environment

​
Resend Webhooks

  1. In Resend dashboard:

    • Go to Webhooks → Add Endpoint
    • URL: https://your-project.convex.cloud/resend-webhook
    • Events: Select all email.* events
    • Copy the webhook signing secret

  2. Update Convex environment variable:

    • Add RESEND_WEBHOOK_SECRET=whsec_... to your Convex production environment

​
Step 6: Final Configuration Updates

​
Update Clerk Production Settings

  1. Add production domains:

    • Go to Configure → Instance Settings
    • Add your production domain to allowed origins
    • Remove development/localhost URLs

  2. Update JWT Template for Convex:

    • Go to Configure → JWT Templates
    • Find your Convex template
    • Ensure it’s properly configured for production

​
Update Frontend URL in Convex

Critical: Update the FRONTEND_URL in your Convex production environment variables to your actual domain:

FRONTEND_URL=https://yourdomain.com

​
Step 7: Test Production Deployment

​
Complete User Flow Test

  1. Authentication:

    • Sign up with a new account
    • Verify email works
    • Test login/logout

  2. Payments (if enabled):

    • Test subscription signup
    • Use test card: 4242 4242 4242 4242
    • Verify dashboard access after payment
    • Test subscription management

  3. Core Features:

    • Test all main app functionality
    • Verify real-time features work
    • Test email notifications

​
Monitor Service Dashboards

Check logs and metrics in:

  • Convex Dashboard → Logs
  • Clerk Dashboard → Activity
  • Polar Dashboard → Webhooks
  • Resend Dashboard → Logs
  • Vercel Dashboard → Functions

​
Production Checklist

  • Custom domain configured and working
  • Convex deployed to production with all environment variables
  • Vercel deployed with correct environment variables
  • Clerk switched to production mode with domain configured
  • Polar.sh production account with webhooks configured
  • Resend production API key with domain verified
  • All webhooks pointing to production Convex URL
  • Complete user flow tested end-to-end
  • OAuth providers configured for production (if applicable)
  • Subscription plans created in production Polar
  • Email templates working with production domain

​
Troubleshooting

Authentication Issues:

  • Verify Clerk domain settings include your production URL
  • Check JWT template configuration in Clerk
  • Ensure OAuth apps are in “production” mode (not “testing”)

Payment Issues:

  • Verify Polar webhook URL points to production Convex
  • Check webhook secret matches in both Polar and Convex
  • Ensure using production Polar account (not sandbox)

Email Issues:

  • Verify domain authentication in Resend
  • Check webhook secret matches in both Resend and Convex
  • Ensure sender email domain is verified

General Issues:

  • Check Convex logs for backend errors
  • Verify all environment variables are set correctly
  • Ensure frontend URL is set correctly in Convex (no trailing slash)

🎉 Congratulations! Your Kaizen application is now live in production. Monitor your service dashboards for the first few days to ensure everything is working smoothly.