security-platform/START_BACKEND_GUIDE.md

Backend Startup Guide

This guide provides multiple ways to start the AI SOC Analyst backend server.

Quick Start Options

1. Enhanced Python Script (Recommended)

python run_backend.py

Features:

• ✅ Automatic dependency checking and installation
• ✅ Creates necessary directories
• ✅ Smart application detection
• ✅ Cross-platform compatibility
• ✅ Enhanced error handling

2. Shell Script (Linux/Mac)

./start_backend.sh

Features:

• ✅ Virtual environment creation/activation
• ✅ Dependency management
• ✅ Colorized output
• ✅ Environment setup

3. Batch Script (Windows)

start_backend.bat

Features:

• ✅ Windows-specific optimizations
• ✅ Virtual environment handling
• ✅ Error handling with pause

4. Manual Backend Startup

# Navigate to backend directory
cd backend

# Install dependencies
pip install -r requirements.txt

# Start with uvicorn (recommended)
uvicorn app.api_main:app --host 0.0.0.0 --port 8000 --reload

# Or start with Python directly
python app/main.py

5. Simple Development Script

cd backend
python run_dev.py

What These Scripts Do

1. Environment Setup

   • Create virtual environment (if needed)
   • Install/update Python dependencies
   • Set up PYTHONPATH

2. Directory Management

   • Create uploads directory
   • Verify project structure

3. Server Startup

   • Start FastAPI with hot reload
   • Bind to all interfaces (0.0.0.0:8000)
   • Enable automatic code reloading

Access Points

Once started, the backend will be available at:

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

Troubleshooting

Port Already in Use

# Find process using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>

Dependencies Issues

# Manual dependency installation
cd backend
pip install -r requirements.txt

# Force reinstall
pip install --force-reinstall -r requirements.txt

Virtual Environment Issues

# Remove existing venv
rm -rf venv

# Run startup script again (will recreate venv)
./start_backend.sh

Development Tips

• Use python run_backend.py for the most reliable startup experience
• The server runs with hot reload - changes to code will auto-restart the server
• Check the console output for any startup errors or warnings
• Use Ctrl+C to gracefully stop the server

Environment Variables

The startup scripts will automatically handle:

• PYTHONPATH - Set to include backend directory
• Virtual environment activation
• Upload directory creation

For custom configuration, create a .env file in the backend directory.