> ## Documentation Index
> Fetch the complete documentation index at: https://blueprint.codeandcreed.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy to Production

> Comprehensive guide for deploying your Kaizen application to production

# 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.

<Warning>
  **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.
</Warning>

## 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](https://clerk.com/docs/authentication/social-connections/google) 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:**

```env theme={null}
# 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-...
```

<Note>
  **Webhook secrets** will be generated in Step 5 when you configure webhooks. Add placeholders for now.
</Note>

## 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:**
   ```bash theme={null}
   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):
   ```bash theme={null}
   npx convex deploy --cmd-url-env-var-name VITE_CONVEX_URL --cmd 'npm run build'
   ```

<Note>
  Convex will now deploy successfully since all required environment variables are configured.
</Note>

## Step 4: Deploy Frontend to Vercel

1. **Connect your repository to Vercel:**
   * Go to [vercel.com](https://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:**

   ```env theme={null}
   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:

```env theme={null}
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)

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