Deploy to Vercel

Vercel is the recommended platform for deploying ZapDev. This guide covers the complete deployment process including Convex backend, Inngest Cloud integration, and all required services.

Prerequisites

Before deploying, ensure you have accounts for:

Vercel - Hosting platform
Convex - Real-time database backend
Inngest Cloud - Background job processing
Clerk - Authentication (or Stack Auth)
E2B - Code sandbox environment
Polar.sh - Billing and subscriptions
OpenRouter - AI model gateway
Cerebras - Ultra-fast AI inference (optional)

Step 1: Set Up Inngest Cloud

Inngest Cloud handles background AI code generation workflows.

Create an Inngest Account

Go to Inngest Cloud and sign up or log in

Create a New App

Click “Create App” in the dashboard
Name your app (e.g., zapdev-production)

Get Your Keys

Navigate to your app settings and copy:

Event Key (starts with ac9_)
Signing Key (starts with signkey-)

You’ll need these for Vercel environment variables.

Step 2: Deploy Convex Backend

Convex provides the real-time database for ZapDev.

Install Convex CLI

bun install -g convex

bunx convex login

Create Production Deployment

bunx convex deploy

This will:

Create a production deployment
Provide your NEXT_PUBLIC_CONVEX_URL
Deploy your database schema and functions

Copy Convex URL

Save the NEXT_PUBLIC_CONVEX_URL from the deployment output - you’ll need it for Vercel.

Step 3: Build E2B Sandbox Template

This step is required before deployment. The E2B template must be built with Docker running.

Install E2B CLI

bun install -g @e2b/cli
# or
brew install e2b

e2b auth login

Build the Template

cd sandbox-templates/nextjs
e2b template build --name zapdev-production --cmd "/compile_page.sh"

Important: Docker must be installed and running for this command.

Update Template Name

After building, update the template name in your codebase:

// src/inngest/functions.ts (line ~22)
const sandbox = await Sandbox.create("zapdev-production");

Commit this change before deploying to Vercel.

Step 4: Deploy to Vercel

Push to GitHub

git add .
git commit -m "chore: prepare for production deployment"
git push origin main

Import to Vercel

Go to Vercel Dashboard
Click “New Project”
Import your GitHub repository
Select the repository containing ZapDev

Configure Build Settings

Vercel should auto-detect Next.js. Verify:

Framework Preset: Next.js
Build Command: bun run build
Install Command: bun install
Output Directory: .next (default)

Add Environment Variables

In the Vercel project settings, add all environment variables (see below).

Copy from your local .env file, but replace development URLs with production values.

Deploy

Click “Deploy” and wait for the build to complete (typically 2-3 minutes).

Step 5: Configure Environment Variables

Add these environment variables in your Vercel project settings:

Application

NEXT_PUBLIC_APP_URL="https://your-app.vercel.app"

Convex Database

NEXT_PUBLIC_CONVEX_URL="https://your-deployment.convex.cloud"
NEXT_PUBLIC_CONVEX_SITE_URL="https://your-app.vercel.app"

Clerk Authentication

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_live_..."
CLERK_SECRET_KEY="sk_live_..."
CLERK_JWT_ISSUER_DOMAIN="clerk.your-domain.com"
CLERK_JWT_TEMPLATE_NAME="convex"

Create a JWT template named “convex” in Clerk Dashboard → JWT Templates for Convex integration.

Polar.sh Billing

POLAR_ACCESS_TOKEN="polar_at_..."
POLAR_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_POLAR_ORGANIZATION_ID="org_..."
NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID="prod_..."
NEXT_PUBLIC_POLAR_PRO_PRICE_ID="price_..."
NEXT_PUBLIC_POLAR_PRO_YEARLY_PRICE_ID="price_..."
NEXT_PUBLIC_POLAR_UNLIMITED_PRODUCT_ID="prod_..."
NEXT_PUBLIC_POLAR_UNLIMITED_PRICE_ID="price_..."
NEXT_PUBLIC_POLAR_SERVER="production"

AI Services

# OpenRouter (AI Gateway)
OPENROUTER_API_KEY="sk-or-..."
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"

# Cerebras (Ultra-fast inference)
CEREBRAS_API_KEY="csk-..."

# Vercel AI Gateway (fallback)
VERCEL_AI_GATEWAY_API_KEY="..."

E2B Sandboxes

E2B_API_KEY="e2b_..."

Inngest (Background Jobs)

INNGEST_EVENT_KEY="ac9_..."
INNGEST_SIGNING_KEY="signkey-..."

Optional Services

# Brave Search (web research)
BRAVE_SEARCH_API_KEY="..."

# Firecrawl (web scraping)
FIRECRAWL_API_KEY="..."

# UploadThing (file uploads)
UPLOADTHING_TOKEN="..."

# Sentry (error monitoring)
NEXT_PUBLIC_SENTRY_DSN="https://..."
SENTRY_DSN="https://..."

Step 6: Sync with Inngest Cloud

After Vercel deployment completes, connect Inngest to your app:

Get Your Vercel URL

