Deployment Guide - GitaChat

Overview

GitaChat uses a split deployment architecture:

Frontend: Deployed to Vercel (Next.js optimized hosting)
Backend: Deployed to Railway (Python/FastAPI with GPU support)

This guide walks you through deploying both services to production.

Architecture

Frontend on Vercel

Next.js 15 with App Router
Automatic deployments from Git
Edge network distribution
Zero-config setup

Backend on Railway

FastAPI with Uvicorn
Automatic HTTPS
Environment variable management
Persistent deployments

Prerequisites

Before deploying, ensure you have:

Git Repository

Code pushed to GitHub, GitLab, or Bitbucket

API Keys

All required API keys ready (see Environment Variables)

Accounts Created

Deploy Backend to Railway

Deploy the FastAPI backend first, as the frontend needs the backend URL.

Create new Railway project

Log in to Railway
Click New Project
Select Deploy from GitHub repo
Authorize Railway to access your repository
Select your GitaChat repository

Configure root directory

Since the backend code is in the backend/ subdirectory:

Go to Settings
Under Source, set Root Directory to backend
Click Save

Set environment variables

Go to Variables tab
Add the following variables:

PINECONE_API_KEY=xxxxx-xxxxx-xxxxx
PINECONE_INDEX=gitachat
GPT_KEY=sk-xxxxx

See Environment Variables for details on obtaining these keys.

Configure deployment settings

Railway should auto-detect Python and use the Procfile. Verify:

Go to Settings > Deploy
Ensure Build Command is empty (uses Procfile)
Start Command should reference: web: uvicorn main:app --host 0.0.0.0 --port $PORT

Your Procfile should contain:

web: uvicorn main:app --host 0.0.0.0 --port $PORT

Deploy and get URL

Railway will automatically deploy your backend
Once deployed, go to Settings > Networking
Click Generate Domain to get a public URL
Your backend will be available at: https://your-app.up.railway.app
Test the health endpoint: https://your-app.up.railway.app/health

Expected response: {"status": "ok"}

Railway Configuration Tips

Resource Usage

Monitor your usage:

Check Metrics tab for CPU/RAM
Model loading takes ~400MB RAM
First request loads the model (slow)
Subsequent requests are fast

Logs & Debugging

View logs in real-time:

Click Deployments > Latest deployment
View logs to debug issues
Check model loading messages
Monitor API request errors

Deploy Frontend to Vercel

Import project to Vercel

Log in to Vercel
Click Add New > Project
Import your Git repository
Vercel will detect it’s a Next.js project

Configure root directory

Since the frontend code is in the frontend/ subdirectory:

Under Build & Development Settings
Set Root Directory to frontend
Keep other settings as default (Vercel auto-detects Next.js)

Set environment variables

Under Environment Variables, add:

BACKEND_URL=https://your-app.up.railway.app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxxxx
CLERK_SECRET_KEY=sk_live_xxxxx
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxxxx

Use your Railway backend URL (from previous step) for BACKEND_URL. Use production/live keys for Clerk, not test keys.

Deploy

Click Deploy
Vercel will build and deploy your frontend
Once complete, you’ll get a production URL: https://your-app.vercel.app
Set up a custom domain (optional) under Settings > Domains

Vercel Configuration Tips

Automatic Deployments

Every push to main auto-deploys
Preview deployments for PRs
Rollback to previous deployments
View deployment history

Custom Domain

Add your custom domain:

Go to Settings > Domains
Add domain (e.g., gitachat.org)
Configure DNS records
Automatic HTTPS with SSL

CORS Configuration

Ensure your backend allows requests from your frontend domain.

Update CORS origins in backend

Edit backend/main.py to include your production frontend URL:

main.py

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:3000",
        "https://gitachat.org",
        "https://www.gitachat.org",
        "https://your-app.vercel.app",  # Add your Vercel URL
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "OPTIONS"],
    allow_headers=["Content-Type", "Authorization"],
)

Commit and push

git add backend/main.py
git commit -m "Add production frontend URL to CORS"
git push

Railway will automatically redeploy with the updated CORS settings.

Verify Deployment

Backend Health Check

Test your Railway backend:

curl https://your-app.up.railway.app/health

Expected: {"status": "ok"}

Frontend Test

Visit your Vercel URL
Try asking a question
Verify it returns a verse
Check browser console for errors

End-to-End Test

# Test the query endpoint with your production backend
curl -X POST https://your-app.up.railway.app/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I overcome fear?"}'

You should receive a verse with contextual commentary.

Production Checklist

Security

Use production API keys (not test keys)
Enable rate limiting on Railway
Set up monitoring and alerts
Configure Clerk production settings
Review Supabase RLS policies

