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 4b26531172 chore(worker): migrate compute worker from Redis/BullMQ to NATS JetStream 
Replace Redis and BullMQ with NATS JetStream and KV for job queuing and state management
in the compute worker service. Update environment variables, Docker Compose, and documentation
to reflect the new message queue backend. Adjust dependencies and code to use NATS-based
work queue and key-value storage for durable job processing.

This change improves scalability and reliability of distributed compute workloads by leveraging
NATS JetStream's work queue and persistence features. Documentation and configuration examples
are updated to guide deployments using the new backend.
2026-05-20 07:38:03 -06:00

1.7 KiB
Raw Blame History

title: Compute Worker (NATS JetStream)

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 NATS JetStream WorkQueue consumers and NATS KV.

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
  • NATS_URL: NATS server connection string (JetStream enabled)
  • 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_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