Skip to Content
Iris Saas Kit documentation is under construction.
TechnicalDeployment

Deployment

Complete deployment guide for production-ready SaaS applications using Vercel for frontend hosting and Convex for backend deployment.

🎯 Deployment Overview

Technology Stack:

  • Frontend Hosting: Vercel  (recommended)
  • Backend Platform: Convex 
  • Authentication: Convex Auth with OAuth providers
  • Database: Convex real-time database
  • File Storage: Convex file storage
  • Payments: Stripe integration

🚀 Quick Deployment Workflow

1. Development Setup

# Initial project setup
pnpm install
npx convex dev
npx @convex-dev/auth  # Convex Auth CLI setup
pnpm dev

2. Production Deployment

# Deploy backend to Convex
npx convex deploy --prod
 
# Deploy frontend to Vercel
vercel --prod

3. Environment Configuration

  • Convex: Set production environment variables
  • Vercel: Configure frontend environment variables
  • Integration: Ensure both environments are connected

🔧 Convex Backend Deployment

Production Backend Setup

Deploy to Convex Production:

# Deploy your Convex functions, schema, and configuration
npx convex deploy --prod

Set Production Environment Variables:

# Configure production environment
npx convex env set --prod AUTH_RESEND_KEY your-prod-resend-key
npx convex env set --prod AUTH_GOOGLE_CLIENT_ID your-prod-google-client-id
npx convex env set --prod AUTH_GOOGLE_CLIENT_SECRET your-prod-google-client-secret
npx convex env set --prod STRIPE_SECRET_KEY your-prod-stripe-key
npx convex env set --prod STRIPE_WEBHOOK_SECRET your-prod-webhook-secret

Key Features:

  • Automatic scaling with serverless functions
  • Real-time database with global edge caching
  • Built-in authentication with OAuth providers
  • File storage with CDN distribution

Authentication Setup

Convex Auth CLI Configuration:

# Run Convex Auth setup (includes production config)
npx @convex-dev/auth
 
# This configures:
# - SITE_URL for your production domain
# - JWT keys for authentication
# - OAuth provider settings

For detailed Convex deployment options, see the official Convex production guide .

🌐 Vercel Frontend Deployment

Vercel Setup

1. Connect Repository:

# Initialize Vercel project
npx vercel
 
# Follow prompts to:
# - Connect your Git repository
# - Configure build settings
# - Set up domains

2. Configure Build Settings:

// vercel.json (optional)
{
  "framework": "nextjs",
  "buildCommand": "pnpm build",
  "installCommand": "pnpm install",
  "devCommand": "pnpm dev"
}

3. Environment Variables:

# Set frontend environment variables
vercel env add NEXT_PUBLIC_CONVEX_URL
vercel env add NODE_ENV
 
# Or configure via Vercel Dashboard:
# Project Settings → Environment Variables

Production Environment Variables

Required Frontend Variables:

# Convex connection
NEXT_PUBLIC_CONVEX_URL=https://your-production-deployment.convex.cloud
 
# Node environment
NODE_ENV=production

Vercel automatically provides:

  • VERCEL_URL - Your deployment URL
  • VERCEL_ENV - Environment (production, preview, development)
  • SSL certificates and custom domains

Automatic Deployments

Git Integration:

  • Production deploys - Triggered by pushes to main branch
  • Preview deploys - Created for pull requests
  • Branch deploys - Optional for feature branches

For comprehensive Vercel deployment guides, see the Convex hosting documentation .

🔐 Production Environment Setup

Complete Environment Configuration

Convex Production Variables

# Core system (auto-configured by Convex Auth)
CONVEX_SITE_URL=https://your-deployment.convex.cloud
SITE_URL=https://your-domain.com
 
# Authentication
AUTH_RESEND_KEY=re_prod_xxxxxxxxxx
EMAIL_DOMAIN=@yourdomain.com
AUTH_GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-xxxxx
 
# Stripe billing
STRIPE_SECRET_KEY=sk_live_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx
 
# Team notifications (optional)
SLACK_BOT_TOKEN=xoxb-xxxxx
DISCORD_BOT_TOKEN=xxxxx
 
# Developer access
DEVELOPER_ROLE_PASSKEY=your-secure-passkey

Vercel Production Variables

# Convex connection (required)
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
 
# Node environment (automatic)
NODE_ENV=production

Environment Security

