Skip to content

deploy.md

Latest commit

 

History

History
183 lines (123 loc) · 5.45 KB

deploy.md

File metadata and controls

183 lines (123 loc) · 5.45 KB
Raw

Deployment Guide

This guide covers the most practical ways to run aerotrack beyond local development.

Recommended no-cost path

If the goal is a public challenge URL without committing to monthly spend, the best current fit is a single free Render web service for the API demo.

Why this is the best default:

  • Render officially supports free web-service instances in render.yaml
  • Docker deployments are supported directly from your repository
  • the free web tier is enough for a low-traffic portfolio demo
  • the tradeoff is that free services can spin down when idle, so it is best for demos, judging, and portfolio review rather than production uptime

Recommended public architecture:

  • deploy the FastAPI browser demo only
  • make MLflow optional for the public URL
  • fetch the chosen checkpoint at startup using AEROTRACK_MODEL_URL
  • keep uploads short and demo-oriented

Deployment modes

1. Local Docker Compose

Best for:

  • development
  • smoke testing
  • demo recording
  • MLflow experiment review on a single machine

Command:

docker-compose up --build

Services:

  • FastAPI API on localhost:8000
  • MLflow UI on localhost:5001

2. Single-service API deployment

Best for:

  • live challenge demos
  • simple hosted inference endpoints
  • lightweight portfolio deployments

In this mode, deploy only the API container and point it at:

  • a preloaded model path
  • an external MLflow tracking server, if you want experiment logging

Good fits:

  • Render web service
  • Railway service
  • Fly.io app

Current recommendation:

  • choose Render first for the public demo, because it has an official free web-service plan and native Blueprint support

3. Split deployment

Best for:

  • more serious demos
  • shared experiment tracking
  • team usage

Recommended split:

  • API service deployed separately
  • MLflow deployed as its own service
  • artifact storage moved to persistent disk or object storage
  • model artifacts/versioning managed outside the API filesystem

Minimum environment variables

For the API service:

API_HOST=0.0.0.0
API_PORT=8000
AEROTRACK_MODEL_PATH=/app/models/aerotrack-detector.pt
AEROTRACK_MODEL_URL=https://example.com/path/to/model.pt
AEROTRACK_DEVICE=cpu
AEROTRACK_CONFIDENCE=0.25
AEROTRACK_IOU=0.45
AEROTRACK_OUTPUT_DIR=/app/outputs
MLFLOW_UI_URL=

AEROTRACK_MODEL_URL is the key to a free-tier deployment with no persistent disk. On startup, the container downloads the model into AEROTRACK_MODEL_PATH if it is not already present.

For MLflow:

MLFLOW_BACKEND_STORE_URI=sqlite:////mlflow/mlflow.db
MLFLOW_ARTIFACT_ROOT=/mlflow/artifacts

Render deployment

The repository includes render.yaml, which defines a free Render web service for the demo app.

The current Blueprint is tuned for a stable free-tier live demo. It intentionally points the public Render deployment at the lighter yolov8n.pt model so the site stays responsive on CPU. The repo still includes the stronger RTX 4070 Ti-trained checkpoint under models/ for local evaluation, project review, and higher-capacity deployments.

Suggested flow:

  1. Push the latest repo state to GitHub.
  2. In Render, create a new Blueprint from the repo.
  3. Keep the service on the free plan.
  4. Leave AEROTRACK_MODEL_URL blank unless you want the container to fetch a custom checkpoint at startup.
  5. Optionally set MLFLOW_UI_URL if you want the homepage to link to a hosted MLflow instance.
  6. Deploy and verify /health, /metadata, /detect, and /track.

Where to host the model file cheaply:

  • a GitHub Release asset
  • a Hugging Face model repository file
  • any public direct-download object URL you control

Why not deploy MLflow on the free path

For the challenge URL, the browser demo matters more than hosting the experiment tracker publicly.

Keeping MLflow out of the first public deployment:

  • reduces memory pressure
  • avoids managing a persistent backend database
  • lowers the risk of free-tier instability

You can still show MLflow locally in recordings and screenshots.

Public demo advice

If you want a cheap live demo:

  1. Deploy the API container first
  2. Start with CPU inference
  3. Start with the lighter bundled live model or use AEROTRACK_MODEL_URL for a custom checkpoint
  4. Keep request sizes small for demo clips
  5. Treat MLflow as optional for the public demo if operating two services is too much friction

API start command

The container already starts with:

uvicorn api.main:app --host 0.0.0.0 --port ${API_PORT}
  • expose /health for quick verification
  • use the browser demo at / as the primary submission URL
  • keep one known-good image and one short clip ready for judging
  • refresh the deployed checkpoint once the stronger GPU-trained model is ready

Production-minded follow-ups

If this repo were extended into a more operational system, the next infrastructure upgrades would be:

  • move MLflow backend from SQLite to Postgres
  • move artifacts to object storage
  • bake model weights into an artifact bundle or registry flow
  • add structured request logging
  • add request size limits and auth in front of the API
  • add a background job path for long-running video tracking

Operational checklist

Before calling a deployment "demo-ready":

  1. GET /health returns 200
  2. POST /detect works on a known sample frame
  3. POST /track works on a known short clip
  4. MLflow UI is reachable if enabled
  5. Model weights are present and do not require surprise downloads during the demo