Skip to content

AI Velocity Deployment Guide

This guide covers deploying your AI Velocity project using the enhanced Taskfile commands and modern deployment workflows. AI Velocity maintains all Top G deployment capabilities while adding intelligent development features.

Deployment Overview

AI Velocity offers multiple deployment strategies optimized for modern development workflows:

  1. Railway (Single Docker) - Simplest deployment
  2. Vercel + Railway - Modern separation of concerns
  3. Single Docker (Any Platform) - Maximum flexibility
  4. Separate Services - Custom platform combinations

Quick Deployment Commands

AI Velocity includes enhanced Taskfile commands for streamlined deployment:

View All Deployment Options

task deploy-help

# Single Docker to Railway (simplest)
task deploy-railway-docker

# Frontend to Vercel + Backend to Railway (modern)
task deploy-vercel-railway

# Generic single Docker (any platform)
task deploy-single-docker

# Separate services (custom platforms)
task deploy-separate-services

Environment-Specific Deployments

# Deploy to staging with tests
task deploy-staging

# Deploy to production with tests
task deploy-prod

Single Docker Deployment

Perfect for: MVPs, simple deployments, getting started quickly

# 1. Test locally first
task build-docker
task run-docker

# 2. Deploy to Railway
task deploy-railway-docker

What this does:

  1. Builds Docker image with both frontend and backend
  2. Guides Railway setup: CLI installation, login, project creation
  3. Database setup: Automatic PostgreSQL addition
  4. Environment variables: Configuration guidance
  5. Auto-deployment: Tables create automatically on startup

Complete Railway Workflow

# Enhanced Railway deployment with full guidance
task deploy-railway-complete

This command provides comprehensive deployment assistance:

  • ✅ Prerequisites check (CLI, Docker)
  • ✅ Step-by-step instructions with exact commands
  • ✅ Database auto-creation on startup
  • ✅ Environment variable guidance
  • ✅ Troubleshooting tips for common issues
  • ✅ Verification steps to confirm deployment success

Vercel + Railway (Modern Approach)

Separate Frontend and Backend

Perfect for: Production apps, teams, performance optimization

task deploy-vercel-railway

Deployment Flow:

1. Deploy Backend to Railway

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy backend
railway login --browserless
railway new
railway add --database postgres
railway up --detach

2. Generate Latest API Client

# CRITICAL: Ensure API types are current
task run-local          # Start backend locally
task generate-client    # Generate TypeScript client

3. Deploy Frontend to Vercel

# Install Vercel CLI
npm install -g vercel

# Build with Railway API URL
cd frontend
VITE_API_URL=https://your-app.railway.app npm run build

# Deploy to Vercel
vercel --prod

Platform-Specific Deployments

Digital Ocean App Platform

# Build and deploy
task build-docker
# Upload to DO App Platform via dashboard

Render

# Connect GitHub repo to Render
# Automatic Docker detection and deployment
task build-docker  # Test locally first

Heroku

# Deploy with Heroku CLI
heroku create your-app-name
heroku stack:set container
git push heroku main

Environment Configuration

AI Velocity Environment Variables

AI Velocity requires the same environment variables as Top G, with these deployment considerations:

# Core Backend Variables
db_host=your-production-db-host
db_port=25060
db_username=your-db-user
db_password=your-secure-password
db_database=your-db-name
jwt_secret_key=your-jwt-secret-32-chars-minimum

# Frontend Configuration
redirect_after_login=https://your-domain.com

# API Integration
VITE_API_URL=https://your-backend-domain.com  # For separate deployments

# OAuth & External Services
google_client_id=your-google-client-id
google_client_secret=your-google-client-secret
stripe_publishable_key=pk_live_your-stripe-key
stripe_secret_key=sk_live_your-stripe-secret

Platform Environment Setup

Railway: 

# Set via CLI
railway variables set DB_HOST=your-host
railway variables set JWT_SECRET_KEY=your-secret

# Or via Railway dashboard

Vercel: 

# Frontend environment variables
vercel env add VITE_API_URL
# Enter your backend URL: https://your-app.railway.app

AI Development Features in Production

Cursor Rules (Development Only)

Cursor Rules are development-time features and don't affect production deployment:

  • ✅ No runtime impact: Rules only assist during development
  • ✅ Not included in builds: .cursor/ folder excluded from Docker
  • ✅ Team sharing: Rules can be committed to git for team consistency
  • ✅ No server resources: Zero production overhead

Modern Design System

AI Velocity's enhanced UI components deploy seamlessly:

  • ✅ Light/Dark themes: Automatic theme detection works in production
  • ✅ StandardButton system: Optimized bundle size
  • ✅ Enhanced animations: GPU-accelerated for performance
  • ✅ Mobile-first design: Responsive across all devices

Database Migrations in Production

Automatic Migration (Cloud Platforms)

AI Velocity includes automatic table creation for cloud deployments:

# main.py - included in AI Velocity
@app.on_event("startup")
async def create_db_and_tables():
    """Create database tables on startup"""
    async with async_engine.begin() as conn:
        await conn.run_sync(SQLModel.metadata.create_all)

When to use:

  • ✅ Initial cloud deployment (Railway, Render, etc.)
  • ✅ Simple schema updates
  • ✅ Development and staging environments

Manual Migration (Production)

For complex changes requiring data migration:

# Run from local machine to production DB
task alembic-upgrade-prod

# Or create specific migration
task alembic-revision-prod -- "Your migration description"
task alembic-upgrade-prod

Pre-Deployment Testing

Local Testing Workflow

# 1. Test full development workflow
task run-local
task generate-client
task run-frontend

# 2. Test production build
task build-docker
task run-docker

# 3. Run test suites
task test-backend
task test-frontend

# 4. Verify environment setup
task check-env

Staging Deployment

# Deploy to staging with automatic testing
task deploy-staging

# This automatically:
# - Runs backend tests
# - Runs frontend tests  
# - Provides deployment guidance
# - Validates environment setup

Troubleshooting Deployment

Common Issues & Solutions

1. Database Connection Errors 

# Check environment variables
task check-env

# Verify database credentials in production
# Test connection with staging environment first

2. API Client Sync Issues 

# Always generate fresh client before frontend deployment
task run-local
task generate-client
cd frontend && npm run build

3. Build Failures 

# Test Docker build locally first
task build-docker

# Check for missing environment variables
# Verify all dependencies are installed

4. Railway Deployment Issues 

# Check Railway deployment guide for detailed troubleshooting
task deploy-railway-complete

# Common fixes:
# - Wait for database initialization
# - Check environment variable names
# - Verify domain configuration

Production Monitoring

Health Checks

Your AI Velocity deployment includes health endpoints:

# Test deployment health
curl https://your-domain.com/api/health

# Verify API functionality
curl https://your-domain.com/api/auth/current

Performance Optimization

AI Velocity is optimized for production:

  • ✅ Frontend: Vite build optimization, code splitting
  • ✅ Backend: Async FastAPI, connection pooling
  • ✅ Database: Proper indexing, migration strategies
  • ✅ Assets: Compressed images, optimized fonts

Next Steps After Deployment

  1. Configure Domain - Set up custom domain
  2. Monitor Performance - Set up logging and metrics
  3. Scale Resources - Adjust resources as needed
  4. CI/CD Pipeline - Automate deployments

Additional Resources

Your AI Velocity app is now live!

The enhanced deployment workflows make it easy to get your AI-powered application online quickly while maintaining production-grade reliability and performance.

Deploy fast, develop faster with AI Velocity. ✨