Production Deployment

Overview

CheckThat AI consists of two deployable components:

Frontend: Static React application (deployed to GitHub Pages)
Backend: FastAPI application (deployed to cloud hosting)

This guide covers production deployment for both components, including configuration, security, and optimization.

Architecture Overview

Frontend Deployment (GitHub Pages)

The frontend is automatically deployed to GitHub Pages using GitHub Actions.

Prerequisites

GitHub Repository

Repository with GitHub Pages enabled

Custom Domain

Optional: Custom domain (CNAME file)

Secrets Configuration

GitHub repository secrets configured

Node.js 18+

For build process

Deployment Steps

Configure Repository Secrets

Add these secrets to your GitHub repository (Settings → Secrets → Actions):

Secret Name	Description	Example
`VITE_BACKEND_URL`	Backend API URL	`https://api.checkthat-ai.com`
`VITE_SUPABASE_URL`	Supabase project URL	`https://xxx.supabase.co`
`VITE_SUPABASE_ANON_KEY`	Supabase anonymous key	`eyJhbGc...`

Never commit these values to your repository. Always use GitHub Secrets.

Configure GitHub Pages

In your repository settings:

Navigate to Settings → Pages
Under Source, select GitHub Actions
Save the configuration

Set Up Custom Domain (Optional)

If using a custom domain:

Create a CNAME file in the repository root:
```
www.checkthat-ai.com
```

Configure DNS records with your domain provider:

Type: CNAME
Name: www
Value: <username>.github.io

Update vite.config.ts base URL:

export default defineConfig({
  base: 'https://www.checkthat-ai.com/',
  // ... other config
})

Deploy via GitHub Actions

The deployment workflow triggers automatically on push to main:

# .github/workflows/gh-pages-deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '18'
          cache: 'npm'
          cache-dependency-path: app/package-lock.json
      
      - name: Install dependencies
        working-directory: app
        run: npm ci
      
      - name: Build project
        working-directory: app
        env:
          VITE_BACKEND_URL: ${{ secrets.VITE_BACKEND_URL }}
          VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
          VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
        run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./app/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

Manual Deployment (Alternative)

To deploy manually without GitHub Actions:

# Build for production
cd src/app
npm run build

# Deploy to GitHub Pages
npm run deploy

# Commit and push
git add .
git commit -m "Deploy to GitHub Pages"
git push origin main

Frontend Build Configuration

The production build is configured in vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  base: 'https://www.checkthat-ai.com/',
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  build: {
    outDir: 'dist',
    sourcemap: false,  // Disable for production
    minify: 'terser',  // Minification
    rollupOptions: {
      output: {
        manualChunks: {  // Code splitting
          vendor: ['react', 'react-dom', 'react-router-dom'],
        },
      },
    },
  },
})

Backend Deployment (Cloud Hosting)

The FastAPI backend can be deployed to various cloud platforms. This guide covers general deployment principles applicable to Render, Railway, Fly.io, AWS, GCP, or Azure.

Prerequisites

Cloud Platform Account

Render, Railway, Fly.io, etc.

API Keys

OpenAI, Anthropic, Gemini, xAI

Supabase Project

Database and authentication

Python 3.8+

Runtime environment

Deployment Configuration

Set Environment Variables

Configure these environment variables in your cloud platform:

View All Environment Variables

See Environment Variables for complete list.Required:

ENV_TYPE=prod
CORS_ORIGINS=* (or specific frontend domain)
At least one model provider API key
Supabase configuration (if using authentication)

Optional:

LOG_LEVEL=INFO
Additional model provider keys

Configure CORS

Update CORS settings in api/core/config.py:

class Settings(BaseSettings):
    env_type: str = os.getenv("ENV_TYPE", "dev")
    cors_origins: str = os.getenv("CORS_ORIGINS", "")
    
    @property
    def allowed_origins(self) -> List[str]:
        if self.cors_origins:
            origins = [origin.strip() for origin in self.cors_origins.split(",")]
            if "*" in origins:
                return ["*"]  # Public API
            return origins
        
        # Production defaults
        if self.env_type == "prod":
            return ["*"]  # Or specify your frontend domain
        return ["*"]

