Background Queues (BullMQ)

LaunchKit Pro includes an optional Redis-backed queue system (BullMQ) for background jobs. The safe default is QUEUES_ENABLED=false — no Redis is required for a normal local install.

Quick answer

Setting	Result
QUEUES_ENABLED=false (default)	App starts without BullMQ; synchronous flows work
QUEUES_ENABLED=true	Redis required; five queues register at startup

Recommended for first install: keep queues disabled until you need background jobs and have Redis provisioned.

---

Supported queues

These names are registered from a single constants file — BullMQ registration, processors, services, metrics, and admin APIs all use the same values:

Queue	Purpose
email	Async email jobs (send_email, password reset, invite, license, billing receipt)
webhook	Outbound webhook delivery when WEBHOOK_QUEUE_ENABLED=true
notification	In-app / notification delivery foundation
maintenance	Cleanup and scheduler jobs (dry-run by default)
ai	Long-running AI jobs foundation (sync AI API remains default)

---

Environment variables

# Queues / Redis
QUEUES_ENABLED=false
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
# REDIS_URL=redis://127.0.0.1:6379
QUEUE_PREFIX=launchkit
QUEUE_DASHBOARD_ENABLED=false

# Queue workers
QUEUE_WORKER_EMAIL_ENABLED=true
QUEUE_WORKER_AI_ENABLED=true
QUEUE_WORKER_WEBHOOK_ENABLED=true
QUEUE_WORKER_NOTIFICATION_ENABLED=true
QUEUE_WORKER_MAINTENANCE_ENABLED=true

# Queue behavior
QUEUE_DEFAULT_ATTEMPTS=3
QUEUE_DEFAULT_BACKOFF_MS=30000
QUEUE_JOB_REMOVE_ON_COMPLETE=100
QUEUE_JOB_REMOVE_ON_FAIL=500

# Maintenance scheduler
MAINTENANCE_SCHEDULER_ENABLED=false
MAINTENANCE_CLEANUP_CRON=0 3 * * *
MAINTENANCE_DEMO_RESET_CRON=0 4 * * *
MAINTENANCE_STORAGE_CLEANUP_CRON=0 5 * * *

# Webhook queue handoff (optional)
WEBHOOK_QUEUE_ENABLED=false

Set REDIS_URL or REDIS_HOST (+ optional port/password/db). When QUEUES_ENABLED=true, at least one must resolve to a connection URL.

Worker enable flags control which in-process processors start. Set a flag to false to disable that worker while keeping the queue registered.

---

Simple buyer setup

QUEUES_ENABLED=false

• No Redis install required for queues
• API starts normally — no “BullMQ queues not registered” error
• GET /admin/queues/status returns { enabled: false, message: "Queues are disabled." }
• Billing, AI, webhooks (direct mode), email mock, storage, and license flows work synchronously

---

Enabling queues (production rollout)

1. Provision Redis (local, VPS, or managed).
2. Configure Redis:

REDIS_URL=redis://127.0.0.1:6379
# or REDIS_HOST=127.0.0.1
QUEUES_ENABLED=true

3. Restart the API. Logs should show:

Registering BullMQ queues: email, webhook, notification, maintenance, ai
Queue system ready - BullMQ queues registered

4. Verify admin status:

• Admin → Queues (/admin/queues) — per-queue counts and pause/resume/clean
• Admin → Settings — queue monitor and test job enqueue
• GET /admin/queues/status — enabled, redisConfigured, queuesReady, per-queue counts

5. Optionally enable webhook queue handoff:

WEBHOOK_QUEUE_ENABLED=true

When both QUEUES_ENABLED=true and WEBHOOK_QUEUE_ENABLED=true, outbound webhook deliveries enqueue deliver_webhook jobs. Retries respect WEBHOOK_MAX_RETRIES and WEBHOOK_RETRY_BACKOFF_SECONDS. Direct delivery still works when the queue is disabled or not ready.

---

Email queue foundation

Email jobs are enqueued on the email queue when callers use the queue path:

Job name	Purpose
send_email	Generic email
send_password_reset	Password reset
send_invite	Workspace invite
send_license_email	License delivery
send_billing_receipt	Billing receipt

With EMAIL_PROVIDER=MOCK, jobs log safe mock delivery and complete without exposing secrets. If a real provider is selected but queue sending is not implemented yet, jobs return a friendly skipped status — the API does not crash.

---

AI queue foundation

The ai queue supports ai_generate_text and ai_usage_rollup jobs. Synchronous AI generation remains the default for POST /ai/generate. The queue layer is for future long-running or batched work.

---

Maintenance scheduler

MAINTENANCE_SCHEDULER_ENABLED=false by default. When enabled and queues are ready, dry-run maintenance jobs are enqueued on a daily interval:

• cleanup_expired_sessions
• cleanup_orphan_files (dry-run)
• demo_reset (placeholder — logs only, no deletion)

Cleanup jobs use dryRun=true unless a future feature flag enables deletion. Uploads and database records are not deleted by default.

---

Admin queue APIs

Method	Route	Description
GET	/admin/queues/status	System status and per-queue counts
GET	/admin/queues/jobs	Recent jobs (optional queueName filter)
POST	/admin/queues/:queueName/pause	Pause a queue
POST	/admin/queues/:queueName/resume	Resume a queue
POST	/admin/queues/:queueName/clean	Clean completed/old failed jobs

When queues are disabled, status returns HTTP 200 with enabled: false — not a 500 error.

---

Testing Redis locally

# macOS (Homebrew)
brew install redis && brew services start redis

# Docker
docker run -d --name redis -p 6379:6379 redis:7-alpine

# Verify
redis-cli ping   # PONG

Then set QUEUES_ENABLED=true and REDIS_HOST=127.0.0.1 (or REDIS_URL) and restart the API.

---

Troubleshooting: “BullMQ queues not registered”

This error appeared in older builds when QUEUES_ENABLED=true but BullMQ was never registered at module startup (for example, Redis env vars missing at init time while the health layer still expected queues).

The current implementation avoids this by:

1. Shared bootstrap resolution — QueuesBullModule, workers, and QueuesService use the same env check before registering or validating queues.
2. Bootstrap state token — if BullMQ was skipped, QueuesService reports a clear config error instead of listing all five queues as missing.
3. Direct queue injection — QueuesService injects each queue by name constant, matching BullModule.registerQueue tokens exactly.

If you still see startup errors:

• Confirm REDIS_URL or REDIS_HOST is set in .env
• Confirm Redis is running (redis-cli ping)
• Restart the API after env changes
• Revert to QUEUES_ENABLED=false if you do not need background jobs yet

---

Related docs

• Environment Variables
• Deployment
• Deployment Gotchas
• Email & Notifications
• Developer Tools — outbound webhooks and WEBHOOK_QUEUE_ENABLED
• Admin Panel