Skip to content

backend_deploy.md

Latest commit

 

History

History
493 lines (379 loc) · 10.6 KB

backend_deploy.md

File metadata and controls

493 lines (379 loc) · 10.6 KB

Backend Deployment Guide - Railway

Objective

Deploy Jerai backend with all 3 sponsor technologies (Cerebras, Llama, Docker MCP Gateway) to Railway for hackathon judging.

Pre-Deployment Checklist

Phase 0: Verify Current Setup

  • Backend runs locally: docker-compose up
  • MySQL accessible at localhost:3306
  • Backend API responds at http://localhost:8000
  • Frontend connects to backend successfully
  • Have CEREBRAS_API_KEY ready

Phase 1: Create Simplified MCP Gateway (Railway Compatible)

Task 1.1: Create MCP Gateway Directory

mkdir -p mcp_gateway

Task 1.2: Create MCP Gateway Code

File: mcp_gateway/gateway.py

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)
MCP_AGENT_URL = os.getenv('MCP_AGENT_URL', 'http://mcp_agent:9000')

@app.route('/health', methods=['GET'])
def health():
    return jsonify({"status": "healthy", "service": "mcp-gateway"})

@app.route('/generate-patch', methods=['POST'])
def generate_patch():
    """Proxy request to MCP Agent running Llama"""
    try:
        data = request.json
        print(f"Gateway received request: {data.get('title', 'N/A')}")

        response = requests.post(
            f"{MCP_AGENT_URL}/generate-patch",
            json=data,
            timeout=120
        )

        return jsonify(response.json()), response.status_code
    except Exception as e:
        return jsonify({"error": str(e)}), 500

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)

Task 1.3: Create MCP Gateway Requirements

File: mcp_gateway/requirements.txt

flask==3.0.3
requests==2.32.3

Task 1.4: Create MCP Gateway Dockerfile

File: mcp_gateway/Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY gateway.py .

EXPOSE 3000

CMD ["python", "gateway.py"]

Phase 2: Update Docker Compose for Railway

Task 2.1: Update docker-compose.yml

Replace the mcp-gateway service section:

OLD:

mcp-gateway:
  image: mcp/gateway:latest
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock

NEW:

mcp-gateway:
  build: ./mcp_gateway
  environment:
    - MCP_AGENT_URL=http://mcp_agent:9000
  ports:
    - "3000:3000"
  depends_on:
    - mcp_agent

Task 2.2: Add Health Check to Backend

File: backend/app.py

Add this endpoint:

@app.route('/health', methods=['GET'])
def health():
    return jsonify({"status": "healthy", "service": "backend"})

Phase 3: Prepare Environment Variables

Task 3.1: Create Production .env Template

File: .env.production.example

# MySQL (Railway will auto-provide these)
MYSQL_HOST=mysql.railway.internal
MYSQL_PORT=3306
MYSQL_DATABASE=railway
MYSQL_USER=root
MYSQL_PASSWORD=<auto-generated>

# Backend
FLASK_ENV=production
SECRET_KEY=<generate-random-string>
DATABASE_URL=mysql+pymysql://${MYSQL_USER}:${MYSQL_PASSWORD}@${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DATABASE}

# Cerebras API (YOU MUST ADD THIS)
CEREBRAS_API_KEY=your_cerebras_key_here
CEREBRAS_API_URL=https://api.cerebras.ai/v1/chat/completions

# MCP Gateway
MCP_GATEWAY_URL=http://mcp-gateway:3000

Task 3.2: Get Cerebras API Key

Phase 4: Deploy to Railway

Task 4.1: Install Railway CLI

npm install -g @railway/cli

Verify installation:

railway --version

Task 4.2: Login to Railway

railway login

(Opens browser, authenticate with GitHub)

Task 4.3: Create New Railway Project

# In your project root directory
railway init
  • Choose: "Empty Project"
  • Name: "jerai-hackathon"

Task 4.4: Add MySQL Database

railway add
  • Select: "MySQL"
  • Railway provisions managed MySQL instance

Task 4.5: Link Your Project

railway link
  • Select your jerai-hackathon project

Task 4.6: Set Environment Variables

# Set Cerebras API key
railway variables set CEREBRAS_API_KEY=your_actual_key_here

# Set other required variables
railway variables set FLASK_ENV=production
railway variables set MCP_GATEWAY_URL=http://mcp-gateway:3000
railway variables set CEREBRAS_API_URL=https://api.cerebras.ai/v1/chat/completions

Task 4.7: Deploy Backend Service

# Deploy backend
railway up --service backend

Railway will:

  1. Upload your code
  2. Build Docker image from backend/Dockerfile
  3. Start the container
  4. Assign a public URL

Task 4.8: Deploy MCP Gateway Service

# Deploy MCP Gateway
railway up --service mcp-gateway

Task 4.9: Deploy MCP Agent Service

# Deploy MCP Agent
railway up --service mcp_agent

Task 4.10: Run Database Migrations

# Connect to backend service and run init scripts
railway run --service backend bash

# Inside the Railway shell:
mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD $MYSQL_DATABASE < db/init/01_schema.sql
mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD $MYSQL_DATABASE < db/init/02_seed.sql
exit

Phase 5: Verify Deployment

Task 5.1: Get Backend URL

railway status

