quantum-ai-v3/RAILWAY_STARTUP_DEBUG.md

🚨 Railway Startup Failure - Debug Guide

Current Issue

Health check failing with "service unavailable" after 60 seconds, indicating Django/Gunicorn not starting properly.

🔧 Fixes Applied

1. Simplified Health Check

• No database dependency: Health check returns 200 if Django is running
• Always passes: As long as Django loads, health check succeeds
• Database optional: Database issues logged as warnings, not failures

2. Simplified Startup Process

• Removed migrations: No database dependency during startup
• Minimal startup: Only collectstatic + gunicorn
• Single worker: Reduced resource usage
• Faster timeout: 30s health check, 10s intervals

3. Separate Database Setup

• Post-startup command: python manage.py setup_database
• Built-in retries: Waits for database to be ready
• Graceful handling: Continues even if some steps fail

🚀 Deployment Steps

Step 1: Set ONLY These Environment Variables

# Critical variables only
SECRET_KEY=your-50-character-secret-key
DEBUG=False
ALLOWED_HOSTS=your-project.railway.app,quantumtaskai.com

Step 2: Deploy Simplified Version

git add .
git commit -m "Simplify Railway startup - remove database dependencies"
git push origin main

Step 3: After App Starts, Run Database Setup

# Wait for app to be running, then:
railway run python manage.py setup_database

🔍 Debugging Commands

Check Deployment Status

# View recent logs
railway logs --tail 50

# Check if app is responding
curl https://your-project.railway.app/health/

# Check environment variables
railway variables

Expected Health Response (Without Database)

{
  "status": "healthy",
  "app": "quantum-tasks-ai",
  "checks": {
    "application": {
      "status": "healthy", 
      "django_ready": true,
      "server_running": true
    },
    "database": {
      "status": "warning",
      "error": "Database connection failed"
    },
    "environment": {
      "status": "healthy",
      "debug_mode": false,
      "secret_key_configured": true
    }
  }
}

🎯 Troubleshooting Common Issues

Issue 1: SECRET_KEY Error

ImproperlyConfigured: The SECRET_KEY setting must not be empty

Fix: Generate and set SECRET_KEY in Railway variables

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Issue 2: ALLOWED_HOSTS Error

DisallowedHost at /health/

Fix: Add Railway domain to ALLOWED_HOSTS

ALLOWED_HOSTS=your-project.railway.app,quantumtaskai.com

Issue 3: Port Binding Error

[ERROR] Can't connect to ('0.0.0.0', PORT)

Fix: Ensure $PORT variable is available (Railway sets this automatically)

Issue 4: Import Errors

ModuleNotFoundError: No module named 'xyz'

Fix: Check requirements.txt includes all dependencies

📊 Success Indicators

✅ App Starting Successfully

• Railway logs show "Starting gunicorn"
• Health check returns 200 status
• No import errors in logs
• Django loads without database

✅ Health Check Passing

curl https://your-project.railway.app/health/
# Should return JSON with "status": "healthy"

✅ Ready for Database Setup

railway run python manage.py setup_database
# Should complete migrations and populate agents

🔄 If Still Failing

Last Resort: Minimal Config

{
  "deploy": {
    "startCommand": "gunicorn netcop_hub.wsgi:application --bind 0.0.0.0:$PORT",
    "healthcheckTimeout": 30
  }
}

Test Locally First

# Test with minimal settings
export SECRET_KEY="test-key-123"
export DEBUG=False
export ALLOWED_HOSTS="localhost"
python manage.py runserver

📞 Next Steps

1. Deploy simplified version (no database dependencies)
2. Verify health check passes (app starts successfully)
3. Run database setup separately (after app is running)
4. Test full functionality (agents, payments, etc.)

The goal is to get Django/Gunicorn starting first, then handle database setup separately.