From 193a4d6ee625ab5e5a7978457e47a3cb98e8a504 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Mon, 18 May 2026 11:23:04 +0200
Subject: [PATCH] =?UTF-8?q?docs(deployment):=20document=20ocr-volume-init?=
 =?UTF-8?q?=20bootstrap=20service=20in=20=C2=A78=20upgrade=20notes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explains what ocr-volume-init does (chown volumes + create TMPDIR), how to
verify it succeeded (docker logs), and what failure looks like. Addresses
reviewer concerns from @mkeller and @tobiwendt on PR #615.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/DEPLOYMENT.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index aaba04e2..945346ae 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -564,6 +564,22 @@ bash scripts/download-kraken-models.sh
 
 Version-specific one-time steps that must be run before or after upgrading to a given release. Each subsection is safe to skip on a fresh install.
 
+### Upgrading to PR #615 — TMPDIR redirect + ocr-volume-init
+
+`ocr-volume-init` is a new one-shot service in both compose files that runs before `ocr-service` on every `docker compose up`. It:
+
+1. `chown -R 1000:1000 /app/cache /app/models` — corrects volume ownership so the non-root `ocr` user (uid 1000) can write to volumes that may have been created as root (including volumes from before PR #611).
+2. `mkdir -p /app/cache/.tmp` — creates the TMPDIR staging directory that Surya uses for GB-scale model downloads. Without this directory, the first model download falls back to the 512 MB `/tmp` tmpfs and fails with ENOSPC. See ADR-021.
+
+**Verify it succeeded:**
+```bash
+docker logs archiv-ocr-volume-init   # dev
+docker logs archiv-production-ocr-volume-init-1   # prod
+```
+Expected output: no error lines; exit code 0.
+
+**Failure mode:** if `chown` is denied (e.g. the volume is mounted read-only), the container exits non-zero and `ocr-service` will not start (`depends_on: condition: service_completed_successfully`). Check `docker logs` for the `chown` error and verify the volume is writable.
+
 ### Upgrading to PR #611 — non-root OCR container
 
 The OCR cache volume path changed from `/root/.cache` to `/app/cache` (PR #611 — CIS Docker §4.1 hardening). The existing volume was written as root and is inaccessible to the new non-root `ocr` user, causing a `PermissionError` on startup.