BrakePoint Model Service

BrakePoint model-serving API and worker stack for video inference.

API Contract (unchanged)

• POST /jobs/video
• GET /health
• GET /jobs/{job_id}

Model Artifacts Are External (not in Git)

This repository does not store runtime model artifacts. Copy these files to the server model directory:

• vehicles.pt
• yolov8m.pt
• traffic_sign.pth
• botsort.yaml

Expected server location:

/opt/brakepoint-model-service/models/
  vehicles.pt
  yolov8m.pt
  traffic_sign.pth
  botsort.yaml

Required environment variables:

• MODEL_DIR (shared base directory)
• VEHICLES_MODEL_PATH
• PRETRAINED_YOLO_MODEL_PATH
• TRAFFIC_SIGN_MODEL_PATH
• TRACKER_CONFIG_PATH

Defaults are shown in .env.example.

On service startup, the API validates these files and fails fast with a clear error if any are missing.

Recommended Deployment (host-based, non-Docker)

This server currently uses direct host deployment instead of Docker because GPU containers are not available in this LXC environment.

1. Create directories:

sudo mkdir -p /opt/brakepoint-model-service/{app,data/incoming,data/results,models}

2. Copy project files to /opt/brakepoint-model-service and copy model artifacts into /opt/brakepoint-model-service/models/.

3. Create Python virtual environment and install dependencies:

cd /opt/brakepoint-model-service
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

4. Create env file:

cp .env.example .env

5. Start Redis:

redis-server --daemonize yes

6. Start API:

source /opt/brakepoint-model-service/.venv/bin/activate
cd /opt/brakepoint-model-service
export $(grep -v '^#' .env | xargs)
uvicorn app.main:app --host 0.0.0.0 --port 8000

7. Start Celery worker (separate terminal/session):

source /opt/brakepoint-model-service/.venv/bin/activate
cd /opt/brakepoint-model-service
export $(grep -v '^#' .env | xargs)
celery -A app.jobs.celery_app worker --loglevel=info --concurrency=1

8. Put Nginx in front of Uvicorn:

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 2G;
    }
}

9. Health check:

curl http://127.0.0.1/health

Docker Files

Dockerfile and docker-compose.yml are kept in this repository for future containerized deployment work, but current production usage is host-based in this environment.

GitHub Actions Secrets

For .github/workflows/deploy.yml in the current host-based setup, the only required secret is:

• GPU_SERVER_SSH_KEY

Connection target values are hardcoded in the workflow:

• host: altdsidccf.dlsu.edu.ph
• username: root
• port: 34011