MGSLG Analytics Platform - Production Deployment Guide

✅ Status: Ready for Railway Deployment

Database: ✅ PostgreSQL seeded with 1,500+ participants Backend API: ✅ Real database queries implemented Frontend: ✅ Configured for production

Prerequisites

Railway Account (already have subscription)
GitHub Repository - gedeza/mathew-goniwe (configured)
PostgreSQL Database on Railway
Domain (optional) - for custom URLs

Part 1: Deploy Backend to Railway

Step 1: Create Backend Service

# Login to Railway (if not already)
railway login

# Link repository
railway link

Step 2: Configure Environment Variables

In Railway Dashboard → Backend Service → Variables:

# Application
ENVIRONMENT=production
SECRET_KEY=<generate-strong-secret-key>

# Database (provided by Railway PostgreSQL)
DATABASE_URL=${{Postgres.DATABASE_URL}}

# Redis (optional, add later)
REDIS_URL=${{Redis.REDIS_URL}}

# Application Settings
PORT=8000
LOG_LEVEL=INFO

# Mock Data (disable in production)
MOCK_DATA_ENABLED=false

Step 3: Deploy Backend

# From project root
cd backend
railway up

# Or link GitHub for auto-deployment
# Railway Dashboard → Settings → Connect GitHub Repo

Step 4: Run Database Migrations

# SSH into Railway container or run locally against production DB
railway run python seed_database.py

Step 5: Verify Deployment

# Get your backend URL
railway status

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

# Test KPIs endpoint
curl https://your-backend-url.up.railway.app/api/dashboard/kpis

Expected Response:

{
  "success": true,
  "data": [
    {
      "title": "Total Participants",
      "value": 1500,
      "change": 12,
      "changeType": "increase"
    }
  ]
}

Part 2: Deploy Frontend to Railway

Step 1: Create Frontend Service

In Railway Dashboard:

New → Service
Select “Deploy from GitHub”
Choose frontend directory

Step 2: Configure Build Settings

Build Command:

npm install && npm run build

Start Command:

npm start

Root Directory:

/frontend

Step 3: Configure Environment Variables

NEXT_PUBLIC_API_URL=https://your-backend-url.up.railway.app
NODE_ENV=production

Step 4: Deploy Frontend

cd frontend
railway up

Step 5: Verify Frontend

Visit: https://your-frontend-url.up.railway.app

Part 3: Configuration Summary

Backend Environment Variables (Railway)

Variable	Value	Notes
`ENVIRONMENT`	`production`
`DATABASE_URL`	`${{Postgres.DATABASE_URL}}`	Auto-populated
`SECRET_KEY`	Generate securely	Use `openssl rand -hex 32`
`PORT`	`8000`	Railway default
`LOG_LEVEL`	`INFO`
`MOCK_DATA_ENABLED`	`false`	Use real data

Frontend Environment Variables (Railway)

Variable	Value	Notes
`NEXT_PUBLIC_API_URL`	Backend Railway URL	e.g., `https://mgslg-backend.up.railway.app`
`NODE_ENV`	`production`

Part 4: Database Setup

Option A: Use Railway PostgreSQL (Recommended)

Railway Dashboard → New → Database → PostgreSQL
Copy connection string
Set as DATABASE_URL in backend service
Run seed script:

railway run --service backend python seed_database.py

Option B: Use External PostgreSQL

# Create database
createdb mgslg_analytics_prod

# Update DATABASE_URL
export DATABASE_URL="postgresql://user:pass@host:5432/mgslg_analytics_prod"

# Run seed script
python backend/seed_database.py

Part 5: Custom Domain (Optional)

Backend Domain

Railway Dashboard → Backend Service → Settings
Add custom domain: api.mgslg-analytics.com
Update DNS:
- Type: CNAME
- Name: api
- Value: <railway-domain>.up.railway.app

Frontend Domain

Railway Dashboard → Frontend Service → Settings
Add custom domain: mgslg-analytics.com
Update DNS:
- Type: CNAME
- Name: @ or www
- Value: <railway-domain>.up.railway.app

Update Frontend Environment:

NEXT_PUBLIC_API_URL=https://api.mgslg-analytics.com

