docs/DEPLOYMENT_GUIDE.md

BankBot AI — Deployment Guide

Option 1: Local Development (Fastest)

# 1. Clone and setup backend
cd backend
python -m venv venv
venv\Scripts\activate          # Windows
pip install -r requirements.txt
copy .env.example .env         # Edit with your API keys

# 2. Seed demo data
python app/scripts/seed_demo.py

# 3. Start backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 4. In a new terminal — setup frontend
cd frontend
npm install --legacy-peer-deps
npm run dev

# Access: http://localhost:3000
# Login: alex@bankbot.dev / BankBot2026!
# API Docs: http://localhost:8000/docs
# Metrics: http://localhost:8000/api/metrics

---

Option 2: Docker Compose (Recommended for Demo)

# 1. Configure environment
cp .env.example .env
# Edit .env — set OPENAI_API_KEY or GROQ_API_KEY

# 2. Start all services (PostgreSQL + Redis + Backend + Frontend)
docker compose up -d

# 3. Seed demo data
docker compose exec backend python app/scripts/seed_demo.py

# 4. Access
# Frontend: http://localhost:3000
# Backend:  http://localhost:8000
# API Docs: http://localhost:8000/docs

# 5. View logs
docker compose logs -f backend
docker compose logs -f frontend

# 6. Stop
docker compose down

With Nginx (Production mode)

docker compose --profile production up -d
# Access via http://localhost (port 80)

---

Option 3: Cloud Deployment

Frontend → Vercel

cd frontend

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

# Set environment variable in Vercel dashboard:
# NEXT_PUBLIC_API_URL = https://your-backend.onrender.com

Backend → Render

1. Push code to GitHub
2. Go to https://render.com → New → Web Service
3. Connect your GitHub repo
4. Render auto-detects render.yaml in backend/
5. Set environment variables in Render dashboard:
   • OPENAI_API_KEY or GROQ_API_KEY
   • JWT_SECRET_KEY (generate a strong random string)
6. Render provisions PostgreSQL and Redis automatically

Backend → Railway

# Install Railway CLI
npm i -g @railway/cli
railway login

cd backend
railway init
railway up

# Add PostgreSQL and Redis plugins in Railway dashboard
# Set environment variables in Railway dashboard

Backend → DigitalOcean App Platform

1. Create new App → GitHub repo
2. Set source directory: backend
3. Build command: pip install -r requirements.txt
4. Run command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
5. Add PostgreSQL and Redis managed databases
6. Set environment variables

---

Environment Variables Reference

Backend (Required for Production)

# REQUIRED
JWT_SECRET_KEY=<generate with: python -c "import secrets; print(secrets.token_hex(32))">
DATABASE_URL=postgresql://user:pass@host:5432/bankbot

# REQUIRED (at least one AI key)
OPENAI_API_KEY=sk-...
# OR
GROQ_API_KEY=gsk_...

# RECOMMENDED
REDIS_URL=redis://host:6379/0
BACKEND_CORS_ORIGINS=["https://your-frontend.vercel.app"]
ACCESS_TOKEN_EXPIRE_MINUTES=60

Frontend (Required for Production)

NEXT_PUBLIC_API_URL=https://your-backend.onrender.com

---

Post-Deployment Checklist

[ ] Backend health check passes: GET /health → {"status": "healthy"}
[ ] API status shows correct backend: GET /api/status
[ ] Demo account works: POST /api/auth/login
[ ] Dashboard loads: GET /api/dashboard/overview
[ ] WebSocket connects: ws://your-backend/api/ai/chat/ws
[ ] Metrics endpoint works: GET /api/metrics
[ ] Frontend loads at production URL
[ ] CORS allows frontend origin
[ ] JWT tokens work end-to-end
[ ] Seed demo data: python app/scripts/seed_demo.py

---

Troubleshooting

Backend won't start

# Check Python version (needs 3.11+)
python --version

# Check if port is in use
netstat -ano | findstr :8000

# Check logs
uvicorn app.main:app --port 8000 --log-level debug

Frontend can't reach backend

# Check NEXT_PUBLIC_API_URL in .env.local
cat frontend/.env.local

# Test backend directly
curl http://localhost:8000/health

# Check CORS — backend must allow frontend origin
# Edit BACKEND_CORS_ORIGINS in .env

WebSocket not connecting

# Check browser console for WS errors
# Verify backend is running on correct port
# Check Nginx config if using reverse proxy (ws:// upgrade headers)

AI responses not working

# Check which backend is active
curl http://localhost:8000/api/status

# If ai_available: false, check your API keys
# For Ollama: ensure it's running with: ollama serve
# For Groq: verify key at https://console.groq.com

Database issues

# Force SQLite (no PostgreSQL needed)
# In .env: USE_SQLITE=true

# Re-seed database
python app/scripts/seed_demo.py

# Check DB type
curl http://localhost:8000/api/status | python -m json.tool