ALwrity/DEPLOYMENT_GUIDE.md

🚀 ALwrity Deployment Guide

Vercel Deployment Strategy

Since Vercel is optimized for frontend applications, we'll deploy the frontend on Vercel and the backend on a separate platform.

Architecture Overview

Frontend (Vercel) ←→ Backend (Railway/Render) ←→ Database (SQLite/PostgreSQL)

---

🎯 Step-by-Step Deployment

Part 1: Deploy Backend (Railway - Recommended)

Option A: Railway (Recommended)

1. Install Railway CLI:

   npm install -g @railway/cli
   

2. Login to Railway:

   railway login
   

3. Initialize Project:

   cd backend
   railway init
   

4. Add Environment Variables:

   railway variables set GEMINI_API_KEY=your_gemini_key
   railway variables set OPENAI_API_KEY=your_openai_key
   railway variables set ANTHROPIC_API_KEY=your_anthropic_key
   railway variables set MISTRAL_API_KEY=your_mistral_key
   railway variables set TAVILY_API_KEY=your_tavily_key
   railway variables set EXA_API_KEY=your_exa_key
   railway variables set SERPER_API_KEY=your_serper_key
   railway variables set CLERK_SECRET_KEY=your_clerk_secret
   railway variables set GSC_REDIRECT_URI=https://your-frontend.vercel.app/gsc/callback
   railway variables set WORDPRESS_REDIRECT_URI=https://your-frontend.vercel.app/wp/callback
   railway variables set WIX_REDIRECT_URI=https://your-frontend.vercel.app/wix/callback
   

5. Deploy:

   railway up
   

6. Get Backend URL:

   railway domain
   

   Copy the URL (e.g., https://your-app.railway.app)

Option B: Render

1. Go to render.com and connect your GitHub
2. Create a new "Web Service"
3. Select your repository
4. Configure:
   • Build Command: pip install -r requirements.txt
   • Start Command: python start_alwrity_backend.py
   • Environment: Python 3
5. Add all environment variables in the dashboard
6. Deploy and get your backend URL

---

Part 2: Deploy Frontend (Vercel)

1. Prepare Frontend for Production

Create a .env.production file in the frontend directory:

REACT_APP_API_URL=https://your-backend-url.railway.app
REACT_APP_ENVIRONMENT=production

2. Deploy to Vercel

1. Connect to Vercel:

   • Go to vercel.com
   • Click "New Project"
   • Import your GitHub repository

2. Configure Project:

   • Framework Preset: Create React App
   • Root Directory: frontend
   • Build Command: npm run build
   • Output Directory: build

3. Add Environment Variables:

   REACT_APP_API_URL = https://your-backend-url.railway.app
   REACT_APP_ENVIRONMENT = production
   

4. Deploy:

   • Click "Deploy"
   • Wait for deployment to complete
   • Get your frontend URL (e.g., https://your-app.vercel.app)

3. Update Backend URLs

After getting your frontend URL, update the backend environment variables:

# Update redirect URIs with your actual Vercel URL
railway variables set GSC_REDIRECT_URI=https://your-app.vercel.app/gsc/callback
railway variables set WORDPRESS_REDIRECT_URI=https://your-app.vercel.app/wp/callback
railway variables set WIX_REDIRECT_URI=https://your-app.vercel.app/wix/callback

---

🔧 Alternative: Full-Stack on Vercel (Advanced)

If you want to deploy everything on Vercel, you can use Vercel's serverless functions:

1. Create API Routes

Create api/ directory in your project root:

api/
├── auth/
│   └── [...auth].ts
├── content/
│   └── generate.ts
└── seo/
    └── analyze.ts

2. Convert FastAPI to Vercel Functions

This requires significant refactoring of your backend code to work with Vercel's serverless functions.

3. Deploy as Monorepo

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

---

🛠️ Environment Variables Checklist

Backend Environment Variables:

# AI API Keys
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
MISTRAL_API_KEY=your_mistral_key

# Research APIs
TAVILY_API_KEY=your_tavily_key
EXA_API_KEY=your_exa_key
SERPER_API_KEY=your_serper_key

# Authentication
CLERK_SECRET_KEY=your_clerk_secret

# OAuth Redirects (update with your Vercel URL)
GSC_REDIRECT_URI=https://your-app.vercel.app/gsc/callback
WORDPRESS_REDIRECT_URI=https://your-app.vercel.app/wp/callback
WIX_REDIRECT_URI=https://your-app.vercel.app/wix/callback

Frontend Environment Variables:

REACT_APP_API_URL=https://your-backend-url.railway.app
REACT_APP_ENVIRONMENT=production

---

🚀 Post-Deployment Steps

1. Test Your Deployment

• Visit your Vercel URL
• Complete the onboarding process
• Test content generation
• Verify OAuth integrations

2. Configure Custom Domain (Optional)

• In Vercel dashboard, go to your project
• Click "Domains"
• Add your custom domain
• Update redirect URIs with custom domain

3. Monitor Performance

• Check Vercel analytics
• Monitor Railway/Render logs
• Set up error tracking (Sentry, etc.)

---

🔍 Troubleshooting

Common Issues:

1. CORS Errors:

   • Add your Vercel domain to backend CORS settings
   • Update allowed_origins in FastAPI CORS middleware

2. Environment Variables:

   • Ensure all variables are set in both platforms
   • Check variable names match exactly

3. OAuth Redirects:

   • Update all redirect URIs with production URLs
   • Test OAuth flows end-to-end

4. Database Issues:

   • Consider upgrading to PostgreSQL for production
   • Set up database backups

Performance Optimization:

1. Frontend:

   • Enable Vercel's edge caching
   • Optimize bundle size
   • Use CDN for static assets

2. Backend:

   • Implement connection pooling
   • Add caching layers
   • Monitor memory usage

---

📊 Monitoring & Maintenance

Health Checks:

• Frontend: https://your-app.vercel.app/health
• Backend: https://your-backend.railway.app/health

Logs:

• Vercel: Built-in function logs
• Railway: railway logs
• Render: Dashboard logs section

Scaling:

• Vercel: Automatic scaling
• Railway: Manual scaling in dashboard
• Render: Auto-scaling available

---

🎯 Recommended Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   (Vercel)      │◄──►│   (Railway)     │◄──►│   (PostgreSQL)  │
│                 │    │                 │    │                 │
│ • React App     │    │ • FastAPI      │    │ • User Data     │
│ • Static Files │    │ • AI Services   │    │ • Content       │
│ • CDN Cached    │    │ • OAuth APIs    │    │ • Analytics     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

This setup provides:

• ✅ Fast frontend delivery via Vercel's global CDN
• ✅ Scalable backend with Railway's infrastructure
• ✅ Reliable database with PostgreSQL
• ✅ Easy maintenance with separate concerns
• ✅ Cost-effective scaling based on usage

---

🚀 Next Steps

1. Deploy backend to Railway/Render
2. Deploy frontend to Vercel
3. Configure environment variables
4. Test all integrations
5. Set up monitoring
6. Configure custom domain (optional)

Your ALwrity platform will be live and accessible worldwide! 🌍