Deployment · By Rivtor · Updated
Deploy a BullMQ background worker with Redis
A BullMQ producer puts jobs into Redis and a separately running worker consumes them. Both processes must agree on queue names and connection settings; a live API does not prove jobs are completing.
See the Rivtor deployment workflow →
Declare worker startup
Give the worker a dedicated start command and include runtime dependencies in its service manifest. Queue consumers do not need a public HTTP endpoint simply to receive jobs. Review the platform’s supported workload configuration rather than assuming an API container starts a second process.
Keep Redis credentials private
Read the Redis connection from environment configuration. Do not place it in a browser bundle. Verify driver, endpoint and TLS settings for the actual service instead of copying a configuration intended for another provider.
Make jobs safe to repeat
Choose a stable business identifier for operations that cannot happen twice. Use bounded retries and backoff, and keep permanent business state outside the queue where auditability is required. Avoid placing provider tokens or full user documents in job payloads.
Observe shutdown and completion
Test a harmless job and inspect both queue state and the business result. Handle process termination so active work is released or completed according to the worker library’s behavior. Queue age and stalled jobs reveal problems that may not appear as HTTP errors.
Command reference
node dist/worker.js
These commands illustrate the documented workflow. Replace example addresses and identifiers with your own. Deployment and migration commands affect the selected project; confirm the target before running them.
Keep the worker independently startable
A Node package can expose separate commands for an API and a worker:
{
"scripts": {
"start": "node dist/api.js",
"worker": "node dist/worker.js"
}
}
Ensure the build produces both files and that the worker's production dependencies include bullmq and its Redis client. Start a dedicated process with npm run worker. A worker does not need a public HTTP endpoint solely because the API has one.
Check job delivery rather than process uptime
Enqueue a synthetic job with a known identifier. Inspect waiting, active, completed and failed states, then confirm the expected output. Producer and worker need the same queue name, Redis destination and compatible connection settings. A producer can successfully enqueue work while no worker is consuming that queue.
Set retry policy according to job behavior. External side effects require idempotency protection; retrying an email or charge is not equivalent to retrying a pure calculation. Inspect errors without logging job payloads that contain customer data.
Decide what happens during a release
Handle process termination by stopping new work and closing the worker cleanly where supported. Rehearse long jobs and failures on synthetic inputs, including a worker restart. Reserve memory for the API, worker and Redis together rather than pricing the API alone.
Read Rivtor data services and always-on versus sleeping hosting. Source: BullMQ connections.
Next steps
Read the Rivtor reference for supported configuration and limitations, and use the deployment quickstart when trying Rivtor for the first time. Validate workflows with synthetic data before connecting valuable production records.