danvics/openreader
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openreader/docs-site/docs/deploy/compute-worker.md
Richard R f1aa1c3e3b feat(compute): add external compute worker backend and integration 
Introduce support for external compute worker mode (`COMPUTE_MODE=worker`) using a new `WorkerComputeBackend`. This enables offloading heavy ONNX Whisper alignment and PDF layout parsing to a standalone worker service (Redis + BullMQ), improving scalability and compatibility with serverless/limited environments.

- Add `@openreader/compute-core` as a shared package for ONNX inference and PDF parsing logic.
- Implement `WorkerComputeBackend` and worker contract/types for remote job execution.
- Update compute backend selection logic and remove previous worker mode guards.
- Extend `WhisperAlignInput` and `PdfLayoutInput` types to support object keys for remote data access.
- Refactor local compute backend to use `@openreader/compute-core` and support both buffer and object key inputs.
- Update job runner, TTS segment alignment, and PDF layout parsing flows to use new compute backend APIs.
- Add scripts, Docker workflow, and documentation for deploying and running the compute worker.
- Update environment variable docs and examples for worker mode, including storage requirements and configuration.
- Document published images and stack changes to reflect the new compute worker architecture.

BREAKING CHANGE: `COMPUTE_MODE=worker` now requires an external compute worker service and S3-compatible object storage. Embedded SeaweedFS (`weed mini`) is not supported in worker mode. See the new documentation for deployment and configuration details.
2026-05-19 15:21:25 -06:00

1.7 KiB
Raw Blame History

title
Compute Worker (Redis + BullMQ)

Use this guide for COMPUTE_MODE=worker deployments where heavy compute runs outside the Next.js app server.

Overview

The compute worker handles:

  • Whisper word alignment (/align/whisper/jobs)
  • PDF layout parsing (/layout/pdf/jobs)

The app server enqueues jobs and polls status. Queue durability and retries are backed by Redis + BullMQ.

Published image

  • App server image: ghcr.io/richardr1126/openreader
  • Compute worker image: ghcr.io/richardr1126/openreader-compute-worker

Worker environment variables

Required:

  • COMPUTE_WORKER_TOKEN: bearer token expected by worker routes
  • REDIS_URL: BullMQ Redis connection string
  • S3_BUCKET
  • S3_REGION
  • S3_ACCESS_KEY_ID
  • S3_SECRET_ACCESS_KEY

Common optional:

  • S3_ENDPOINT (for non-AWS S3-compatible storage)
  • S3_FORCE_PATH_STYLE=true (for many S3-compatible providers)
  • S3_PREFIX=openreader
  • COMPUTE_WORKER_HOST=0.0.0.0
  • COMPUTE_WORKER_PORT=8081
  • COMPUTE_LOG_FORMAT=pretty (default) or json
  • COMPUTE_QUEUE_MAX_DEPTH=64
  • COMPUTE_PREWARM_MODELS=true

App server environment variables (worker mode)

Set on the Next.js app server:

COMPUTE_MODE=worker
COMPUTE_WORKER_URL=http://<worker-host>:8081
COMPUTE_WORKER_TOKEN=<same-token-as-worker>

COMPUTE_MODE=worker has no local fallback. If worker is unavailable, affected requests fail.

Production notes

  • Worker mode assumes shared object storage is reachable by both app server and worker.
  • Non-exposed embedded weed mini is not supported with external worker mode.
  • Protect COMPUTE_WORKER_TOKEN and avoid exposing worker routes publicly without auth.

Health endpoints

  • GET /health/live
  • GET /health/ready