feat(backend): add Dockerfile, .dockerignore, and corrected .env schema for HF Spaces deploy

.dockerignore

@@ -0,0 +1,71 @@
+# =============================================================================
+# .dockerignore — keep the build context tiny.
+# Everything not needed by the backend runtime is excluded.
+# =============================================================================
+
+# --- VCS / IDE ---------------------------------------------------------------
+.git
+.github
+.gitignore
+.gitattributes
+.vscode
+.idea
+*.swp
+
+# --- Python caches & build artefacts -----------------------------------------
+__pycache__
+*.py[cod]
+*$py.class
+*.egg-info
+.eggs
+build
+dist
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.coverage
+.coverage.*
+htmlcov
+.tox
+
+# --- Virtual envs ------------------------------------------------------------
+.venv
+venv
+env
+
+# --- Frontend (deployed separately to Vercel) --------------------------------
+frontend
+node_modules
+
+# --- Tests, notebooks, docs --------------------------------------------------
+tests
+notebooks
+docs
+assets
+scripts
+
+# --- Local dev / secrets -----------------------------------------------------
+.env
+.env.*
+!.env.example
+*.local
+
+# --- OS junk -----------------------------------------------------------------
+.DS_Store
+Thumbs.db
+
+# --- Docker / CI configs (not needed inside the image) -----------------------
+Dockerfile
+.dockerignore
+.pre-commit-config.yaml
+Makefile
+CLAUDE.md
+
+# --- Lockfiles / dev-only deps -----------------------------------------------
+requirements-dev.txt
+requirements-eval.txt
+
+# --- Model artefacts: keep ONLY the production version -----------------------
+# (Add explicit exceptions here if you publish multiple versions.)
+models/**/*.tar
+models/**/*.zip

.env.example

@@ -3,33 +3,50 @@
 # -----------------------------------------------------------------------------
 # Copy this file to `.env` (which is gitignored) and fill in real values.
 # `pydantic-settings` automatically reads `.env` at startup and validates each
-# field. Variables prefixed CAPTIONING__ override nested config keys (see
-# `src/captioning/config/schema.py`); double underscore is the nesting delimiter.
+# field.
 #
-# Example: CAPTIONING__TRAIN__BATCH_SIZE=32 overrides AppConfig.train.batch_size.
+# Two prefixes are read by the application:
+#   BACKEND_*               -> backend/app/core/config.py (BackendSettings)
+#   CAPTIONING__<sec>__<k>  -> src/captioning/config/schema.py (AppConfig)
+# Nested AppConfig fields use a double-underscore delimiter:
+#   CAPTIONING__TRAIN__BATCH_SIZE=32  overrides AppConfig.train.batch_size
 # =============================================================================
 
 # ---- App-wide ----------------------------------------------------------------
 APP_ENV=development                          # development | staging | production
 LOG_LEVEL=INFO                               # DEBUG | INFO | WARNING | ERROR
 
-# ---- Backend (FastAPI) -------------------------------------------------------
-PORT=8000
-# Directory where weights/vocab are downloaded at startup. Empty in the image
-# layer; populated by `huggingface_hub.snapshot_download`. Use a writable path.
-MODEL_DIR=./models/cache
-MAX_UPLOAD_BYTES=10485760                    # 10 MB; rejects oversized images
-# Comma-separated list of allowed origins for CORS. In production, the Vercel
-# frontend URL only. NEVER use "*" in prod.
-CORS_ALLOWED_ORIGINS=http://localhost:3000,https://your-frontend.vercel.app
-
-# ---- HuggingFace Hub (model artefact storage) --------------------------------
-# Public model repo holding the trained weights, vocab.pkl, config.yaml.
+# ---- BackendSettings (FastAPI process) --------------------------------------
+BACKEND_CONFIG_PATH=configs/base.yaml
+BACKEND_WEIGHTS_PATH=models/v1.0.0/model.h5
+BACKEND_TOKENIZER_DIR=models/v1.0.0
+BACKEND_MODEL_VERSION=v1.0.0
+BACKEND_API_VERSION=0.1.0
+BACKEND_WARMUP=true
+BACKEND_REQUEST_ID_HEADER=x-request-id
+
+# ---- AppConfig overrides (research-side hyperparameters) --------------------
+# CORS allow-list lives in configs/base.yaml under `serve.cors_allowed_origins`.
+# Override it for prod by setting the env var below to a JSON list.
+# CAPTIONING__SERVE__CORS_ALLOWED_ORIGINS=["https://your-frontend.vercel.app"]
+# CAPTIONING__SERVE__MAX_UPLOAD_BYTES=10485760
+# CAPTIONING__INFERENCE__DECODE_STRATEGY=beam
+# CAPTIONING__INFERENCE__BEAM_WIDTH=3
+
+# ---- TensorFlow runtime tuning (optional, for HF Spaces cpu-basic) ----------
+# TF_CPP_MIN_LOG_LEVEL=2          # silence INFO/WARNING from TF
+# OMP_NUM_THREADS=2               # match cpu-basic vCPU count
+# TF_NUM_INTEROP_THREADS=1
+# TF_NUM_INTRAOP_THREADS=2
+
+# ---- HuggingFace Hub (model artefact storage — wired up in WS-A4) -----------
+# Public model repo holding the trained weights + vocab.json.
 HF_REPO_ID=your-username/captioning-weights
 HF_REVISION=v1.0.0                           # Pin a specific tag for reproducibility
 # Optional: only needed for private repos or higher rate limits.
 # Generate at https://huggingface.co/settings/tokens (read-only is enough).
 HF_TOKEN=