Part 6: Monitoring & Health Checks

Health Check Endpoints

Backend:

/api/health - Service health status
/docs - API documentation (development only)

Frontend:

/ - Main dashboard

Railway Monitoring

Railway provides built-in monitoring:

CPU/Memory usage
Request logs
Error tracking
Deployment history

Part 7: Quick Deployment Commands

Deploy Everything

# 1. Deploy backend
cd backend
railway up --service backend

# 2. Seed database (first time only)
railway run --service backend python seed_database.py

# 3. Deploy frontend
cd ../frontend
railway up --service frontend

# 4. Check status
railway status

Update After Changes

# Railway auto-deploys on git push if GitHub is connected
git add .
git commit -m "Update feature"
git push origin main

# Or manually deploy
railway up

Part 8: Verification Checklist

Backend Verification

Health check returns {"success": true, "data": {"status": "healthy"}}
KPIs endpoint returns 1,500 participants
Geographic endpoint returns 6 provinces
Database has 1,500+ participant records
Logs show no errors

Frontend Verification

Main dashboard loads successfully
KPIs display real data (1,500 participants)
Geographic performance shows provinces
No console errors
API calls succeed (check Network tab)

Integration Verification

Frontend successfully connects to backend API
Data loads without fallback to mock data
All dashboard pages functional
ML Analytics page loads
Reports page accessible

Part 9: Troubleshooting

Backend Issues

Database Connection Errors:

# Check DATABASE_URL format
echo $DATABASE_URL

# Railway format: postgresql://user:pass@host:5432/db
# Backend automatically adds +asyncpg

Migration Errors:

# Reset database (CAUTION: Deletes all data)
railway run --service backend python seed_database.py

Frontend Issues

API Connection Errors:

# Check NEXT_PUBLIC_API_URL is set
railway variables --service frontend

# Test backend URL manually
curl https://your-backend-url.up.railway.app/api/health

Build Errors:

# Clear cache and rebuild
railway logs --service frontend

# Check Node version (should be 18+)

Part 10: Production URLs

After deployment, you’ll have:

Development (Local)

Frontend: http://localhost:3000
Backend: http://localhost:8000
API Docs: http://localhost:8000/docs

Production (Railway)

Frontend: https://<frontend-service>.up.railway.app
Backend: https://<backend-service>.up.railway.app
API Docs: Disabled in production (security)

Custom Domains (if configured)

Frontend: https://mgslg-analytics.com
Backend: https://api.mgslg-analytics.com

Part 11: Security Best Practices

Secrets Management:
- Use Railway environment variables
- Never commit .env files
- Rotate SECRET_KEY regularly
Database Security:
- Use Railway PostgreSQL (private networking)
- Enable SSL connections
- Regular backups (Railway auto-backup)
API Security:
- CORS configured for frontend domain only
- Rate limiting (add later)
- Input validation with Pydantic
POPIA Compliance:
- Data anonymization for analytics
- Audit trails enabled
- Consent management (add later)

Part 12: Cost Estimation

Railway Costs (Monthly)

Service	Cost	Notes
Starter Plan	$5	Base subscription
PostgreSQL	$5-10	Based on usage
Backend Service	Included	In plan
Frontend Service	Included	In plan
Total	$10-15/month	Hobby project range

Pro Plan (Recommended for production)

Service	Cost	Notes
Pro Plan	$20
PostgreSQL	$10	Larger database
Redis	$5	Caching
Total	$35/month	Production-ready

Part 13: Post-Deployment

Immediate Tasks

Test all endpoints with real stakeholder scenarios
Monitor logs for first 24 hours
Verify data integrity in production database
Create backup of production database
Document any issues encountered

Next Steps

Add authentication (JWT tokens)
Implement Redis caching for performance
Add ML predictions for career progression
Set up monitoring (Sentry, LogRocket)
Create demo video walkthrough

Support & Resources

Railway Docs: https://docs.railway.app
Project README: /README.md
Local Setup: /LOCAL-DEMO-SETUP.md
Backend API Docs: /docs (when running)

Generated: 2025-09-30 Platform: MGSLG Analytics Platform v1.0 Deployment Target: Railway Status: ✅ Ready for Production Deployment