ocr/docs/deployment.md

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

```sh
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:

```sh
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.