For public APIs, use CORS_ORIGINS=*. For private APIs, specify your frontend domain:

CORS_ORIGINS=https://www.checkthat-ai.com,https://checkthat-ai.com

Set Up Application Server

The backend uses Uvicorn as the ASGI server. Configure startup command:

uvicorn api.main:app --host 0.0.0.0 --port 8000 --workers 4

For development mode:

fastapi dev main.py --host 0.0.0.0 --port 8000

For production mode:

fastapi run main.py --host 0.0.0.0 --port 8000

Install Dependencies

Ensure your cloud platform installs dependencies from requirements.txt:

# Core FastAPI and server
fastapi[standard]
uvicorn[standard]

# AI/ML Model APIs
openai
together
anthropic
google-genai
xai-sdk
instructor

# Data validation and settings
pydantic
pydantic-settings

# Database and authentication
supabase
pyjwt
requests
httpx

# Data processing and analysis
numpy
pandas
nltk
scipy
scikit-learn
tiktoken
deepeval

# Utilities
typing-extensions

Platform-Specific Deployment

Render
Railway
Docker

Create a render.yaml file:

services:
  - type: web
    name: checkthat-api
    env: python
    buildCommand: pip install -r api/requirements.txt
    startCommand: cd api && uvicorn main:app --host 0.0.0.0 --port $PORT
    envVars:
      - key: ENV_TYPE
        value: prod
      - key: PYTHON_VERSION
        value: 3.11.0

Railway automatically detects Python apps. Configure in railway.toml:

[build]
builder = "NIXPACKS"
buildCommand = "pip install -r api/requirements.txt"

[deploy]
startCommand = "cd api && uvicorn main:app --host 0.0.0.0 --port $PORT"
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY api/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY api/ .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t checkthat-api .
docker run -p 8000:8000 --env-file .env checkthat-api

Security Best Practices

API Key Management

Never commit API keys to version control
Use environment variables for all sensitive data
Rotate API keys regularly
Use different keys for development and production
Monitor API usage and set spending limits

CORS Configuration

For public APIs: Use CORS_ORIGINS=*
For private APIs: Specify exact frontend domains
Never expose internal services to public CORS
Use HTTPS for all production URLs

Authentication & Authorization

Enable Supabase Row Level Security (RLS)
Validate JWT tokens on the backend
Use Supabase service key only on backend
Never expose service keys to frontend
Implement rate limiting for API endpoints

Logging & Monitoring

Set LOG_LEVEL=INFO for production
Never log API keys or sensitive data
Monitor error rates and response times
Set up alerts for critical errors
Use structured logging (JSON format)

Environment Configuration

Set ENV_TYPE=prod for production
Use separate Supabase projects for dev/prod
Implement graceful error handling
Configure appropriate timeout values
Enable HTTPS only in production

Performance Optimization

Frontend Optimization

Build Optimization

Enable code splitting in Vite configuration
Minify JavaScript and CSS
Tree-shake unused dependencies
Use production builds (never deploy dev builds)

Asset Optimization

Compress images (use WebP format)
Lazy load components with React.lazy()
Use CDN for static assets
Enable Brotli/Gzip compression

Caching Strategy

Set appropriate cache headers
Use service workers for offline support
Cache API responses where applicable
Version static assets

Backend Optimization

Server Configuration

Use multiple Uvicorn workers:
```
uvicorn main:app --workers 4
```

Configure worker class based on workload:

--worker-class uvicorn.workers.UvicornWorker

Database Optimization

Enable connection pooling for Supabase
Use database indexes for frequent queries
Implement caching for repeated queries
Use async database operations

API Rate Limiting

Implement rate limiting middleware
Cache LLM responses when appropriate
Use streaming responses for long-running tasks
Implement request queuing for high load

Health Checks & Monitoring

Implement health check endpoints for monitoring:

# api/routes/health.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/health")
async def health_check():
    return {
        "status": "healthy",
        "version": "1.0.0",
        "environment": os.getenv("ENV_TYPE", "dev")
    }

