fix: keep published Recoll image below registry upload limit

Dockerfile

@@ -10,7 +10,7 @@ FROM ghcr.io/astral-sh/uv:0.12.16 AS uv-bin
 FROM debian:trixie-slim
 COPY --from=uv-bin /uv /usr/local/bin/uv
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    ca-certificates python3 python3-recoll recoll poppler-utils python3-lxml unzip \
+    ca-certificates python3 python3-recoll recollcmd poppler-utils python3-lxml unzip \
     && rm -rf /var/lib/apt/lists/*
 COPY --from=helper-build /build/recoll-membership /usr/local/bin/recoll-membership
 WORKDIR /app
@@ -25,7 +25,8 @@ ENV VIRTUAL_ENV=/opt/venv \
     RECOLL_MODERN_STATE_ROOT=/var/lib/recoll-modern \
     RECOLL_MODERN_RECOLL_CONFIG_DIR=/var/lib/recoll-modern/recoll-config \
     RECOLL_MODERN_MEMBERSHIP_MAP=/var/lib/recoll-modern/membership.map
-RUN uv sync --locked --no-dev && python -c 'from recoll import recoll'
+RUN uv sync --locked --no-dev && python -c 'from recoll import recoll' \
+    && command -v recollindex && command -v recollq
 COPY docker/recoll.conf docker/fields /etc/recoll-modern/
 COPY docker/entrypoint.sh /usr/local/bin/recoll-modern-entrypoint
 RUN chmod 755 /usr/local/bin/recoll-modern-entrypoint \

docs/ARCHITECTURE.md

@@ -126,12 +126,13 @@ path under the configured root. Original downloads open a contained regular file
 directory descriptors and stream from the pinned descriptor, including single byte ranges; inline
 display is limited to safe media types.
 
-The image installs Recoll and its Python binding from Debian trixie, and syncs the application into a
-system-site-packages venv so the binding remains importable. A separate build stage compiles the C
-helper. The non-root process copies Recoll config templates into the persistent state volume only when
-absent; Recoll may generate additional support files there. Compose mounts documents read-only and
-keeps the SQLite/config and Xapian index volumes separate. Initial health can be 503 until an indexing
-job creates the first index.
+The image installs Debian trixie's headless `recollcmd` package and Python binding.
+It syncs the application into a system-site-packages venv so the binding remains
+importable. A separate build stage compiles the C helper. The non-root process
+copies Recoll config templates into the persistent state volume only when absent;
+Recoll may generate additional support files there. Compose mounts documents
+read-only and keeps the SQLite/config and Xapian index volumes separate. Initial
+health can be 503 until an indexing job creates the first index.
 
 Gitea Actions tests and builds on pull requests, main pushes and version tags. A dependent job publishes
 `linux/amd64` images only for main and full `vX.Y.Z` tags. `main` follows the branch; `latest` follows

docs/DECISIONS.md

@@ -426,3 +426,19 @@ raises an internal-file error.
 **Alternatives:** catch the generic extraction error, which would hide genuine extraction failures.
 **Consequences:** exact-path text lookup follows the engine contract for missing documents while real
 extraction failures still surface as `engine_unavailable`.
+
+---
+
+## 2026-09-28 — Install headless Recoll command package in the published image
+**Status:** accepted
+**Context:** Gitea's registry is behind Cloudflare's 100 MB request limit. The Docker image's Debian
+`recoll` metapackage pulled in `recollgui` and Qt WebEngine, producing a 273 MB compressed layer. The
+registry rejected that layer with HTTP 413, so no image manifest was published.
+**Decision:** install Debian's `recollcmd` package instead. It supplies `recollindex` and `recollq`
+without the unused graphical interface. Keep the Python binding and document filters, and check the
+command binaries during the image build.
+**Alternatives:** bypass Cloudflare for registry uploads; split the same GUI dependencies across Docker
+layers. A split-package probe still produced a 253 MB compressed layer.
+**Consequences:** the service remains headless. The full image's largest compressed layer is 39.02 MB,
+and a local container confirms both Recoll commands and the Python binding are present. Registry
+publishing and pulling still require a successful Gitea Actions run.