HiveGrid-Wireframes/hivegrid-cloud/apps/worker/README.md

@toolctrl/worker

Opt-in BullMQ worker runtime for queue-backed jobs.

The worker is disabled by default and is not imported by the web runtime. Running it directly without WORKER_ENABLED=true exits immediately.

Local execution

Check worker readiness and Redis configuration without starting processors:

pnpm --filter @toolctrl/worker health

Run the disabled-by-default worker locally:

pnpm --filter @toolctrl/worker dev

Start the enabled worker against a local Redis instance and database:

WORKER_ENABLED=true WORKER_QUEUE_GROUP=general BULLMQ_REDIS_URL=redis://localhost:6379/0 DATABASE_URL=postgresql://localhost/app pnpm --filter @toolctrl/worker dev

The worker stays disabled unless WORKER_ENABLED=true. When enabled, DATABASE_URL is required, and Redis is resolved from BULLMQ_REDIS_URL first; REDIS_URL is fallback only when BULLMQ_REDIS_URL is absent for deployments that already provide a generic Redis binding.

Docker Compose

Build the worker image and start a disabled smoke container with local Redis:

docker compose up redis worker-general

The compose topology builds the Dockerfile worker target for five grouped services: worker-general, worker-mail, worker-import, worker-webhook, and worker-plugin. Each service leaves processors disabled by default and wires Redis with BULLMQ_REDIS_URL=redis://redis:6379/0 using the compose service name. Enable real processors only with a valid database URL and the group you want to exercise, for example with WORKER_ENABLED=true DATABASE_URL=postgresql://... docker compose up worker-mail or an override file.

Manual E2E note: real queued job processing requires a running Redis/container smoke test outside Auto-Mode; Auto-Mode verification for this task is limited to static configuration and documentation checks.

Current processors

The worker has concrete handler paths for mail, webhooks, notifications, maintenance, storage scans, exports, imports, and guarded AI/browser job descriptors. Some queues remain disabled unless feature flags and provider services are configured.

• toolctrl.email
• toolctrl.notifications
• toolctrl.maintenance
• toolctrl.ai-chatbot
• toolctrl.browser-automation
• toolctrl.file-scan
• toolctrl.exports
• toolctrl.imports
• toolctrl.plugin-invoke