marcel/familienarchiv
1
0
Fork 0
Code Issues 114 Pull Requests 2 Actions 1 Packages Projects Releases Wiki Activity

docs(deployment): document ocr-volume-init bootstrap service in §8 upgrade notes
All checks were successful
CI / Unit & Component Tests (pull_request) Successful in 3m1s
Details
CI / OCR Service Tests (pull_request) Successful in 20s
Details
CI / Backend Unit Tests (pull_request) Successful in 3m0s
Details
CI / fail2ban Regex (pull_request) Successful in 42s
Details
CI / Semgrep Security Scan (pull_request) Successful in 20s
Details
CI / Compose Bucket Idempotency (pull_request) Successful in 59s
Details
CI / Unit & Component Tests (push) Successful in 3m5s
Details
CI / OCR Service Tests (push) Successful in 19s
Details
CI / Backend Unit Tests (push) Successful in 3m1s
Details
CI / fail2ban Regex (push) Successful in 43s
Details
CI / Semgrep Security Scan (push) Successful in 18s
Details
CI / Compose Bucket Idempotency (push) Successful in 59s
Details

Browse Source 
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>
This commit was merged in pull request #615.
This commit is contained in:
Marcel
2026-05-18 11:23:04 +02:00
parent 3182da8d92
commit 193a4d6ee6
1 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/DEPLOYMENT.md
View File

@@ -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.