TinyKit Docs

Deployment Guide

This guide covers deploying TinyKit SaaS to production environments, including Vercel deployment, environment configuration, and production best practices.

Deployment Overview

TinyKit SaaS uses a modern serverless deployment strategy:

  • Frontend: Deployed to Vercel with Edge Runtime optimization
  • Backend: Convex managed serverless functions with automatic scaling
  • Database: Convex managed database with built-in real-time capabilities
  • Assets: Static assets served via Vercel's global CDN

Pre-Deployment Checklist

Code Quality Verification

Before deploying, ensure all quality checks pass:

# These MUST pass with zero errors before deployment
pnpm lint             # ESLint validation
pnpm typecheck        # TypeScript strict mode validation
pnpm build            # Production build test

Environment Configuration

Verify all required environment variables are configured for production.

Vercel Deployment

1. Prepare Repository

# Ensure code is committed and pushed
git add .
git commit -m "feat: prepare for production deployment"
git push origin main

2. Connect to Vercel

  1. Import Project:

    • Visit vercel.com/new
    • Connect your GitHub repository
    • Select the TinyKit SaaS repository

  2. Configure Build Settings:

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

3. Environment Variables

Configure these environment variables in Vercel dashboard:

Required Variables

# Convex Configuration
CONVEX_DEPLOYMENT=prod:your-project-name
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site

# Site Configuration
NEXT_PUBLIC_SITE_URL=https://yourdomain.com

# OAuth Providers (Production URLs)
GITHUB_CLIENT_ID=your_production_github_id
GITHUB_CLIENT_SECRET=your_production_github_secret
GOOGLE_CLIENT_ID=your_production_google_id
GOOGLE_CLIENT_SECRET=your_production_google_secret

Convex Environment Variables (Backend-Only)

Set these in Convex for production:

# Stripe (all keys go in Convex - no frontend keys needed)
npx convex env set STRIPE_SECRET_KEY sk_live_... --prod
npx convex env set STRIPE_WEBHOOK_SECRET whsec_production... --prod

# Email (optional)
npx convex env set RESEND_API_KEY re_production_api_key --prod

Optional Variables

# Analytics (if enabled)
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

4. Deploy

Click Deploy in Vercel dashboard. The deployment process will:

  1. Install Dependencies: Run pnpm install
  2. Build Application: Execute pnpm run build
  3. Deploy to Edge: Distribute to Vercel's global CDN
  4. Generate Domain: Provide production URL

Convex Production Setup

1. Create Production Deployment

# Create production deployment
npx convex deploy --prod

# This creates a new production deployment separate from development

2. Configure Production Environment Variables

Set production environment variables in Convex:

# Email Configuration
npx convex env set RESEND_API_KEY re_production_api_key --prod
npx convex env set EMAIL_FROM "Your App <noreply@yourdomain.com>" --prod
npx convex env set SITE_URL https://yourdomain.com --prod

3. Database Migration

If migrating from development to production:

# Export development data (if needed)
npx convex export --output dev-data.jsonl

# Import to production (if needed)
npx convex import --prod dev-data.jsonl

Stripe Production Configuration

1. Switch to Live Mode

  1. Stripe Dashboard: Toggle to Live mode (top-left)
  2. Get Live API Keys: Copy live API keys from dashboard
  3. Update Environment Variables: Replace test keys with live keys in Vercel

2. Configure Production Webhooks

  1. Create Webhook Endpoint:

    • Go to Stripe Webhooks
    • Click Add endpoint
    • URL: https://yourdomain.com/stripe
    • Events: Select all billing-related events

  2. Configure Webhook Secret:

    • Copy the webhook signing secret from the endpoint page
    • Set in Convex production environment: 
      npx convex env set STRIPE_WEBHOOK_SECRET whsec_... --prod

3. Customer Portal Configuration

Important: Configure Customer Portal for production:

  1. Go to Customer Portal Settings
  2. Business Information: Add production business details
  3. Branding: Upload logo and customize appearance
  4. Features: Enable subscriptions, payment methods, billing history
  5. Support: Add production support email and links
  6. Save Configuration: Activate for live mode

4. Product Sync

Use the admin interface to sync products to production:

  1. Access Admin Panel: Navigate to /admin/products
  2. Sync Products: Use the sync interface to create/import products
  3. Verify Products: Confirm all products and pricing are correct

OAuth Provider Configuration

Update OAuth redirect URLs for production domain:

GitHub OAuth

  1. Go to GitHub OAuth Apps
  2. Update Authorization callback URL: https://yourdomain.com/api/auth/callback/github

Google OAuth

  1. Go to Google Cloud Console
  2. Update Authorized redirect URIs: https://yourdomain.com/api/auth/callback/google

Apple OAuth

  1. Go to Apple Developer Portal
  2. Update Redirect URIs: https://yourdomain.com/api/auth/callback/apple

DNS and Domain Configuration

1. Custom Domain Setup

In Vercel dashboard:

  1. Add Domain: Go to Project Settings → Domains
  2. Add Custom Domain: Enter your domain (e.g., yourdomain.com)
  3. Configure DNS: Add DNS records as instructed by Vercel
  4. SSL Certificate: Vercel automatically provisions SSL

2. DNS Configuration

Add these DNS records at your domain provider:

Type: CNAME
Name: www
Value: cname.vercel-dns.com

Type: A
Name: @
Value: 76.76.19.19

Email System Production Setup

