Skip to main content

Deployment Guide

Complete step-by-step guide for deploying the AI Agentification Platform to production.

Table of Contents​

Pre-Deployment Checklist​

Before deploying to production, ensure you have:

Required Accounts​

  • Supabase account with production project created
  • Vercel account (free tier works)
  • GitHub repository with your code
  • Custom domain (optional, but recommended)

Production Database​

  • Production Supabase project created (separate from development)
  • All database migrations run in production database
  • Database tables verified in Supabase Table Editor
  • RLS policies enabled on all tables
  • At least one admin user created

Environment Variables Ready​

  • Production Supabase URL and keys
  • Strong SECRET_KEY generated (not dev key!)
  • Strong JWT_SECRET generated (not dev key!)
  • Email service configured (if using email features)
  • All API keys for external services (YouTube, Cloudinary, etc.)

Code Ready​

  • All features tested locally
  • No console.log or debug code in production builds
  • All TODO comments resolved or documented
  • Error handling implemented for all API calls
  • Loading states implemented for all async operations

Production Environment Setup​

1. Create Production Supabase Project​

Why Separate Projects?​

  • Development: For testing, frequent schema changes, fake data
  • Production: For real users, stable schema, real data

Setup Steps​

  1. Go to supabase.com/dashboard
  2. Click "New Project"
  3. Choose settings:
    • Name: "AI Agentification Platform - Production"
    • Database Password: Generate strong password and save it
    • Region: Closest to your users (e.g., US East, EU West)
    • Pricing Plan: Free tier works, upgrade as needed
  4. Wait for project to initialize (~2 minutes)

2. Run Production Database Migrations​

  1. In production Supabase project, go to SQL Editor
  2. Run each migration file from supabase/migrations/ in order:
-- Example: Run each file one by one
-- File: 001_initial_schema.sql
-- File: 002_add_rls_policies.sql
-- File: 003_create_views.sql
-- etc.
  1. Verify in Table Editor that all tables exist
  2. Check Database → Policies that RLS is enabled

3. Create Admin User​

Option A: Via Supabase Dashboard​

  1. Go to Authentication → Users
  2. Click "Add User" → "Create New User"
  3. Enter email and password
  4. After user is created, click on the user
  5. Edit User Metadata and add:
{
  "role": "admin",
  "name": "Admin User"
}
  1. Save changes

Option B: Via SQL​

-- Create admin user in auth.users (use Supabase Auth UI instead)
-- Then update metadata:
UPDATE auth.users
SET raw_user_meta_data = jsonb_set(
  raw_user_meta_data,
  '{role}',
  '"admin"'
)
WHERE email = 'your-admin@email.com';

4. Generate Production Secrets​

# Generate SECRET_KEY (copy the output)
openssl rand -hex 32

# Generate JWT_SECRET (copy the output)
openssl rand -hex 32

Save these values - you'll need them for Vercel environment variables.

Deploying to Vercel​

1. Connect GitHub Repository​

  1. Go to vercel.com
  2. Click "Add New" → "Project"
  3. Import your GitHub repository
  4. Click "Import"

2. Configure Build Settings​

Vercel should auto-detect the settings, but verify:

Build Command:     npm run build
Output Directory:  dist
Install Command:   npm install

3. Set Environment Variables​

Click "Environment Variables" and add:

Required Variables​

# Environment
NODE_ENV=production

# Supabase (PRODUCTION PROJECT)
VITE_SUPABASE_URL=https://your-prod-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Flask Secrets (USE GENERATED VALUES FROM STEP 4)
SECRET_KEY=<your-generated-secret-key>
JWT_SECRET=<your-generated-jwt-secret>

# Database
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres

Optional Variables (if using features)​

# Email
EMAIL_ENABLED=true
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# YouTube API
VITE_YOUTUBE_API_KEY=your_youtube_api_key

# Cloudinary
VITE_CLOUDINARY_CLOUD_NAME=your_cloud_name
VITE_CLOUDINARY_UPLOAD_PRESET=your_upload_preset

# Analytics
VITE_GA4_MEASUREMENT_ID=G-XXXXXXXXXX

Important:

  • Set all variables to apply to "Production" environment
  • Don't set variables to "Preview" unless you want different values for preview deploys

4. Deploy​

  1. Click "Deploy"
  2. Wait for build to complete (~2-5 minutes)
  3. Check build logs for any errors
  4. Once complete, Vercel will show your deployment URL

5. Custom Domain (Optional)​

  1. In Vercel project, go to Settings → Domains
  2. Add your custom domain (e.g., agentification.academy)
  3. Follow Vercel's instructions to add DNS records
  4. Wait for DNS propagation (~5-60 minutes)
  5. Vercel automatically provisions SSL certificate

Post-Deployment Verification​

1. Test Basic Functionality​

Homepage​

  • Visit your production URL
  • Homepage loads without errors
  • Check browser console for errors
  • All images and assets load

Authentication​

  • Sign up with a new account
  • Check email for verification link
  • Verify email and log in
  • Log out and log back in

Admin Dashboard​

  • Log in with admin account
  • Navigate to /admin
  • Verify admin panel loads
  • Check that data loads from database

2. Test API Endpoints​

# Replace with your production URL
PROD_URL="https://your-site.vercel.app"

# Test public endpoint
curl "$PROD_URL/api/content?section=homepage_content"

# Test that it returns JSON data