Performance

Test backend cold start time
Monitor Railway resource usage
Check Vercel analytics
Optimize images (Next.js Image)
Enable caching where appropriate

Monitoring

Set up error tracking (e.g., Sentry)
Monitor API usage (OpenAI, Pinecone)
Check Railway logs regularly
Review Vercel deployment logs
Track user queries in Supabase

Backup & Recovery

Troubleshooting

Backend Not Responding

Symptoms: 503 errors, timeoutsSolutions:

Check Railway deployment status
View logs in Railway dashboard
Verify environment variables are set
Check if model loaded successfully
Ensure Pinecone index is accessible

# Check Railway logs
railway logs

CORS Errors

Symptoms: Frontend can’t reach backendSolutions:

Add frontend URL to CORS origins
Verify BACKEND_URL in frontend env
Check browser network tab for errors
Ensure Railway domain is active

Build Failures

Symptoms: Deployment fails during buildSolutions:

Check Vercel/Railway build logs
Verify all dependencies in package.json/requirements.txt
Ensure root directory is set correctly
Check for syntax errors in code
Verify Node/Python versions

Environment Variable Issues

Symptoms: Runtime errors about missing configSolutions:

Double-check all env vars are set
No typos in variable names
Use correct keys for production
Restart deployments after adding vars
Check Railway/Vercel env var UI

Cold Start Optimization

Railway apps may experience cold starts. To optimize:

Keep Backend Warm

Set up a cron job to ping your backend every 5 minutes:

# Using a service like cron-job.org
GET https://your-app.up.railway.app/health

Optimize Model Loading

The backend loads the embedding model on startup:

Model caching in Railway
Use Railway’s persistent storage
Pre-warm on deployment

Continuous Deployment

Set up Git workflow

# Development branch
git checkout -b development
git push origin development

# Production branch
git checkout main
git push origin main

Configure branch deployments

Vercel:

main branch → Production
Other branches → Preview deployments

Railway:

main branch → Production
Set up staging environment for development branch (optional)

Create deployment workflow

Develop and test locally
Push to feature branch
Create pull request
Review preview deployment (Vercel auto-generates)
Merge to main for production deployment

Monitoring & Analytics

Vercel Analytics

Enable in Vercel dashboard:

Page views and traffic
Core Web Vitals
User geography
Device breakdown

Railway Metrics

Monitor in Railway dashboard:

CPU and memory usage
Request count and latency
Deployment history
Build times

API Usage Tracking

Monitor your API quotas:

OpenAI: Check usage dashboard
Pinecone: Monitor vector operations
Clerk: Track active users
Supabase: Database usage

Error Tracking

Recommended tools:

Sentry: Frontend & backend errors
LogRocket: Session replay
Vercel Logs: Deployment errors
Railway Logs: Runtime errors

Cost Optimization

Free Tier Limits

Vercel: 100GB bandwidth/month
Railway: $5 credit/month (hobby plan)
Pinecone: 1 pod free tier
Supabase: 500MB database free

Reduce Costs

Cache OpenAI responses in Supabase
Batch Pinecone queries
Optimize Railway resource usage
Use Vercel Edge caching
Monitor API usage closely

Next Steps

Local Setup

Return to local setup guide

Environment Variables

Review all environment configuration

Environment Variables

Technology Stack

⌘I

Setup

Architecture

​Overview

​Architecture

Frontend on Vercel

Backend on Railway

​Prerequisites

Git Repository

API Keys

Accounts Created

​Deploy Backend to Railway

​Railway Configuration Tips

Resource Usage

Logs & Debugging

​Deploy Frontend to Vercel

​Vercel Configuration Tips

Automatic Deployments

Custom Domain

​CORS Configuration

​Verify Deployment

Backend Health Check

Frontend Test

​End-to-End Test

​Production Checklist

Security

Performance

Monitoring

Backup & Recovery

​Troubleshooting

Backend Not Responding

CORS Errors

Build Failures

Environment Variable Issues

​Cold Start Optimization

Keep Backend Warm

Optimize Model Loading

​Continuous Deployment

​Monitoring & Analytics

Vercel Analytics

Railway Metrics

API Usage Tracking

Error Tracking

​Cost Optimization

Free Tier Limits

Reduce Costs

​Next Steps

Local Setup

Environment Variables

Build docs developers (and LLMs) love

Overview

Architecture

Prerequisites

Deploy Backend to Railway

Railway Configuration Tips

Deploy Frontend to Vercel

Vercel Configuration Tips

CORS Configuration

Verify Deployment

End-to-End Test

Production Checklist

Troubleshooting

Cold Start Optimization

Continuous Deployment

Monitoring & Analytics

Cost Optimization

Next Steps