chore: add hugging face docker deployment

.dockerignore

@@ -0,0 +1,12 @@
+.git
+.venv
+.uv-cache
+.runtime
+.env
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+docs
+tests

Dockerfile

@@ -0,0 +1,31 @@
+FROM nvidia/cuda:12.6.3-cudnn-runtime-ubuntu24.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    UV_CACHE_DIR=/home/ubuntu/.cache/uv \
+    HF_HOME=/home/ubuntu/.cache/huggingface \
+    TRANSFORMERS_CACHE=/home/ubuntu/.cache/huggingface/transformers \
+    DIFFUSERS_CACHE=/home/ubuntu/.cache/huggingface/diffusers
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        python3.12 \
+        python3.12-venv \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:0.5.31 /uv /uvx /usr/local/bin/
+
+USER ubuntu
+WORKDIR /home/ubuntu/app
+
+COPY --chown=ubuntu:ubuntu pyproject.toml uv.lock README.md ./
+COPY --chown=ubuntu:ubuntu catbox ./catbox
+COPY --chown=ubuntu:ubuntu experiments ./experiments
+
+RUN uv sync --frozen --no-dev
+
+EXPOSE 7860
+
+CMD ["uv", "run", "--no-sync", "python", "-m", "catbox.browser_ui", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,3 +1,9 @@
+---
+title: Catbox
+sdk: docker
+app_port: 7860
+---
+
 # catBox
 
 Catbox is an interactive image-generation demo. You open a sealed box, a local
@@ -155,3 +161,29 @@ For the complete first-observation GPU validation checklist, including Browser
 UI readiness, normal observation, forced Dev Controls outcomes, runtime timing,
 ephemeral output files, and failure retry/reset behavior, see
 `docs/manual-gpu-validation.md`.
+
+## Deploy on Hugging Face Spaces
+
+The preferred public deployment target is a Docker Hugging Face Space with GPU
+hardware. The container serves Catbox on port `7860`, which is the default
+external port for Spaces.
+
+Create a new Hugging Face Space with these settings:
+
+- SDK: Docker
+- Visibility: Public or Protected
+- Hardware: start with `1x Nvidia L4`; use `Nvidia A10G - small` if L4 is too
+  slow or unavailable
+
+Add a Space secret named `HF_TOKEN` if the model download requires
+authenticated Hugging Face access.
+
+Push this repository's contents to the Space git remote. The Space README
+metadata at the top of this file tells Hugging Face to build the Docker image
+and expose port `7860`. The Space will start `python -m catbox.browser_ui`,
+download `sd-turbo` on first startup if it is not already cached, and serve the
+app from the Space URL.
+
+Generated outcomes and Captured Denoising Trace frames are still ephemeral in
+the deployed container. They are written under `.runtime/generated-outcomes` and
+may be lost when the Space restarts.