Quick Start Guide

This guide will help you get the Brain Tumor Monitoring System up and running quickly.

Prerequisites

Before starting, ensure you have:

  • Python 3.8+ installed

  • PostgreSQL database running

  • Node.js 16+ (for frontend)

  • Git installed

Step 1: Clone the Repository

git clone https://github.com/minhNgnn/MedView-LMU-MLOps-SoSe25-GroupB.git
cd MedView-LMU-MLOps-SoSe25-GroupB

Create virtual environment:

python -m venv env
source env/bin/activate  # On Windows: env\Scripts\activate

Install dependencies:

pip install -r requirements_dev.txt
# Install backend dependencies
cd backend
pip install -r requirements.txt

# Install ML dependencies
cd ../ml
pip install -r requirements.txt

# (Optional) Install test dependencies
cd ../tests
pip install -r requirements_tests.txt

# (Frontend) Install Node.js dependencies
cd ../frontend
npm install

Step 2: Database Setup

Create database:

# Connect to PostgreSQL
sudo -u postgres psql

# Create database and user
CREATE DATABASE monitoring;
CREATE USER monitoring_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE monitoring TO monitoring_user;
\q

Run migrations:

# Set environment variable
export DATABASE_URL="postgresql://monitoring_user:your_password@localhost:5432/monitoring"

# Run the migration script
psql -h localhost -U monitoring_user -d monitoring -f backend/migrations/create_monitoring_tables.sql

Note

The database and user are already provisioned in the cloud. You do not need to run the CREATE DATABASE or CREATE USER commands. You will receive the DATABASE_URL from the project maintainer. Add this to your .env file as described above.

# (No need to run these commands)
# sudo -u postgres psql
# CREATE DATABASE monitoring;
# CREATE USER monitoring_user WITH PASSWORD 'your_password';
# GRANT ALL PRIVILEGES ON DATABASE monitoring TO monitoring_user;
# \q

Run migrations:

# Set environment variable
export DATABASE_URL="postgresql://monitoring_user:your_password@localhost:5432/monitoring"

# Run the migration script
psql -h localhost -U monitoring_user -d monitoring -f backend/migrations/create_monitoring_tables.sql

Note

The actual database credentials (including the cloud DATABASE_URL) will be provided to you securely by the project maintainer. Do not share or commit your .env file. To set up your environment, copy .env.example to .env and fill in the real values:

cp .env.example .env
# Then edit .env and fill in the real DATABASE_URL

Step 3: Start the Backend

Set environment variables:

export DATABASE_URL="postgresql://monitoring_user:your_password@localhost:5432/monitoring"
export DEBUG=True

Start the API server:

uvicorn backend.src.api:app --reload --host 0.0.0.0 --port 8000

Verify the backend is running:

curl https://gcp-test-app-351704569398.europe-west1.run.app/health

You should see:

{
  "status": "ok",
  "message": "Backend is running"
}

Step 4: Start the Frontend

Install Node.js dependencies:

cd frontend
npm install
cd ..

Start the frontend development server:

cd frontend
npm start

The frontend will open automatically at http://localhost:3000

Step 5: Test the System

Upload a test image:

curl -X POST https://gcp-test-app-351704569398.europe-west1.run.app/predict \
  -F "file=@path/to/test/image.jpg"

Check monitoring dashboard:

curl https://gcp-test-app-351704569398.europe-west1.run.app/monitoring/dashboard

Generate a drift report:

curl "https://gcp-test-app-351704569398.europe-west1.run.app/monitoring/drift-report?days=7"

Step 6: Explore the Dashboard

Open your browser and navigate to http://localhost:3000

You should see:

  • Dashboard: Real-time monitoring metrics

  • Upload: Image upload and prediction interface

  • Reports: Generated drift reports

  • Settings: System configuration

Step 7: Generate Sample Data

Create synthetic data for testing:

from monitoring.core.monitor import BrainTumorImageMonitor
import numpy as np

