detections/_docs/04_deploy/containerization.md

Containerization Plan

Image Variants

detections-cpu (Dockerfile)

Aspect	Specification
Base image	python:3.11-slim (pinned digest recommended)
Build stages	Single stage (Cython compile requires gcc at runtime for setup.py)
Non-root user	adduser --disabled-password --gecos '' appuser + USER appuser
Health check	HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8080/health || exit 1
Exposed ports	8080
Entrypoint	uvicorn main:app --host 0.0.0.0 --port 8080

Changes needed to existing Dockerfile:

1. Add non-root user (security finding F7)
2. Add HEALTHCHECK directive
3. Pin python:3.11-slim to specific digest
4. Add curl to apt-get install (for health check)

detections-gpu (Dockerfile.gpu)

Aspect	Specification
Base image	nvidia/cuda:12.2.0-runtime-ubuntu22.04
Build stages	Single stage
Non-root user	adduser --disabled-password --gecos '' appuser + USER appuser
Health check	HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8080/health || exit 1
Exposed ports	8080
Entrypoint	uvicorn main:app --host 0.0.0.0 --port 8080
Runtime	Requires --runtime=nvidia or nvidia runtime in Docker

Changes needed to existing Dockerfile.gpu:

1. Add non-root user
2. Add HEALTHCHECK directive
3. Add curl to apt-get install

.dockerignore

.git
.gitignore
_docs/
_standalone/
e2e/
tests/
*.md
.env
.env.*
.cursor/
.venv/
venv/
__pycache__/
*.pyc
build/
dist/
*.egg-info
Logs/

Docker Compose — Local Development

docker-compose.yml (already partially exists as e2e/docker-compose.mocks.yml):

name: detections-dev

services:
  mock-loader:
    build: ./e2e/mocks/loader
    ports:
      - "18080:8080"
    volumes:
      - ./e2e/fixtures:/models
    networks:
      - dev-net

  mock-annotations:
    build: ./e2e/mocks/annotations
    ports:
      - "18081:8081"
    networks:
      - dev-net

  detections:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    depends_on:
      - mock-loader
      - mock-annotations
    env_file: .env
    environment:
      LOADER_URL: http://mock-loader:8080
      ANNOTATIONS_URL: http://mock-annotations:8081
    volumes:
      - ./e2e/fixtures/classes.json:/app/classes.json:ro
      - detections-logs:/app/Logs
    shm_size: 512m
    networks:
      - dev-net

volumes:
  detections-logs:

networks:
  dev-net:
    driver: bridge

Docker Compose — Blackbox Tests

Already exists: e2e/docker-compose.test.yml. No changes needed — supports both cpu and gpu profiles with mock services and test runner.

detections-jetson (Dockerfile.jetson)

Aspect	Specification
Base image	nvcr.io/nvidia/l4t-jetpack:r36.4.0 (JetPack 6.2.x-compatible, aarch64)
TensorRT	Pre-installed via JetPack — python3-libnvinfer apt package (NOT pip)
PyCUDA	Installed via pip in requirements-jetson.txt because python3-pycuda is not available in the l4t-jetpack:r36.4.0 apt repositories
Build stages	Single stage (Cython compile requires gcc)
Non-root user	adduser --disabled-password --gecos '' appuser + USER appuser
Exposed ports	8080
Entrypoint	uvicorn main:app --host 0.0.0.0 --port 8080
Runtime	Requires NVIDIA Container Runtime (runtime: nvidia in docker-compose)

Jetson-specific behaviour:

• requirements-jetson.txt derives from requirements.txt — tensorrt is excluded from pip and installed from the JetPack/L4T apt packages in Dockerfile.jetson; PyCUDA is installed via pip on this image line because the apt package is unavailable
• Engine filename auto-encodes CC+SM (e.g. azaion.cc_8.7_sm_16.engine for Orin Nano), ensuring the Jetson engine is distinct from any x86-cached engine
• INT8 is used when azaion.int8_calib.cache is available on the Loader service; precision suffix appended to engine filename (*.int8.engine); FP16 fallback when cache is absent
• docker-compose.jetson.yml uses runtime: nvidia for the NVIDIA Container Runtime

Compose usage on Jetson:

docker compose -f docker-compose.jetson.yml up

detections-jetson-trt104 (Dockerfile.jetson.trt104)

Experimental INT8 calibration image for Jetson Orin devices. It uses NVIDIA's TensorRT iGPU container:

Aspect	Specification
Base image	nvcr.io/nvidia/tensorrt:24.09-py3-igpu
TensorRT	TensorRT 10.4.0.26
Purpose	Work around TensorRT 10.3 INT8 calibration failures such as checkSanity.cpp::checkLinks / Graph::regions internal errors

Build/tag example:

docker build -f Dockerfile.jetson.trt104 -t <registry>/azaion/detections:dev-arm-trt104 .

Image Tagging Strategy

Context	Tag Format	Example
CI builds	<registry>/azaion/detections-cpu:<git-sha>	registry.example.com/azaion/detections-cpu:a1b2c3d
CI builds (GPU)	<registry>/azaion/detections-gpu:<git-sha>	registry.example.com/azaion/detections-gpu:a1b2c3d
Local development	detections-cpu:dev	—
Latest stable	<registry>/azaion/detections-cpu:latest	Updated on merge to main