Vercel Deployment Guide for do.dev Application

This guide covers deploying the do.dev application to Vercel with Convex backend.

Prerequisites

1. A Vercel account
2. A Convex account and project
3. The repository connected to Vercel
4. Convex CLI installed locally

Deployment Architecture

• Frontend: Next.js application deployed to Vercel
• Backend: Convex (serverless functions and database)
• Build System: pnpm workspace with Turborepo

Environment Variables

Required Environment Variables

# Convex Deployment URL (from Convex dashboard)
NEXT_PUBLIC_CONVEX_URL="https://your-project.convex.cloud"

# Auth.js Secret (generate with: openssl rand -base64 32)
AUTH_SECRET="your-auth-secret"

# Google OAuth (if using)
AUTH_GOOGLE_ID="your-google-client-id"
AUTH_GOOGLE_SECRET="your-google-client-secret"

# PostHog Analytics (optional)
NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key"
NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"

App-Specific Variables

For DNS Management:

TECHNITIUM_DNS_URL="http://10.3.3.3:5380"
TECHNITIUM_USERNAME="admin"
TECHNITIUM_PASSWORD="your-password"

Step-by-Step Deployment

1. Deploy Convex Backend

# Navigate to the tools/convex directory
cd tools/convex

# Deploy to production
npx convex deploy

2. Import Project to Vercel

1. Go to https://vercel.com/new
2. Import your GitHub repository
3. Select the root directory (monorepo root)

3. Configure Build Settings

Create a vercel.json in the project root:

{
  "buildCommand": "pnpm --filter dodev build",
  "outputDirectory": "apps/dodev/.next",
  "installCommand": "pnpm install",
  "framework": "nextjs"
}

4. Add Environment Variables

In Vercel Project Settings > Environment Variables:

1. Add all required variables
2. Ensure they're set for all environments (Production, Preview, Development)
3. Copy the NEXT_PUBLIC_CONVEX_URL from your Convex dashboard

5. Deploy

Click Deploy. The build process will:

1. Install dependencies with pnpm
2. Build the dodev Next.js application
3. Deploy to Vercel's edge network

Alternative Configuration

Root Directory Configuration

If you prefer to set the root directory to the app folder:

1. Go to Project Settings
2. Set Root Directory to: apps/dodev
3. Update build command to just: pnpm build
4. Set output directory to: .next

Troubleshooting

Build Failures

1. "Module not found" errors

   • Ensure all workspace dependencies are properly linked
   • Check that pnpm install runs from the project root

2. "NEXT_PUBLIC_CONVEX_URL is not defined"

   • Add the environment variable in Vercel dashboard
   • Redeploy after adding variables

3. Build timeouts

   • Consider using Vercel's build cache
   • Optimize build by excluding unused workspaces

Convex Connection Issues

1. "Failed to connect to Convex"

   • Verify NEXT_PUBLIC_CONVEX_URL is correct
   • Ensure Convex project is deployed
   • Check that the URL includes https://

2. Authentication failures

   • Verify AUTH_SECRET matches across environments
   • Ensure OAuth redirect URLs are configured for Vercel domains

Performance Optimization

Build Caching

Add to vercel.json:

{
  "buildCommand": "pnpm --filter dodev build",
  "outputDirectory": "apps/dodev/.next",
  "installCommand": "pnpm install --frozen-lockfile"
}

Ignored Build Step

To optimize builds when only documentation changes, add:

{
  "github": {
    "silent": true
  },
  "ignoreCommand": "git diff HEAD^ HEAD --quiet -- apps/dodev"
}

Production Checklist

• Environment variables set for production
• Convex backend deployed
• Custom domain configured (if applicable)
• Preview deployments working
• Build optimizations applied
• Error tracking configured (e.g., Sentry)
• Analytics configured (PostHog)

Security Considerations

1. Environment Variables

   • Never commit .env files
   • Use Vercel's encrypted environment variables
   • Rotate AUTH_SECRET regularly

2. API Keys

   • Limit OAuth redirect URLs to your Vercel domains
   • Use environment-specific API keys

3. Branch Protection

   • Enable protection for main/production branches
   • Require PR reviews before deployment

Monitoring

After deployment:

• Monitor build times in Vercel dashboard
• Check Function logs for API errors
• Monitor Convex dashboard for backend performance
• Use Vercel Analytics for frontend metrics

Common Patterns

Deploying Preview Branches

Vercel automatically creates preview deployments for PRs. Ensure:

1. Preview environment variables are set
2. Convex has a dev/preview instance (optional)
3. OAuth providers accept preview URLs

Rollback Strategy

1. Use Vercel's instant rollback feature
2. Convex maintains version history
3. Keep environment variables versioned

For additional deployment instructions, see the project README.md file.