# Initialize monitor
monitor = BrainTumorImageMonitor("postgresql://monitoring_user:your_password@localhost:5432/monitoring")

# Generate synthetic images
for i in range(100):
    # Create random image
    image = np.random.randint(0, 255, (512, 512, 3), dtype=np.uint8)

    # Create prediction data
    prediction = {
        "confidence": np.random.uniform(0.7, 0.95),
        "class": np.random.choice(["benign", "malignant", "normal"]),
        "num_detections": np.random.randint(0, 3)
    }

    # Log prediction
    monitor.log_prediction(image, prediction)

Verify data generation:

curl https://gcp-test-app-351704569398.europe-west1.run.app/monitoring/dashboard

Step 8: Test Drift Detection

Generate drifted data:

# Generate data with different characteristics
for i in range(50):
    # Create brighter images (drift in brightness)
    image = np.random.randint(100, 255, (512, 512, 3), dtype=np.uint8)

    prediction = {
        "confidence": np.random.uniform(0.6, 0.9),
        "class": np.random.choice(["benign", "malignant", "normal"]),
        "num_detections": np.random.randint(0, 3)
    }

    monitor.log_prediction(image, prediction)

Check drift analysis:

curl "https://gcp-test-app-351704569398.europe-west1.run.app/monitoring/feature-analysis?days=7"

Generate drift report:

curl "https://gcp-test-app-351704569398.europe-west1.run.app/monitoring/drift-report?days=7"

Step 9: Next Steps

Customization:

  • Adjust drift detection thresholds

  • Customize feature extraction

  • Modify report templates

  • Add custom monitoring metrics

Integration:

  • Integrate with existing ML pipelines

  • Set up automated monitoring

  • Configure alerting systems

  • Implement CI/CD pipelines

Troubleshooting

Common Issues:

Backend won’t start:

# Check if port is in use
lsof -i :8000

# Check environment variables
echo $DATABASE_URL

# Check database connection
psql -h localhost -U monitoring_user -d monitoring -c "SELECT 1;"

Frontend won’t start:

# Check Node.js version
node --version

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Database connection issues:

# Check PostgreSQL status
sudo systemctl status postgresql

# Test connection
psql -h localhost -U monitoring_user -d monitoring

# Check logs
tail -f /var/log/postgresql/postgresql-*.log

No drift detection:

  • Ensure sufficient data exists (at least 50 records)

  • Check drift threshold settings

  • Verify feature extraction is working

  • Review database data quality

Getting Help:

  • Check the troubleshooting guide

  • Review system logs

  • Test with sample data

  • Contact the development team

Configuration Options

Environment Variables:

# Database
export DATABASE_URL="postgresql://user:password@host:5432/database"

# API settings
export API_HOST="0.0.0.0"
export API_PORT="8000"

# Monitoring settings
export DRIFT_THRESHOLD="1.0"
export REPORTS_DIR="reports/monitoring"

# Development settings
export DEBUG="True"
export LOG_LEVEL="INFO"

Configuration File: Create a .env file in the project root:

# .env file
DATABASE_URL=postgresql://monitoring_user:your_password@localhost:5432/monitoring
API_HOST=0.0.0.0
API_PORT=8000
DRIFT_THRESHOLD=1.0
REPORTS_DIR=reports/monitoring
DEBUG=True
LOG_LEVEL=INFO

Docker Setup (Alternative):

# Use Docker Compose for easier setup
docker-compose up -d

# Check services
docker-compose ps

# View logs
docker-compose logs -f

What’s Next?

Now that you have the system running, explore:

  1. API Documentation: Test different endpoints

  2. Monitoring Dashboard: Explore real-time metrics

  3. Drift Reports: Generate and analyze reports

  4. Customization: Adjust settings for your needs

  5. Production Setup: Deploy to production environment

For detailed information, see:

  • api/index - Complete API reference

  • monitoring/index - Monitoring system details

  • troubleshooting - Common issues and solutions