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:

Most Popular Options¶

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

Quick Deployment Commands¶

AI Velocity includes enhanced Taskfile commands for streamlined deployment:

View All Deployment Options¶

Bash
1	`task deploy-help`

Most Popular Deployments¶

Bash
# 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¶

Bash
# Deploy to staging with tests
task deploy-staging

# Deploy to production with tests
task deploy-prod

Railway Deployment (Recommended)¶

Single Docker Deployment¶

Perfect for: MVPs, simple deployments, getting started quickly

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

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

What this does:

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

Complete Railway Workflow¶

Bash
1 2	`# 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

Bash
1	`task deploy-vercel-railway`

Deployment Flow:

1. Deploy Backend to Railway¶

Bash
# 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¶

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

3. Deploy Frontend to Vercel¶

Bash
# 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¶

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

Render¶

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

Heroku¶

Bash
# 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:

Bash
# 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:

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

# Or via Railway dashboard

Vercel:

Bash
# 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:

Python
# 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:

Bash
# 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¶

Bash
# 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¶

Bash
# 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

Bash
# Check environment variables
task check-env

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

2. API Client Sync Issues

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

3. Build Failures

Bash
# Test Docker build locally first
task build-docker

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

4. Railway Deployment Issues

Bash
# 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:

Bash
# 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¶

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

Additional Resources¶

Railway Deployment Guide - Detailed Railway setup
Configuration Guide - Environment variables
API Documentation - API endpoints and testing

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. ✨