+# HF_HOME=/home/user/.cache/huggingface
 
 # ---- Experiment tracking (MLflow) --------------------------------------------
 # Local SQLite during dev; DagsHub URL in production.

Dockerfile

@@ -0,0 +1,58 @@
+# syntax=docker/dockerfile:1.7
+# =============================================================================
+# Dockerfile — FastAPI inference backend for HuggingFace Spaces (Docker SDK).
+# -----------------------------------------------------------------------------
+# Target:    HF Spaces, hardware = cpu-basic (2 vCPU / 16 GB RAM).
+# Port:      7860 (HF Spaces convention).
+# User:      UID 1000 named "user" (HF Spaces requirement).
+# Workdir:   /home/user/app (HF Spaces convention).
+# Worker:    uvicorn single worker — keeps the TF model loaded once in RAM.
+# =============================================================================
+
+FROM python:3.11-slim-bookworm
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    TF_CPP_MIN_LOG_LEVEL=2 \
+    HF_HOME=/home/user/.cache/huggingface
+
+# libgomp1 is required by tensorflow-cpu (OpenMP runtime).
+# curl is used by HEALTHCHECK.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgomp1 curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces requires a non-root user with UID 1000 named "user".
+RUN useradd --create-home --uid 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:${PATH}"
+WORKDIR /home/user/app
+
+# --- Dependency layer (cached across code changes) ---------------------------
+COPY --chown=user:user requirements.txt ./
+RUN pip install --user --no-cache-dir -r requirements.txt
+
+# --- Application source ------------------------------------------------------
+# Copy only what the runtime needs. Build context is pruned by .dockerignore.
+COPY --chown=user:user pyproject.toml README.md ./
+COPY --chown=user:user src/ ./src/
+COPY --chown=user:user backend/ ./backend/
+COPY --chown=user:user configs/ ./configs/
+COPY --chown=user:user models/ ./models/
+
+# Install the local captioning package without re-resolving deps.
+RUN pip install --user --no-cache-dir --no-deps -e .
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=90s --retries=3 \
+    CMD curl --fail --silent http://127.0.0.1:7860/healthz || exit 1
+
+CMD ["uvicorn", "app.main:app", \
+     "--app-dir", "backend", \
+     "--host", "0.0.0.0", \
+     "--port", "7860", \
+     "--workers", "1", \
+     "--log-level", "info"]

README.md

@@ -542,7 +542,7 @@ The backend test suite ([`backend/app/tests/`](backend/app/tests/)) introduced i
 
 ### Phase 2C — Public deployment 🚧 (in progress)
 
-- [ ] **WS-A** — Backend containerisation: multi-stage `Dockerfile` (python:3.11-slim, non-root, EXPOSE 7860, HEALTHCHECK) + `.dockerignore` + `.env.example`
+- [x] **WS-A** — Backend containerisation: `Dockerfile` (python:3.11-slim, non-root UID 1000, EXPOSE 7860, HEALTHCHECK on `/healthz`) + `.dockerignore` + corrected `.env.example` schema
 - [ ] **WS-A4** — Lifespan integration with HuggingFace Hub: extend `BackendSettings` with `weights_hub_repo` / `weights_hub_revision`, call `huggingface_hub.snapshot_download` on startup when set
 - [ ] **WS-B** — Upload trained weights + tokenizer to a HuggingFace Hub model repo
 - [ ] **WS-C** — First manual deploy to a HuggingFace Space (Docker SDK, cpu-basic, port 7860, single worker)