backend/docs/OCR_SETUP.md

Tesseract OCR Runtime Setup

PyMuPDF + pytesseract require the native tesseract-ocr binary (with Vietnamese language data) to extract text from scanned PDFs. Install it on every environment that runs ingestion or Celery workers.

Docker / CI (Debian-based)

The backend Dockerfile already installs the required packages:

apt-get update && apt-get install -y \
  tesseract-ocr \
  tesseract-ocr-eng \
  tesseract-ocr-vie

For GitHub Actions or other CI images, run the same command before executing tests that touch OCR.

macOS (Homebrew)

brew install tesseract
brew install tesseract-lang # optional (contains vie)

Verify:

tesseract --version
ls /opt/homebrew/Cellar/tesseract/*/share/tessdata/vie.traineddata

Ubuntu / Debian

sudo apt update
sudo apt install -y tesseract-ocr tesseract-ocr-eng tesseract-ocr-vie

Rocky / CentOS (DNF)

sudo dnf install -y tesseract tesseract-langpack-eng tesseract-langpack-vie

Configuration

• Set OCR_LANGS (default vie+eng) if additional language combinations are needed.
• OCR_PDF_ZOOM (default 2.0) controls rasterization DPI; increase for very small fonts.
• Check that tesseract is in $PATH for the user running Django/Celery.

Troubleshooting

1. Run tesseract --list-langs to confirm Vietnamese appears.
2. Ensure the worker container/user has read access to /usr/share/tesseract-ocr/4.00/tessdata.
3. If OCR still fails, set CELERY_TASK_ALWAYS_EAGER=true locally to debug synchronously and inspect logs for pytesseract errors.