3. Monitor Vercel Function Logs​

  1. Go to Vercel Dashboard → Your Project
  2. Click "Functions" tab
  3. Check for any errors in recent invocations
  4. Look for:
    • Database connection errors
    • Authentication errors
    • Missing environment variables

4. Check Supabase Logs​

  1. Go to Supabase Dashboard → Logs
  2. Check API logs for:
    • Successful queries
    • Any permission errors (RLS issues)
    • Connection errors

5. Test End-to-End User Flow​

  • New user signs up
  • User verifies email
  • User enrolls in a course
  • User can access course content
  • Progress is tracked correctly
  • User can update profile

Troubleshooting​

Build Failures​

"Command failed: npm run build"​

# Check the build log for specific errors
# Common issues:
# - TypeScript errors
# - Missing dependencies
# - Environment variables not set

# Fix locally first:
npm run build

# If it works locally but fails on Vercel:
# - Check Vercel's Node.js version matches yours
# - Ensure package-lock.json is committed

"Module not found"​

# Ensure all dependencies are in package.json (not devDependencies)
# Move build dependencies to "dependencies":
npm install --save-prod <package-name>

Runtime Errors​

500 Internal Server Error​

# Check Vercel Function logs for Python errors
# Common causes:
# - Missing environment variables
# - Database connection errors
# - Import errors in Python code

# Test backend locally:
SUPABASE_URL="prod-url" \
SUPABASE_SERVICE_ROLE_KEY="prod-key" \
python main.py

"Invalid API credentials"​

# Verify environment variables in Vercel:
# 1. Settings → Environment Variables
# 2. Check all required variables are set
# 3. Redeploy after adding variables

Database Connection Errors​

# Verify DATABASE_URL is correct
# Check Supabase project is not paused (free tier pauses after inactivity)
# Test connection from local machine:
psql $DATABASE_URL

Authentication Issues​

Users Can't Sign Up​

  • Check Supabase Auth settings
  • Verify email templates are configured
  • Check SMTP settings if using custom email

Users Can't Access Protected Routes​

  • Verify JWT_SECRET matches in all environments
  • Check RLS policies in Supabase
  • Ensure token validation works in backend

Performance Issues​

Slow Initial Load​

  • Check that build is optimized (minified)
  • Enable CDN caching in Vercel
  • Optimize images (use Cloudinary or WebP format)
  • Implement code splitting

Slow API Responses​

  • Check Supabase query performance
  • Add database indexes for frequently queried columns
  • Implement caching with TanStack Query
  • Use Vercel Edge Functions for critical endpoints

Maintenance​

Regular Tasks​

Daily​

  • Monitor error logs in Vercel
  • Check Supabase API usage
  • Review user signups and activity

Weekly​

  • Check for security updates in dependencies
  • Review and rotate API keys if needed
  • Backup database (Supabase does this automatically)

Monthly​

  • Update dependencies: npm update
  • Review and optimize slow queries
  • Check Vercel and Supabase usage limits
  • Review and improve documentation

Updating Production​

For Code Changes​

# 1. Test thoroughly in development
npm run dev

# 2. Build and test production build locally
npm run build
npm run preview

# 3. Commit and push to main branch
git add .
git commit -m "feat: your feature description"
git push origin main

# 4. Vercel automatically deploys from main branch
# Monitor deployment in Vercel dashboard

For Database Changes​

# 1. Create migration file
# supabase/migrations/YYYYMMDD_description.sql

# 2. Test in development Supabase project
# Run in SQL Editor

# 3. Run in production Supabase project
# IMPORTANT: Can't undo, so test thoroughly first!

# 4. Update code if schema changed
# 5. Deploy updated code

Rollback Procedure​

If something goes wrong:

  1. Instant Rollback (Vercel):

    • Go to Vercel Dashboard → Deployments
    • Find the last working deployment
    • Click "..." → "Promote to Production"

  2. Database Rollback (if needed):

    • Supabase keeps automatic backups
    • Go to Database → Backups
    • Restore to previous state
    • Warning: This will lose recent data changes!

Security Considerations​

Secrets Management​

  • Never commit .env files with real credentials
  • Rotate secrets periodically (quarterly recommended)
  • Use strong passwords for admin accounts
  • Enable 2FA on Supabase and Vercel accounts

Monitoring​

  • Set up Vercel alerts for failed deployments
  • Monitor Supabase quotas to avoid service disruption
  • Review API logs regularly for suspicious activity
  • Implement rate limiting for public endpoints

Updates​

  • Keep dependencies up to date
  • Monitor security advisories
  • Test updates in development before deploying
  • Subscribe to Vercel and Supabase status updates

Cost Optimization​

Vercel (Free Tier Limits)​

  • 100GB bandwidth per month
  • Serverless function execution: 100GB-hours
  • Edge functions: 500,000 invocations

If you exceed:

  • Upgrade to Pro plan ($20/month)
  • Optimize function execution time
  • Implement caching to reduce API calls

Supabase (Free Tier Limits)​

  • 500MB database storage
  • 2GB bandwidth per month
  • 50MB file storage

If you exceed:

  • Upgrade to Pro plan ($25/month)
  • Optimize database queries
  • Clean up old/unused data
  • Use Cloudinary for media storage

Next Steps​

  • Set up monitoring with error tracking (e.g., Sentry)
  • Configure automated backups beyond Supabase defaults
  • Implement CI/CD testing before deployment
  • Add performance monitoring (e.g., Vercel Analytics)
  • Create staging environment for testing before production

Support Resources​