Self-host with Docker#

Pick the right image#

Start here if you are not sure which one to pull.

Default recommendation: pull withoutbg/withoutbg-openweights-v3-app-cpu:latest if you want to see it working in under a minute. Switch to service-* when you are integrating programmatically and do not need the UI.

When Docker is not the best fit:

• Python library — pip install withoutbg if you want to embed inference in an existing Python process without container overhead.
• Mac app — native macOS app for a desktop GUI with no terminal.
• No install — Hugging Face Space or the hosted demo at withoutbg.com.

Quick start#

Web app (most people start here)#

First startup loads and warms the model (usually 10–30 seconds on CPU). Wait until /health returns {"status":"ok"} before uploading large batches.

API only#

On app images, prefix paths with /api (e.g. /api/v1/remove-background on port 8080).

# Liveness
curl http://localhost:8000/health

# Readiness (503 until model is warmed up)
curl http://localhost:8000/ready

# Remove background — works on macOS and Linux
IMAGE_B64=$(base64 < photo.jpg | tr -d '\n')
curl -X POST http://localhost:8000/v1/remove-background \
  -H "Content-Type: application/json" \
  -d "{\"image\":\"${IMAGE_B64}\"}"

Request body:

{
  "image": "<raw base64 string, or data:image/jpeg;base64,...>"
}

Response fields:

Example response:

{
  "processed": "data:image/png;base64,...",
  "alphaMatte": "data:image/png;base64,...",
  "latencyMs": 842
}

Error responses:

Full schema and try-it-out UI: http://localhost:8000/docs

GPU images#

Requires an NVIDIA GPU and the NVIDIA Container Toolkit.

# API
docker run --rm --gpus all -p 8000:8000 \
  withoutbg/withoutbg-openweights-v3-service-gpu:latest

# Web app
docker run --rm --gpus all -p 8080:8080 \
  withoutbg/withoutbg-openweights-v3-app-gpu:latest

If the container starts but inference is slow, check logs for the active ONNX Runtime provider. GPU images require CUDAExecutionProvider; they will fail fast at startup if CUDA is unavailable.

The four images#

Docker Hub namespace: withoutbg/withoutbg-openweights-v3-*

Service images (API only)#

Headless FastAPI server. Use these for backends, batch jobs, microservices, and production deployments.

Endpoints (direct on port 8000):

App images (web UI + API)#

Same inference service, plus a static Next.js UI served by nginx. The API is proxied under /api.

What you get on port 8080:

• / — drag-and-drop background removal UI
• /api/v1/remove-background — same API as the service image
• /health — proxied liveness check

At a glance#

Service vs app#

CPU vs GPU#

Docker Compose#

For local or server deployment with published images:

services:
  app:
    image: withoutbg/withoutbg-openweights-v3-app-cpu:latest
    ports:
      - "8080:8080"
    restart: unless-stopped

  # Uncomment for API-only deployment:
  # api:
  #   image: withoutbg/withoutbg-openweights-v3-service-cpu:latest
  #   ports:
  #     - "8000:8000"
  #   restart: unless-stopped

  # GPU variant (requires nvidia-container-toolkit):
  # api-gpu:
  #   image: withoutbg/withoutbg-openweights-v3-service-gpu:latest
  #   ports:
  #     - "8000:8000"
  #   deploy:
  #     resources:
  #       reservations:
  #         devices:
  #           - driver: nvidia
  #             count: all
  #             capabilities: [gpu]

Save as compose.yaml, then:

docker compose up -d

The source repository also ships a docker-compose.yml wired to locally built image names. Use that when developing from source with docker buildx bake.

Image tags#

For reproducible deployments, prefer a sha-* or semver tag over latest.

System requirements#

Rough guidance. Actual latency depends on image size and hardware.

CPU images#

• RAM: 4 GB minimum, 8 GB recommended (model + ONNX Runtime + FastAPI)
• Disk: ~2 GB pulled image size
• CPU: Any x86_64 or arm64 host that runs Docker; inference is slower on low-core machines
• GPU: Not required

Expect roughly 2–15 seconds per image on a modern laptop CPU for a typical photo.

GPU images#

• GPU: NVIDIA GPU with CUDA support (CUDA 12.x runtime in image)
• Driver: Recent NVIDIA driver compatible with CUDA 12.4
• RAM: 8 GB system RAM recommended
• Disk: ~5–8 GB pulled image size (CUDA base layer)

GPU images are significantly faster for repeated inference but have a larger footprint and require NVIDIA Container Toolkit on the host.

Production notes#

Health checks#

• Use /health for liveness (is the process running?).
• Use /ready for readiness (is the model loaded?). Returns 503 until warmup completes. Important for Kubernetes readinessProbe so traffic is not routed to a cold container.

Kubernetes probes (service image on port 8000):

readinessProbe:
  httpGet:
    path: /ready
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 5
livenessProbe:
  httpGet:
    path: /health
    port: 8000
  periodSeconds: 10

Scaling#

• Each container runs a single uvicorn worker with one loaded model session. Scale horizontally by running multiple containers behind a load balancer rather than increasing --workers.
• Inference is serialized per container (thread lock on the model). For high throughput, run several replicas.

Security#

• Images run as non-root user withoutbg (uid 1000).
• No outbound network is required after the image is built. The model is baked in at build time.
• Put a reverse proxy (nginx, Caddy, Traefik) in front for TLS termination if exposed beyond localhost.

Request limits#

• App images accept uploads up to 50 MB via nginx (client_max_body_size).
• Input images are letterboxed to 1024×1024 for inference; output is returned at the original resolution.

Troubleshooting#

Build from source#

To build locally instead of pulling from Docker Hub:

git clone https://github.com/withoutbg/withoutbg-inference.git
cd withoutbg-inference
docker buildx bake -f docker-bake.hcl          # all four images
docker buildx bake -f docker-bake.hcl app-cpu  # single target
docker compose up app-cpu                       # run locally built image

CI publishes to Docker Hub on every push to main and on v3.* release tags.

Related resources#

Docker Hub repos#

• service-cpu
• service-gpu
• app-cpu
• app-gpu