docker-compose.yml

services:
  comfyui:
    build:
      context: .
      dockerfile: Dockerfile
      target: comfyui
    image: comfyui-sync-api:latest
    # VRAM/offload tuning for GPUs with limited VRAM (e.g. MiniMax H3 on a 32 GB
    # card): DynamicVRAM (default on NVIDIA) keeps inactive weights in RAM and
    # streams only active layers to the GPU; --vram-headroom leaves that much
    # VRAM free for other apps. Async weight offloading is OFF by default (set
    # ASYNC_OFFLOAD_STREAMS>0 in .env to enable): its pinned host buffers
    # compete with staged models on RAM-tight boxes.
    #
    # IMPORTANT: MiniMax H3 stages ~26 GB of weights in RAM (UNET + VAEs) plus
    # the CLIP (~15 GB) while running. A 32 GB RAM box OOM-kills (exit 137) at
    # decode without swap — add host swap (e.g. 64 GB) or more RAM, and on
    # swap-backed boxes optionally pass --disable-pinned-memory via COMFYUI_ARGS
    # so staged weights are pageable and can spill to swap instead of OOM.
    command: sh -c 'if [ "$${ASYNC_OFFLOAD_STREAMS:-0}" -gt 0 ] 2>/dev/null; then OFFLOAD="--async-offload $${ASYNC_OFFLOAD_STREAMS}"; else OFFLOAD="--disable-async-offload"; fi; exec python main.py --listen 0.0.0.0 --port 8188 --auto-download-models --vram-headroom $${VRAM_HEADROOM_GB:-2} $OFFLOAD $${COMFYUI_ARGS:-}'
    ports:
      - "8188:8188"
    volumes:
      # Model weights live outside the image. Default ./models; point at a
      # shared project dir to reuse one model store between projects, e.g.
      #   MODELS_DIR=~/VoxMin/ace-step/models   (in .env)
      # (use a dedicated model dir, not the huggingface cache dir).
      - ${MODELS_DIR:-./models}:/opt/ComfyUI/models
      - ./input:/opt/ComfyUI/input
      - ./output:/opt/ComfyUI/output
      - ./temp:/opt/ComfyUI/temp
      - ./user:/opt/ComfyUI/user
      - ./api_server/workflows:/opt/ComfyUI/api_server/workflows
      - ~/VoxMin/ace-step/huggingface:/root/.cache/huggingface
      - ./.triton:/root/.triton
    environment:
      - DO_NOT_TRACK=1
      - HF_HUB_DISABLE_TELEMETRY=1
      # VRAM tuning for the comfyui command above (defaults: 2 GB headroom,
      # async offload OFF — pinned host buffers compete with staged weights
      # on RAM-tight boxes).
      - VRAM_HEADROOM_GB=${VRAM_HEADROOM_GB:-2}
      - ASYNC_OFFLOAD_STREAMS=${ASYNC_OFFLOAD_STREAMS:-0}
      # HF_TOKEN is passed through from the host env or a .env file (required
      # for gated models, e.g. the FLUX.2 klein 9B fp8 checkpoint).
      - HF_TOKEN=${HF_TOKEN:-}
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8188/system_stats')"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s

  developer-api:
    image: comfyui-sync-api:latest
    depends_on:
      comfyui:
        condition: service_healthy
    command: uvicorn api_server.developer_api:app --host 0.0.0.0 --port 8000
    ports:
      - "8000:8000"
    volumes:
      - ./api_server/workflows:/opt/ComfyUI/api_server/workflows
    environment:
      - COMFYUI_BASE_URL=http://comfyui:8188
      - COMFYUI_WORKFLOW_DIR=/opt/ComfyUI/api_server/workflows
      - COMFYUI_API_TIMEOUT_SECONDS=900
      - COMFYUI_API_POLL_INTERVAL_SECONDS=1.0
    restart: unless-stopped