Skip to content

Configuration

standoge edited this page Aug 15, 2026 · 2 revisions

Configuration

Full reference for the environment variables read by the app (app/config.py, Pydantic settings loaded from .env). Copy .env.example to .env and fill in your values; on the GCE VM the same variables live in /etc/ocrapi.env.

See also: Architecture · Infrastructure · Job Manager · OCR Plugin · Endpoints.

GCP Document AI

Variable Default Description
GCP_PROJECT_ID — (required) GCP project containing the Document AI processor
GCP_LOCATION us Document AI processor location; also derives the API endpoint {location}-documentai.googleapis.com
GCP_PROCESSOR_ID — (required) Document OCR processor ID
GOOGLE_APPLICATION_CREDENTIALS — Path to service account JSON key (local dev only; on GCE the VM's attached service account is used via ADC)

Google Drive

Variable Default Description
DRIVE_SHARED_FOLDER_ID — Optional default Shared Drive folder for /v1/jobs and /v1/jobs/{jobId}/drive when the request omits a folder ID. Use the full folder ID

Cloud Storage (legacy batch path only)

Variable Default Description
GCS_BUCKET — (optional) GCS bucket for batch OCR scratch. Only the legacy batch path uses it; leave unset otherwise
BATCH_TIMEOUT_SECONDS 1800 Timeout for batch OCR LRO polling
BATCH_POLL_INTERVAL_SECONDS 10 Poll interval for batch OCR

Upload limits

Variable Default Description
MAX_UPLOAD_BYTES 629145600 (600 MB) Maximum upload size for job and sync endpoints
MAX_PDF_PAGES 2000 Maximum pages per PDF (sync and async)

OCR chunking and concurrency

Variable Default Description
ONLINE_CHUNK_PAGES 15 Maximum pages per online OCR chunk
ONLINE_CHUNK_MAX_BYTES 18874368 (18 MB) Maximum bytes per online OCR chunk
ONLINE_MAX_CONCURRENCY 8 Concurrent online processDocument calls per PDF
OCR_WORKER_CONCURRENCY 4 Number of PDFs processed in parallel (async job workers)

Peak concurrent online calls ≈ OCR_WORKER_CONCURRENCY × ONLINE_MAX_CONCURRENCY. The throughput ceiling is the Document AI online pages/min quota — read deploy/gcp/QUOTA.md before raising these. Tuning details: Job Manager.

PDF text-layer assembly

Variable Default Description
PDF_SAVE_INCREMENTAL true PyMuPDF incremental save when injecting the text layer (fast; preserves original bytes). false = full rewrite (smaller output, slower)
PDF_USE_TEXTWRITER true PyMuPDF TextWriter for faster token injection; false falls back to legacy insert_textbox/insert_text

Storage and server

Variable Default Description
JOBS_DIR jobs Directory for job input/output files (relative paths resolve against the repo root; /data/jobs in production)
LOG_LEVEL INFO Application log level
APP_HOST 0.0.0.0 Declared in config but not consumed by the app — the bind address comes from the uvicorn command line
APP_PORT 8000 Declared in config but not consumed by the app — the port comes from the uvicorn command line

Clone this wiki locally