Best Practices:

  • Never expose secrets in NEXT_PUBLIC_* variables
  • Use different keys for development and production
  • Rotate secrets regularly using dashboard interfaces
  • Monitor access logs for unauthorized usage

📋 Deployment Checklist

Pre-Deployment Verification

Backend (Convex):
 
- [ ] All environment variables configured in production
- [ ] Database schema deployed and validated
- [ ] Authentication providers configured (Google OAuth)
- [ ] Stripe webhooks configured for production domain
- [ ] Email templates tested with production Resend account
- [ ] File storage permissions configured correctly
 
Frontend (Vercel):
 
- [ ] NEXT_PUBLIC_CONVEX_URL points to production deployment
- [ ] Build process completes without errors
- [ ] All API routes functional
- [ ] Authentication flow works end-to-end
- [ ] File uploads and downloads working
- [ ] Stripe payment flow functional
 
Integration:
 
- [ ] Custom domain configured (if applicable)
- [ ] SSL certificates active
- [ ] DNS records pointing correctly
- [ ] Email delivery working from production domain
- [ ] Webhook endpoints accessible
- [ ] Error monitoring configured

Post-Deployment Testing

Critical User Flows:
 
- [ ] User sign-up with email verification
- [ ] OAuth sign-in (Google)
- [ ] Workspace creation and management
- [ ] File upload (profile pictures, workspace logos)
- [ ] Stripe subscription flow
- [ ] Email notifications delivery
- [ ] Admin dashboard access
- [ ] Password reset functionality
 
Performance:
 
- [ ] Page load times under 3 seconds
- [ ] API response times under 500ms
- [ ] Real-time updates working
- [ ] Mobile responsiveness
- [ ] Cross-browser compatibility

🔄 Continuous Deployment

Automated Deployment Workflow

Recommended Git Workflow:

# Development
git checkout -b feature/new-feature
# ... make changes
git push origin feature/new-feature
# → Creates Vercel preview deployment
 
# Production
git checkout main
git merge feature/new-feature
git push origin main
# → Triggers production deployment

CI/CD Integration:

# GitHub Actions example (optional)
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy Convex
        run: npx convex deploy --prod
        env:
          CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}
      - name: Deploy Vercel
        run: vercel --prod
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

Preview Deployments

Convex Preview Deployments:

  • Automatic preview environments for pull requests
  • Isolated backend deployments for testing
  • Easy collaboration on feature branches

Vercel Preview Deployments:

  • Automatic frontend previews for pull requests
  • Shareable URLs for stakeholder review
  • Integration testing with Convex preview backends

📊 Monitoring & Maintenance

Built-in Monitoring

Convex Dashboard:

  • Function performance and error rates
  • Database query analytics
  • Authentication metrics
  • File storage usage

Vercel Analytics:

  • Page performance and Core Web Vitals
  • User analytics and traffic patterns
  • Build and deployment logs
  • Error tracking and alerts

Production Maintenance

Regular Tasks:

  • Monitor environment variables for expiration
  • Update dependencies and security patches
  • Review error logs and performance metrics
  • Backup critical data using Convex export tools
  • Test disaster recovery procedures

Scaling Considerations:

  • Convex auto-scales based on usage
  • Vercel auto-scales frontend traffic
  • Monitor Stripe billing and subscription limits
  • Review file storage usage and costs

🚀 Going Live

Final Production Steps

1. Domain Configuration:

# Configure custom domain in Vercel
vercel domains add yourdomain.com
 
# Update SITE_URL in Convex
npx convex env set --prod SITE_URL https://yourdomain.com

2. SSL and Security:

  • Vercel automatically provides SSL certificates
  • Configure security headers and CORS policies
  • Set up proper CSP headers for production

3. Launch Verification:

  • Test all critical user flows
  • Verify email deliverability
  • Confirm payment processing
  • Check analytics and monitoring

4. Go-Live Checklist:

- [ ] Custom domain active and SSL configured
- [ ] All environment variables verified in production
- [ ] Database seeded with initial data (if needed)
- [ ] Stripe in live mode with production keys
- [ ] Email templates tested from production domain
- [ ] Analytics and monitoring active
- [ ] Error reporting configured
- [ ] Team access configured for production management

This deployment guide provides the essential steps to deploy your SaaS boilerplate to production. For detailed deployment configurations and advanced options, refer to the official Convex CLI documentation  and Convex production deployment guides .

Last updated on
Task Driven DevelopmentFunction Reference