build(docker): LLAMA_REF pin to rebuild llama.cpp on demand

small-doc-ie-bench/.env.example

@@ -152,6 +152,15 @@ DOCIE_SERVING_RECONCILE_INTERVAL=10
 # ([wsl2] memory=24GB, then `wsl --shutdown`) before raising this.
 DOCIE_SERVING_MEM_LIMIT=8g
 
+# llama.cpp pin for the serving image's llama-server (build-arg). Empty = latest
+# master HEAD, but the clone+build layer is Docker-CACHED, so `docker compose
+# build serving` reuses the old binary even after upstream moves. To pick up a
+# new architecture (e.g. Unlimited-OCR / deepseek-ocr, llama.cpp#24969 merged
+# 2026-06-24), set a commit/tag AFTER that merge — the changed value busts the
+# cache and rebuilds llama.cpp at the pin (reproducible):
+#   LLAMA_REF=<commit-or-tag>   then  docker compose build serving
+#LLAMA_REF=
+
 # Sizing safety margin (PR-3): the fraction of node TOTAL RAM the Sizing tab /
 # fit gate holds back before pricing prospective instances (fits = floor(
 # (free - margin) / footprint)). Explicit and surfaced in the API/UI — an

small-doc-ie-bench/docker-compose.yml

@@ -139,6 +139,11 @@ services:
         # spawn inside THIS container — it needs the analyzer library. Other
         # services keep the light "ocr" default.
         PIP_EXTRAS: "ocr,encoders"
+        # llama.cpp pin: the serving container holds the llama-server that
+        # actually serves deployed models. Set LLAMA_REF in .env to a commit/
+        # tag to rebuild llama.cpp at that pin (reproducible + picks up new
+        # arch support, e.g. Unlimited-OCR). Empty = latest HEAD (cached).
+        LLAMA_REF: ${LLAMA_REF:-}
     env_file: .env
     mem_limit: ${DOCIE_SERVING_MEM_LIMIT:-8g}
     environment:

small-doc-ie-bench/infra/docker/Dockerfile.api

@@ -11,10 +11,31 @@ FROM python:3.11-slim-bookworm AS llama-builder
 # on a stock Docker Desktop). Override on a roomier machine for speed:
 #   docker compose build --build-arg LLAMA_BUILD_JOBS=8 worker
 ARG LLAMA_BUILD_JOBS=2
+# Pin llama.cpp to a commit/tag for REPRODUCIBLE builds AND to force a rebuild
+# of this (Docker-cached) layer when a needed upstream feature lands. Empty
+# (default) keeps the old behavior — the latest master HEAD, cached forever
+# once built. IMPORTANT: because the clone-and-build below is one RUN whose
+# text never changes, a plain `docker compose build` REUSES the cached
+# llama-server even after upstream HEAD moves. To pick up a new arch (e.g.
+# Unlimited-OCR / deepseek-ocr, ggml-org/llama.cpp#24969, merged 2026-06-24),
+# set LLAMA_REF to a commit/tag AFTER that merge — the changed ARG busts this
+# layer's cache and rebuilds llama.cpp at the pin:
+#   docker compose build --build-arg LLAMA_REF=<commit-or-tag> serving
+# (or `docker compose build --no-cache serving`, but that rebuilds everything).
+ARG LLAMA_REF=
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git build-essential cmake ca-certificates \
   && rm -rf /var/lib/apt/lists/*
-RUN git clone --depth 1 https://github.com/ggml-org/llama.cpp /src \
+# A pinned ref is shallow-fetched (only that commit — GitHub allows any-SHA
+# fetch), so pinning stays as cheap as the --depth 1 clone.
+RUN if [ -n "${LLAMA_REF}" ]; then \
+      git init /src \
+      && git -C /src remote add origin https://github.com/ggml-org/llama.cpp \
+      && git -C /src fetch --depth 1 origin "${LLAMA_REF}" \
+      && git -C /src checkout FETCH_HEAD; \
+    else \
+      git clone --depth 1 https://github.com/ggml-org/llama.cpp /src; \
+    fi \
  && cmake -S /src -B /src/build \
       -DCMAKE_BUILD_TYPE=Release \
       -DBUILD_SHARED_LIBS=OFF \