docs/DEPLOYMENT_GUIDE.md

# BankBot AI — Deployment Guide

## Option 1: Local Development (Fastest)

```bash
# 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)

```bash
# 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)

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

---

## Option 3: Cloud Deployment

### Frontend → Vercel

```bash
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

```bash
# 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)

```env
# 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)

```env
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```