Installation, deployment review and rollback
Do not run the original linux.sh, root Dockerfile, or an HF upload as part of this
OCR rollout: they manage the existing application. No production deploy/restart
has been authorized. Work in the isolated implementation worktree.
Reproduce locally
Python 3.11, Linux x86_64. Use a separate venv; no dependency change to the existing application is necessary. Keep TLS and package/model checksum verification enabled.
python3.11 -m venv /tmp/ocr-venv
/tmp/ocr-venv/bin/pip install --require-hashes -r ocr/requirements.lock
/tmp/ocr-venv/bin/pip install -r ocr/requirements-dev.txt
export OCR_MODELS_DIR=/opt/ocr-models # select an operator-writable location
/tmp/ocr-venv/bin/python -m ocr.download_models
/tmp/ocr-venv/bin/python -m pytest -c pytest-ocr.ini
OCR_RUN_LIVE_CPU=1 /tmp/ocr-venv/bin/python -m pytest -c pytest-ocr.ini ocr/tests/test_live.py
/tmp/ocr-venv/bin/python -m ocr.fixtures.generate /tmp/ocr-fixtures
/tmp/ocr-venv/bin/python -m ocr.cli run /tmp/ocr-fixtures/de-scan.pdf --format markdown
ocr/.env.example lists settings without secrets. The application reads environment
variables directly; it does not load arbitrary .env files. On Debian, a reviewed
service manager can inject an EnvironmentFile with mode 0600. On HF, enter values
under Space Settings → Secrets; those become environment variables at startup.
The dispatcher uses OCR_DISPATCHER_TOKEN; the CPU Space uses only
OCR_CPU_AUTH_TOKEN. Configure the dispatcher with that token plus OCR_CPU_URL.
FREELLMAPI_BASE_URL must be the actual existing private API URL including /v1;
FREELLMAPI_API_KEY stays on Debian. OCR_GPU_MODEL must remain alias-ocr.
They can be filled later from runtime secrets, as requested; there are no stored
credential values or guessed endpoints. Never place FreeLLMAPI keys in a public
CPU worker. If a separate HF-hosted dispatcher is later desired, it needs its own
trust review and cannot reach a Debian loopback address by itself.
Start the dispatcher only on an operator-approved loopback socket or Unix socket,
for example through existing private ingress using uvicorn ocr.api:app --uds /path/to/approved/ocr.sock --workers 1 --no-access-log. Select the approved writable
socket location; do not create new public listeners. One process is required for
consistent in-memory jobs. Existing services need no restart.
Separate CPU Space
Review the target Space identity, privacy, token and D0-only egress policy first.
Agent.md names the existing application Space, not a newly selected OCR Space.
Do not overwrite it. Stage only ocr/, ocr/deploy/hf-cpu/Dockerfile as root
Dockerfile, and ocr/deploy/hf-cpu/README.md as root README.md. The README
contains Docker SDK/app_port 7860 metadata. CPU worker never calls Debian.
Build from repository root:
docker build -f ocr/deploy/hf-cpu/Dockerfile -t hybrid-ocr-cpu:review .
In the managed cloud proxy, supply its public trust bundle as an ephemeral BuildKit
secret (--secret id=proxy_ca,src=/etc/ssl/certs/ca-certificates.crt). Do not disable
TLS verification. Build-time destinations: package registry, Debian signed package
mirrors and pinned ModelScope model URLs/CDNs. Models are checksum-verified and
baked into the image. No inference-time model download is needed.
The reviewed image runs non-root, one Uvicorn worker, ORT intra-op 2/inter-op 1 and OpenCV 2 threads. Test with CPU/memory limits and no host port publication. A real HF CPU Basic deployment must be explicitly approved, followed by authenticated health/readiness, public-fixture OCR, memory/cold-start measurements, sleep/wake checks and D0-only dispatcher integration. No availability guarantee for sleeping Spaces is made.
Alias qualification later
Set the private URL/key securely, leave sensitive data out, then run
python -m ocr.cli probe-alias. Review observed model/provider output with the
FreeLLMAPI operator. /v1/models or an alias name alone cannot qualify routing.
OCR_ENABLE_GPU=true permits only D0 after a successful multimodal challenge;
D1/D2 remain blocked. Grounding/provider enforcement must be separately audited
before any D2 extension. Reprobe after model/config changes; qualification expires
after one hour, after which requests fail closed until a controlled restart/reprobe.
Overflow stays disabled until real CPU/GPU mixed 20+/100-page batches demonstrate
15% end-to-end gain under approved budgets. Enable both operator gates plus caller permission only after retaining that evidence. Mocked timing tests are not evidence.
Rollback
Disable new dispatcher ingress or set OCR_ENABLE_GPU=false and select cpu_only.
Stop only this new worker/dispatcher after owner approval. Revert the implementation
commit in a review branch if needed; no migration or existing service rollback is
required. Retained in-memory jobs are lost on restart; clients must resubmit with
explicit awareness that remote work may already have executed. Keep D2 local until
an audited destination enforcement design is delivered.