1. Resend Production Configuration

  1. Production API Key:

    • Create production API key at resend.com/api-keys
    • Update RESEND_API_KEY and Convex RESEND_API_KEY

  2. Domain Verification:

    • Add your domain in Resend dashboard
    • Configure DNS records for domain verification
    • Wait for verification to complete

  3. Email From Address:

    • Use verified domain: noreply@yourdomain.com
    • Update EMAIL_FROM in both environments

2. Test Email Delivery

# Test password reset emails
# Visit your production site and try password reset

# Test notification emails
# Use admin interface to send test notifications

SEO and Performance Configuration

1. SEO Setup

Update SEO configuration for production:

  • Site URLs: Ensure all URLs use production domain
  • Sitemap: Verify sitemap is accessible at /sitemap.xml
  • Robots.txt: Confirm robots.txt allows crawling
  • OG Images: Test Open Graph images are generating correctly

2. Performance Optimization

Vercel automatically provides:

  • Global CDN: Static assets distributed globally
  • Edge Runtime: Fast serverless function execution
  • Image Optimization: Next.js automatic image optimization
  • Compression: Automatic gzip/brotli compression

Monitoring and Observability

1. Application Monitoring

Convex Monitoring

  • Function Performance: Monitor via Convex dashboard
  • Error Tracking: View function errors and performance
  • Database Metrics: Monitor query performance and usage

Vercel Monitoring

  • Function Logs: View serverless function execution logs
  • Performance Metrics: Monitor response times and success rates
  • Error Tracking: Built-in error monitoring and alerting

2. External Monitoring

Consider adding:

  • Uptime Monitoring: Services like Uptime Robot or Pingdom
  • Error Tracking: Sentry for detailed error tracking
  • Analytics: Google Analytics or similar for user analytics

Security Hardening

1. Environment Security

  • Secret Rotation: Regularly rotate API keys and secrets
  • Environment Isolation: Strict separation between dev/prod environments
  • Access Control: Limit who has access to production environments

2. Application Security

  • HTTPS Enforcement: Vercel automatically enforces HTTPS
  • Content Security Policy: Configure CSP headers in Next.js
  • Rate Limiting: Implement rate limiting for sensitive endpoints
  • Input Validation: Ensure all inputs are validated on server-side

Backup and Recovery

1. Database Backup

Convex provides automatic backups, but you can also:

# Manual backup
npx convex export --output backup-$(date +%Y%m%d).jsonl --prod

# Schedule regular backups
# Set up automated script to run exports periodically

2. Configuration Backup

  • Environment Variables: Document all production environment variables
  • Stripe Configuration: Export Stripe configuration and webhook settings
  • DNS Records: Document all DNS configurations

Troubleshooting Production Issues

Common Deployment Issues

Build Failures

# Check build logs in Vercel dashboard
# Common issues:
- TypeScript errors (run `pnpm typecheck` locally)
- ESLint errors (run `pnpm lint` locally)
- Missing environment variables

Runtime Errors

# Check Vercel function logs
# Check Convex function logs in dashboard
# Verify environment variables are set correctly

Database Connection Issues

# Verify Convex deployment URL
# Check NEXT_PUBLIC_CONVEX_URL is correct
# Ensure Convex production deployment is active

Webhook Issues

# Check Stripe webhook delivery in dashboard
# Verify webhook URL is accessible
# Confirm webhook signing secret matches

Debug Commands

# Check deployment status
npx convex status --prod

# View production logs
npx convex logs --tail --prod

# Test production API endpoints
curl https://yourdomain.com/api/health

Post-Deployment Verification

1. Functionality Testing

  • Authentication: Test sign up/in with all providers
  • Team Features: Create team, invite members, test permissions
  • Billing: Test subscription flow, webhooks, customer portal
  • Notifications: Test email delivery and in-app notifications
  • Real-time Features: Test notifications and live updates

2. Performance Testing

  • Page Load Times: Verify fast page loads globally
  • API Response Times: Check function performance in Convex dashboard
  • Database Performance: Monitor query performance
  • Email Delivery: Verify email delivery times and success rates

3. SEO Verification

  • Search Console: Set up Google Search Console
  • Sitemap Submission: Submit sitemap to search engines
  • OG Images: Test social media previews
  • Page Titles: Verify all pages have appropriate titles

← Previous: Development | Next: API Reference →

API Reference

This document provides comprehensive reference for TinyKit SaaS's API patterns, function conventions, and development standards.

Development Guide

This guide covers the development workflow, commands, debugging techniques, and best practices for working with TinyKit SaaS.

On this page

Deployment OverviewPre-Deployment ChecklistCode Quality VerificationEnvironment ConfigurationVercel Deployment1. Prepare Repository2. Connect to Vercel3. Environment VariablesRequired VariablesConvex Environment Variables (Backend-Only)Optional Variables4. DeployConvex Production Setup1. Create Production Deployment2. Configure Production Environment Variables3. Database MigrationStripe Production Configuration1. Switch to Live Mode2. Configure Production Webhooks3. Customer Portal Configuration4. Product SyncOAuth Provider ConfigurationGitHub OAuthGoogle OAuthApple OAuthDNS and Domain Configuration1. Custom Domain Setup2. DNS ConfigurationEmail System Production Setup1. Resend Production Configuration2. Test Email DeliverySEO and Performance Configuration1. SEO Setup2. Performance OptimizationMonitoring and Observability1. Application MonitoringConvex MonitoringVercel Monitoring2. External MonitoringSecurity Hardening1. Environment Security2. Application SecurityBackup and Recovery1. Database Backup2. Configuration BackupTroubleshooting Production IssuesCommon Deployment IssuesDebug CommandsPost-Deployment Verification1. Functionality Testing2. Performance Testing3. SEO Verification

Ship your startup faster. In minutes.

Get TinyKit SaaS