Copy your deployed app URL (e.g., https://your-app.vercel.app)

Sync with Inngest

Go to Inngest Dashboard
Navigate to your app
Click “Sync App”
Add URL: https://your-app.vercel.app/api/inngest
Click “Sync”

Verify Connection

Inngest will connect to your endpoint. You should see:

Status: “Connected”
Functions listed: codeAgentFunction, auto-pause-sandboxes
No error messages

Step 7: Configure Webhooks

Clerk Webhooks

Update Webhook URL

Go to Clerk Dashboard → Webhooks
Update webhook URL to: https://your-app.vercel.app/api/webhooks/clerk

Enable Events

Ensure these events are enabled:

user.created
user.updated
session.created

Polar.sh Webhooks

Configure Webhook

Go to Polar.sh Dashboard → Webhooks
Add endpoint: https://your-app.vercel.app/api/webhooks/polar
Copy the webhook secret to POLAR_WEBHOOK_SECRET

Step 8: Set Up Cron Jobs

ZapDev includes a cron job for sandbox cleanup defined in vercel.json:

{
  "crons": [
    {
      "path": "/api/cron/cleanup-sandboxes",
      "schedule": "0 0 * * *"
    }
  ]
}

This runs daily at midnight UTC. Vercel automatically registers this cron job on deployment.

View cron job execution logs in Vercel Dashboard → Logs → Filter by /api/cron/cleanup-sandboxes

Monitoring Your Deployment

Vercel Dashboard

Deployments: Track build status and history
Logs: Real-time function logs and errors
Analytics: Performance metrics and Web Vitals
Speed Insights: Core Web Vitals monitoring

Convex Dashboard

Monitor at dashboard.convex.dev:

Data: View database tables and documents
Functions: Query and mutation execution logs
Logs: Real-time backend logs
Deployments: Schema change history

Inngest Dashboard

Monitor at app.inngest.com:

Functions: View all registered functions
Runs: Execution history and status
Errors: Failed runs with replay capability
Crons: Scheduled job execution times

E2B Dashboard

Monitor at e2b.dev/account:

Sandboxes: Active and paused sandboxes
Usage: API calls and compute time
Costs: Real-time cost tracking

Auto-pause should reduce E2B costs by 30-50% by pausing inactive sandboxes every 5 minutes.

Troubleshooting

Deployment Fails

Issue: Build fails with TypeScript errors Solution:

# Test build locally first
bun run build

# Fix any TypeScript errors
bun run lint

Inngest Not Syncing

Issue: Inngest shows “Failed to sync” error Solution:

Verify INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY are correct
Check Vercel function logs for /api/inngest errors
Ensure endpoint is publicly accessible
Re-deploy and try syncing again

AI Generation Not Working

Issue: Code generation fails or hangs Solutions:

Verify E2B Template:

# Check template exists
e2b template list

Check API Keys:
- Verify E2B_API_KEY is valid
- Test CEREBRAS_API_KEY or OPENROUTER_API_KEY
Review Inngest Logs:
- Check for sandbox creation errors
- Look for API timeout issues

Database Connection Issues

Issue: Convex queries failing Solution:

Verify NEXT_PUBLIC_CONVEX_URL is correct
Check Convex dashboard for deployment status
Ensure JWT template is configured in Clerk
Re-deploy Convex: bunx convex deploy

Webhook Failures

Issue: Clerk or Polar webhooks not received Solution:

Check webhook URLs are correct
Verify webhook secrets match environment variables
Review Vercel function logs for webhook endpoints
Test webhook delivery in service dashboard

Production Checklist

Before launching to production:

Updating Your Deployment

Code Changes

# Push to main branch
git push origin main

# Vercel auto-deploys from main

Schema Changes

# Deploy Convex schema updates
bunx convex deploy

# Then deploy to Vercel (auto-triggers on push)
git push origin main

Environment Variables

Update in Vercel Dashboard → Settings → Environment Variables
Redeploy: Vercel Dashboard → Deployments → Redeploy

Next Steps

Docker Deployment

Alternative deployment using Docker containers

Self-Hosted

Deploy on your own infrastructure

Database Setup

Docker Deployment

⌘I

Setup

Platforms

Configuration

Documentation Index

​Prerequisites

​Step 1: Set Up Inngest Cloud

​Step 2: Deploy Convex Backend

​Step 3: Build E2B Sandbox Template

​Step 4: Deploy to Vercel

​Step 5: Configure Environment Variables

​Application

​Convex Database

​Clerk Authentication

​Polar.sh Billing

​AI Services

​E2B Sandboxes

​Inngest (Background Jobs)

​Optional Services

​Step 6: Sync with Inngest Cloud

​Step 7: Configure Webhooks

​Clerk Webhooks

​Polar.sh Webhooks

​Step 8: Set Up Cron Jobs

​Monitoring Your Deployment

​Vercel Dashboard

​Convex Dashboard

​Inngest Dashboard

​E2B Dashboard

​Troubleshooting

​Deployment Fails

​Inngest Not Syncing

​AI Generation Not Working

​Database Connection Issues

​Webhook Failures

​Production Checklist

​Updating Your Deployment

​Code Changes

​Schema Changes

​Environment Variables

​Next Steps

Docker Deployment

Self-Hosted

Prerequisites

Step 1: Set Up Inngest Cloud

Step 2: Deploy Convex Backend

Step 3: Build E2B Sandbox Template

Step 4: Deploy to Vercel

Step 5: Configure Environment Variables

Application

Convex Database

Clerk Authentication

Polar.sh Billing

AI Services

E2B Sandboxes

Inngest (Background Jobs)

Optional Services

Step 6: Sync with Inngest Cloud

Step 7: Configure Webhooks

Clerk Webhooks

Polar.sh Webhooks

Step 8: Set Up Cron Jobs

Monitoring Your Deployment

Vercel Dashboard

Convex Dashboard

Inngest Dashboard

E2B Dashboard

Troubleshooting

Deployment Fails

Inngest Not Syncing

AI Generation Not Working

Database Connection Issues

Webhook Failures

Production Checklist

Updating Your Deployment

Code Changes

Schema Changes

Environment Variables

Next Steps