DEPLOYMENT.md

Deployment Guide

🚀 Quick Start (Local Development)

1. Environment Setup

# Copy environment variables
cp .env.example .env

# Update .env with your keys
# - OPENAI_API_KEY
# - K2_THINK_API_KEY
# - DATABASE_URL (if not using Docker)

2. Docker Compose (Recommended)

# Start all services with live-reload enabled
docker compose up -d

# Services running:
# - Frontend: http://localhost:3000
# - API: http://localhost:8000
# - Docs: http://localhost:8000/docs
# - Qdrant: http://localhost:6333
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379

Live-Reloading: The docker-compose.yml is configured to mount the ./app directory into the container. Most backend code changes will be reflected immediately without restarting the container.

3. First Run

# Check health
curl http://localhost:8000/health/ready

# Run tests
./deploy.sh test

# View logs
./deploy.sh logs

---

🌐 API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Main Endpoints

Analysis

POST /api/analysis/run
- Start comprehensive analysis
- Body: { documents: [...], analysis_type: "comprehensive" }

GET /api/analysis/{analysis_id}/status
- Check analysis status

GET /api/analysis/{analysis_id}/results
- Get analysis results

Health

GET /health/
- Basic health check

GET /health/ready
- Full readiness check with all dependencies

GET /health/live
- Liveness probe (Kubernetes ready)

---

🐳 Docker Commands

Development

# Start in development mode (with reload)
docker-compose up -d

# View logs
docker-compose logs -f api

# Stop services
docker-compose down

# Rebuild images
docker-compose build

# Remove volumes (WARNING: data loss)
docker-compose down -v

Production

Option 1: Railway.app (Recommended for Hackathon)

1. Create Railway account: https://railway.app

2. Deploy from Git:

   # Railway will auto-detect docker-compose.yml
   # Services automatically created:
   # - PostgreSQL
   # - Redis
   # - FastAPI API
   # - Celery Worker
   

3. Environment variables:

   • Set in Railway dashboard
   • Same as .env file

4. DNS & Domains:

   • Railway provides automatic domain
   • Custom domain via dashboard

Option 2: AWS ECS/Kubernetes

# Build and push to ECR
aws ecr create-repository --repository-name scoinvestigator-api

docker build -t scoinvestigator-api .
docker tag scoinvestigator-api:latest <aws-account>.dkr.ecr.us-east-1.amazonaws.com/scoinvestigator-api:latest
docker push <aws-account>.dkr.ecr.us-east-1.amazonaws.com/scoinvestigator-api:latest

# Deploy via ECS/CloudFormation
# OR push to ECR and use AWS Console

Option 3: Vercel (Frontend) + Render (Backend)

# Backend on Render
# 1. Push repo to GitHub
# 2. Connect to Render.com
# 3. Select docker-compose.yml
# 4. Deploy

# Frontend on Vercel
# 1. Create Next.js project
# 2. Connect GitHub
# 3. Set API_URL env var
# 4. Deploy

---

🔧 Configuration

Database Migrations (Alembic)

# Create new migration
docker-compose exec api alembic revision --autogenerate -m "Add new table"

# Apply migrations
docker-compose exec api alembic upgrade head

# Rollback
docker-compose exec api alembic downgrade -1

Celery Tasks

# Monitor Celery
docker-compose exec api celery -A app.workers.tasks inspect active

# Purge queue
docker-compose exec api celery -A app.workers.tasks purge

---

🧪 Testing

Run Tests

# All tests
./deploy.sh test

# Specific test file
docker-compose exec api pytest app/tests/test_analysis.py -v

# With coverage
docker-compose exec api pytest --cov=app --cov-report=html

Test Coverage Report

# Generate and view
docker-compose exec api pytest --cov=app --cov-report=html
open htmlcov/index.html

---

📊 Monitoring

Health Checks

The system includes built-in health checks for orchestration:

• API: GET /health/ (trailing slash required)
• PostgreSQL: pg_isready -d scoinvestigator
• Frontend: Check on port 3000

# Check API health
curl -I http://localhost:8000/health/

Logs

# FastAPI logs
./deploy.sh logs

# Celery logs
docker-compose logs -f celery_worker

# PostgreSQL logs
docker-compose logs -f postgres

# All services
docker-compose logs -f

Performance Monitoring

# Resource usage
docker stats

# Database connections
docker-compose exec postgres psql -U user -d scoinvestigator -c "SELECT count(*) FROM pg_stat_activity;"

# Redis memory
docker-compose exec redis redis-cli INFO memory

---

🔒 Security Checklist

Before Production Deployment

• Update SECRET_KEY in .env (use os.urandom(32))
• Set strong DB password
• Enable HTTPS/SSL
• Configure CORS properly
• Set up firewall rules
• Enable API rate limiting
• Configure log retention
• Set up backups for PostgreSQL
• Use environment variables (never commit secrets)
• Enable authentication on all endpoints
• Set up monitoring/alerting
• Review and test error handling

---

📈 Scaling

Horizontal Scaling (Long-term)

# With Kubernetes
# 1. Multiple API replicas
# 2. PostgreSQL cluster (or managed RDS)
# 3. Qdrant cluster
# 4. Redis cluster
# 5. Load balancer (ingress)

# With Docker Swarm
docker swarm init
docker stack deploy -c docker-compose.yml scoinvestigator

Vertical Scaling

# Increase resources in docker-compose.yml
services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

---

🐛 Troubleshooting

Services won't start

# Check logs
docker-compose logs

# Check ports are available
lsof -i :8000  # API
lsof -i :5432  # PostgreSQL
lsof -i :6333  # Qdrant
lsof -i :6379  # Redis

# Restart everything
docker-compose down -v
docker-compose up

Database connection errors

# Verify database is running
docker-compose exec postgres psql -U user -c "SELECT 1"

# Check connection string in .env
DATABASE_URL=postgresql://user:onion123@postgres:5432/scoinvestigator

Qdrant not responding

# Check Qdrant health
curl http://localhost:6333/health

# Restart Qdrant
docker-compose restart qdrant

API crashes

# View error logs
docker-compose logs api --tail=100

# Rebuild and restart
docker-compose build api
docker-compose up api

---

📞 Support

For issues:

1. Check logs: ./deploy.sh logs
2. Verify health: curl http://localhost:8000/health/ready
3. Check Docker: docker-compose ps
4. Review documentation in /docs endpoint
5. Open GitHub issue with logs

---

🎯 Next Steps

1. Local Testing: Run locally with Docker Compose
2. Frontend Integration: Setup Next.js frontend
3. Production Deployment: Deploy to Railway or AWS
4. Monitoring Setup: Configure observability stack
5. Auto-scaling: Setup scaling policies for load

Happy deploying! 🚀