ppetermm/image-preprocessing-ensemble-dr-classifier-service

Fundus DR Inference Service

Production-ready Docker image for diabetic retinopathy inference from retinal fundus images.

This service exposes a REST API that can:

• preprocess a single input image into 5 model-ready variants,
• run ensemble classification (0-4 DR classes),
• return health, model, and runtime configuration metadata.

What This Image Runs

Container entrypoint starts:

python fundus_inference_server.py --preprocessing-config configs/preprocessing_config.yaml --classifier-config configs/classifier_config.yaml --host 0.0.0.0 --port 5000

Default exposed port: 5000

Main Features

• 5-variant preprocessing pipeline:
  • original (clipped)
  • RGB-CLAHE
  • Ben Graham / min-pooling
  • LAB-CLAHE
  • MaxGreenGsc
• Ensemble classifier support with voting strategy:
  • soft (default)
  • hard
• Health and operational endpoints for deployment checks.
• Optional Redis integration for caching (when runtime environment enables it).

Quick Start

bash
docker run --rm -p 5000:5000 \
  --name fundus-inference \
  <your-dockerhub-user>/image-preprocessing-ensemble-dr-classifier-service:latest

Environment Variables

Adding env vars to Docker docs is a best practice for reproducible deploys.

Common runtime variables:

• AZURE_STORAGE_SAS_TOKEN:
  • Used when runtime needs access to Azure Blob-backed artifacts.
  • Recommended to provide via secret manager or CI/CD runtime injection.
• REDIS_HOST (default from compose usage: redis):
  • Redis hostname for cache integration.
• REDIS_PORT (default: 6379):
  • Redis port.
• REDIS_PASSWORD (optional):
  • Redis password when auth is enabled.
• MAX_CONTENT_LENGTH_MB (default: 8):
  • Maximum accepted request payload size in MB.
• PYTHONUNBUFFERED=1:
  • Immediate log flushing to stdout/stderr.

Example with environment variables:

bash
docker run --rm -p 5000:5000 \
  --name fundus-inference \
  -e AZURE_STORAGE_SAS_TOKEN="<your-sas-token>" \
  -e REDIS_HOST="redis" \
  -e REDIS_PORT="6379" \
  -e MAX_CONTENT_LENGTH_MB="8" \
  -e PYTHONUNBUFFERED="1" \
  <your-dockerhub-user>/image-preprocessing-ensemble-dr-classifier-service:latest

Health check:

bash
curl http://localhost:5000/health

Run full pipeline (/process):

bash
curl -X POST "http://localhost:5000/process?voting_strategy=soft" \
  -F "image=@fundus_image.jpg"

API Endpoints

• GET /health
• GET /info
• GET /config
• GET /models
• POST /preprocess
• POST /classify
• POST /process

Image Tags and Release Policy

This image is published by GitHub Actions from semantic tags.

• Workflow: .github/workflows/dockerhub-release.yml
• Trigger: push tag matching v*.*.* (example: v1.2.3)
• Safety check: release tag must point to a commit reachable from main
• Published tags include:
  • exact version (for example v1.2.3)
  • semver aliases (1.2.3, 1.2, 1)
  • latest

Recommended production usage:

• pin immutable version tags (for example v1.2.3) in deployments,
• avoid relying only on latest.

Required CI/CD Secrets (Repository Side)

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN
• AZURE_STORAGE_SAS_TOKEN
• repository variable: DOCKERHUB_REPOSITORY (format: namespace/repository)

Notes

• This image is optimized for inference serving and API integration.
• For complete project docs and compose-based deployment, see repository README.md and build/docker/.