heartexlab/ml-backend repository overview

⁠ML Backend Base Image (Label Studio–compatible)

A reusable Docker base image for running Label Studio ML⁠ backends with common computer-vision and inference dependencies preinstalled.

This image provides:

• Python runtime (python:3.12-slim)
• OS libraries needed for typical CV pipelines
• Pinned Python dependencies (Label Studio ML, Gunicorn, Ultralytics stack, CPU PyTorch, and related libs)
• A Gunicorn entrypoint with sensible defaults, overridable via environment variables

It does not ship application code or model weights. Build your own image FROM this one, copy your backend package (e.g. _wsgi.py, model classes), and set CMD to your WSGI target.

⁠What it is for

Use as a shared runtime layer when you want:

• A Label Studio ML backend served with Gunicorn
• YOLO/SAM-style inference without rebuilding the same dependency stack in every project

Consumer projects only add their code and configuration on top.

⁠Build

From this directory (where the Dockerfile lives):

docker build --platform=linux/amd64 -t heartexlab/ml-backend:latest .

Include optional test dependencies at build time:

docker build --build-arg TEST_ENV=true --platform=linux/amd64 -t heartexlab/ml-backend:latest .

⁠Runtime defaults

The image ENTRYPOINT runs Gunicorn with:

gunicorn --bind 0.0.0.0:${PORT} --workers ${WORKERS} --threads ${THREADS} --timeout ${TIMEOUT}

Default environment:

Override any of these at docker run time.

⁠Using this image in your app image

Example pattern (replace paths and module names with yours):

FROM heartexlab/ml-backend:latest
WORKDIR /app
COPY your_shared_lib/ ./your_shared_lib/
COPY your_ml_backend/ ./your_ml_backend/
CMD ["your_ml_backend._wsgi:app"]

Run:

docker run --rm -p 9090:9090 \
  -e PORT=9090 \
  -e WORKERS=1 \
  -e THREADS=4 \
  -e TIMEOUT=180 \
  your-registry/your-ml-backend:latest

⁠Models and configuration

This base image only installs Python and system dependencies. How you load weights (local path, object storage, or a database-backed registry) is entirely your application’s responsibility in the image you build on top.

⁠Notes

• Dependencies are pinned for reproducible builds.
• CPU PyTorch wheels are used to avoid pulling CUDA-only dependency chains into a slim image.
• Targets Linux amd64 (linux/amd64) by default.