@router.get("/readiness")
async def readiness_check():
    # Check database connection, external APIs, etc.
    return {"status": "ready"}

Deployment Checklist

Pre-Deployment

✅ All environment variables configured
✅ API keys valid and tested
✅ Database schema deployed (Supabase)
✅ Frontend built successfully
✅ Backend tested locally
✅ CORS configured correctly
✅ Security review completed

Deployment

✅ Frontend deployed to GitHub Pages
✅ Backend deployed to cloud platform
✅ Custom domain configured (if applicable)
✅ SSL/HTTPS enabled
✅ Health checks passing

Post-Deployment

✅ Test all major features
✅ Verify API connectivity
✅ Check authentication flows
✅ Monitor error logs
✅ Set up monitoring alerts
✅ Document deployment process

Troubleshooting

Frontend Not Loading

Check GitHub Pages deployment status
Verify base URL in vite.config.ts
Ensure CNAME file is correct
Check browser console for errors
Verify DNS configuration for custom domain

Backend Connection Errors

Verify backend URL in frontend environment variables
Check CORS configuration
Ensure backend is running and healthy
Verify SSL certificate is valid
Check firewall/security group rules

API Key Errors

Verify environment variables are set
Check API key validity with provider
Ensure sufficient quota/credits
Check for typos in variable names
Verify platform-specific env var syntax

Database Connection Issues

Verify Supabase URL and keys
Check database schema is deployed
Ensure Row Level Security policies are correct
Verify network connectivity
Check Supabase project status

Rollback Procedure

If deployment issues occur:

Frontend Rollback

# Revert to previous commit
git revert HEAD
git push origin main

# GitHub Actions will automatically redeploy

Backend Rollback

Most cloud platforms provide rollback options:

Render: Click “Rollback” in dashboard
Railway: Redeploy previous deployment
Docker: Run previous image version

Next Steps

Environment Variables

Complete environment variable reference

Monitoring

Set up monitoring and alerts

Scaling

Scale your deployment

Security

Advanced security configuration

Get Started

Core Concepts

Web Application

Guides

Deployment

Overview

Architecture Overview

Frontend Deployment (GitHub Pages)

Prerequisites

GitHub Repository

Custom Domain

Secrets Configuration

Node.js 18+

Deployment Steps

Frontend Build Configuration

Backend Deployment (Cloud Hosting)

Prerequisites

Cloud Platform Account

API Keys

Supabase Project

Python 3.8+

Deployment Configuration

Security Best Practices

Performance Optimization

Frontend Optimization

Backend Optimization

Health Checks & Monitoring

Deployment Checklist

Troubleshooting

Rollback Procedure

Frontend Rollback

Backend Rollback

Next Steps

Environment Variables

Monitoring

Scaling

Security

Build docs developers (and LLMs) love

Get Started

Core Concepts

Web Application

Guides

Deployment

​Overview

​Architecture Overview

​Frontend Deployment (GitHub Pages)

​Prerequisites

GitHub Repository

Custom Domain

Secrets Configuration

Node.js 18+

​Deployment Steps

​Frontend Build Configuration

​Backend Deployment (Cloud Hosting)

​Prerequisites

Cloud Platform Account

API Keys

Supabase Project

Python 3.8+

​Deployment Configuration

​Security Best Practices

​Performance Optimization

​Frontend Optimization

​Backend Optimization

​Health Checks & Monitoring

​Deployment Checklist

​Troubleshooting

​Rollback Procedure

​Frontend Rollback

​Backend Rollback

​Next Steps

Environment Variables

Monitoring

Scaling

Security

Build docs developers (and LLMs) love

Overview

Architecture Overview

Frontend Deployment (GitHub Pages)

Prerequisites

Deployment Steps

Frontend Build Configuration

Backend Deployment (Cloud Hosting)

Prerequisites

Deployment Configuration

Security Best Practices

Performance Optimization

Frontend Optimization

Backend Optimization

Health Checks & Monitoring

Deployment Checklist

Troubleshooting

Rollback Procedure

Frontend Rollback

Backend Rollback

Next Steps