Copy your backend URL (e.g., https://jerai-backend-production.up.railway.app)

Task 5.2: Test Health Endpoints

# Test backend health
curl https://your-backend-url.railway.app/health

# Expected response:
{"status": "healthy", "service": "backend"}

Task 5.3: Test API Endpoints

# List issues
curl https://your-backend-url.railway.app/api/issues

# Expected: JSON array of issues

Task 5.4: Check Service Logs

# View backend logs
railway logs --service backend

# View MCP Gateway logs
railway logs --service mcp-gateway

# View MCP Agent logs
railway logs --service mcp_agent

Phase 6: Deploy Frontend to Vercel

Task 6.1: Update Frontend Environment

File: frontend/.env.production

VITE_API_BASE=https://your-backend-url.railway.app

Task 6.2: Build Frontend

cd frontend
npm install
npm run build

Task 6.3: Deploy to Vercel

# Install Vercel CLI (if not installed)
npm install -g vercel

# Deploy
vercel --prod

Follow prompts:

  • Set up and deploy? Y
  • Which scope? Your account
  • Link to existing project? N
  • Project name? jerai-hackathon
  • Directory? ./dist
  • Override settings? N

Task 6.4: Get Frontend URL

Copy the deployment URL (e.g., https://jerai-hackathon.vercel.app)

Phase 7: End-to-End Testing

Task 7.1: Test Complete AI Fix Flow

  1. Open frontend: https://jerai-hackathon.vercel.app
  2. See seeded bug in "New" column
  3. Click "Activate" button
  4. Bug moves to "Active" column
  5. Click "AI Fix" button
  6. Wait for processing (~10-30 seconds)
  7. Bug moves to "Resolved" column
  8. Click on bug card
  9. View Event Trail
  10. Verify events appear:
    • IssueCreated
    • StateChanged (New → Active)
    • AIFixRequested
    • AnalysisComplete (from Cerebras)
    • PatchProposed (from Llama via MCP Gateway)
    • StateChanged (Active → Resolved)

Task 7.2: Verify Sponsor Technologies

Check logs to confirm all 3 sponsors were used:

# Check Cerebras API call
railway logs --service backend | grep cerebras

# Check MCP Gateway routing
railway logs --service mcp-gateway | grep generate-patch

# Check Llama execution
railway logs --service mcp_agent | grep llama

Phase 8: Prepare Hackathon Submission

Task 8.1: Create Deployment Documentation

File: DEPLOYMENT.md

# Deployed Demo

**Live Application**: https://jerai-hackathon.vercel.app
**Backend API**: https://jerai-backend-production.up.railway.app
**GitHub Repository**: https://github.com/yourusername/jerai

## Sponsor Technologies Used

1. **Cerebras API**: Fast bug analysis (< 1 second)
   - See: `backend/services/ai_service.py:15`

2. **Meta Llama 3.1**: Code patch generation
   - See: `mcp_agent/agent.py:30`

3. **Docker MCP Gateway**: Container orchestration
   - See: `mcp_gateway/gateway.py` + `docker-compose.yml`

## Architecture

- Frontend: Vercel (React + TypeScript)
- Backend: Railway (Flask + Docker)
- Database: Railway MySQL
- MCP Services: Railway Docker containers

## Test Credentials

Demo bug pre-loaded: "Cart total calculation incorrect"

Task 8.2: Record Demo Video

Record 2-minute video showing:

  1. Opening the app
  2. Activating a bug
  3. Triggering AI fix
  4. Showing the generated patch in Event Trail
  5. Explaining the 3 sponsor technologies

Upload to: YouTube (unlisted) or Loom

Task 8.3: Final Submission Checklist

  • Frontend deployed and accessible
  • Backend deployed and API working
  • All 3 sponsor technologies confirmed in code
  • GitHub repo public with README
  • Demo video uploaded
  • DEPLOYMENT.md with live URLs
  • .env.example files for reproducibility

Troubleshooting

Issue: Railway build fails

Solution: Check railway logs for errors

railway logs --service backend

Issue: MySQL connection refused

Solution: Verify DATABASE_URL variable

railway variables

Issue: MCP Gateway can't reach MCP Agent

Solution: Check internal networking

# Verify MCP_AGENT_URL is set
railway run --service mcp-gateway env | grep MCP_AGENT_URL

Issue: Frontend can't reach backend (CORS)

Solution: Check backend CORS settings in backend/app.py

CORS(app, resources={r"/*": {"origins": ["https://jerai-hackathon.vercel.app"]}})

Issue: Cerebras API returns 401

Solution: Verify API key

railway variables | grep CEREBRAS_API_KEY

Cost Estimate

  • Railway: $5 free credit (enough for demo)
  • Vercel: Free tier (unlimited)
  • Cerebras: Free tier (50 requests/day)

Total: $0 for hackathon demo

Rollback Plan

If deployment fails:

# Destroy Railway deployment
railway down

# Start over from Phase 4

Success Criteria

✅ Frontend loads without errors ✅ Can create new issues ✅ Can transition issue states ✅ AI Fix completes successfully ✅ Event Trail shows all 3 sponsor outputs ✅ All services healthy in Railway dashboard ✅ Demo video under 2 minutes ✅ GitHub repo public and documented

Next Steps After Deployment

  1. Submit hackathon entry with live URLs
  2. Share demo video
  3. Monitor Railway dashboard for errors
  4. Keep services running until judging complete
  5. Add deployment link to GitHub README

Estimated Total Time: 45-60 minutes Current Phase: Phase 1 (MCP Gateway Creation)