From 4088a8b8dd1691ce456d4afd289bf6028062abbc Mon Sep 17 00:00:00 2001
From: Pier-Jean Malandrino <pierjean.malandrino@scub.net>
Date: Wed, 6 May 2026 10:36:15 +0200
Subject: [PATCH] chore(#254): bake Docling model checkpoints into the local
 image
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Eliminates the ~1.3 GB cold-start download on the first conversion. The
new BAKE_MODELS build-arg defaults to true; pass --build-arg
BAKE_MODELS=false to skip and keep the smaller 1.9 GB image when the
deployment can tolerate a slow first run.

Drop the hf_cache volume from compose — a named-volume mount on top of
the baked path would mask the prefetched models with an empty volume on
first 'docker compose up'. The image is now self-contained.

Measured on arm64:
  - latest-local without bake : 1.89 GB
  - latest-local WITH bake    : 3.19 GB (still -48% vs 6.09 GB baseline)
---
 docker-compose.dev.yml     |  4 ----
 docker-compose.yml         |  4 ----
 document-parser/Dockerfile | 10 ++++++++++
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 4253a9d..b71a909 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -93,9 +93,6 @@ services:
       - ./document-parser:/app
       - uploads_data:/app/uploads
       - db_data:/app/data
-      # Persists Docling / HF model checkpoints across container restarts so
-      # the first conversion does not re-download every cold start.
-      - hf_cache:/home/appuser/.cache/huggingface
     environment:
       CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:3000,http://localhost:5173}
       DOCLING_SERVE_URL: ${DOCLING_SERVE_URL:-}
@@ -143,4 +140,3 @@ volumes:
   uploads_data:
   db_data:
   frontend_node_modules:
-  hf_cache:
diff --git a/docker-compose.yml b/docker-compose.yml
index 85eaabb..e98eec5 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -99,9 +99,6 @@ services:
     volumes:
       - uploads_data:/app/uploads
       - db_data:/app/data
-      # Persists Docling / HF model checkpoints across container restarts so
-      # the first conversion does not re-download every cold start.
-      - hf_cache:/home/appuser/.cache/huggingface
     environment:
       CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:3000,http://localhost:5173}
       DOCLING_SERVE_URL: ${DOCLING_SERVE_URL:-}
@@ -136,4 +133,3 @@ volumes:
   neo4j_logs:
   uploads_data:
   db_data:
-  hf_cache:
diff --git a/document-parser/Dockerfile b/document-parser/Dockerfile
index 3d0597d..fd2e5a2 100644
--- a/document-parser/Dockerfile
+++ b/document-parser/Dockerfile
@@ -97,5 +97,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 USER appuser
 
 COPY --from=builder-local --chown=appuser:appuser /opt/venv /opt/venv
+
+# Pre-fetch Docling model checkpoints into the appuser HF cache so the very
+# first conversion does not pay the ~400 MB cold-start download. Opt out
+# with --build-arg BAKE_MODELS=false for an even smaller image (will then
+# download on first request).
+ARG BAKE_MODELS=true
+RUN if [ "$BAKE_MODELS" = "true" ]; then \
+        docling-tools models download; \
+    fi
+
 COPY --chown=appuser:appuser . /app
 ENV CONVERSION_ENGINE=local