Deploy a BullMQ worker and Redis queue to a VPS

To deploy a BullMQ worker to a VPS with ox, add the repo as a project and deploy it, with no Dockerfile and no ox.toml. ox reads package.json, runs npm install, then starts npm run start under systemd behind Caddy with HTTPS, and sets up redis 8 for it. Run ox check in your repo to see the same plan before the first deploy.

Plan verified, real-server test pending. The plan below is what ox check prints for a minimal BullMQ worker repo in ox's tests. A deploy on a real server is not recorded yet.

What ox detects in a BullMQ worker repo

This is the plan ox check prints for a minimal a Node app with a BullMQ queue, with no ox.toml. Each row says where its value came from: a file in the repo, or ox's default.

ox check also prints these hints for it:

• worker.js starts a BullMQ Worker, which processes jobs only while it runs: add [workers] worker = "node worker.js"

The ox.toml for BullMQ worker

None is needed: the plan above comes from the repo alone. Write one to serve your own domain or to change what ox detected, and to run the worker, as the hint says: ox runs only the processes the plan names. This one passes ox check against the same repo: [app] keeps the detected start command and build. Once a repo has an ox.toml, ox adds no service itself, so list each one under [services].

domains = ["www.example.com"]

[app]

[workers]
worker = "node worker.js"

[services]
redis = {}

Check and deploy BullMQ worker

Add the repo as a project, then check and ship it from a terminal:

ox check                                # in the repo: the plan above, offline
ox new <owner/repo> --server <server>  # add the repo as a project
ox deploy <project> --wait              # stream the deploy, exit with its result
ox logs <project> --follow             # the app's own logs

Variables to set for BullMQ worker

None before the first deploy: ox check asks for no variable. Add your own on the dashboard's Variables tab or with ox vars set <project> KEY.

ox provides these to the app itself: PORT, HOST, OX_ENV, OX_PROJECT, OX_RELEASE, OX_DATA_DIR, PUBLIC_URL, PUBLIC_HOST and REDIS_URL.

If the BullMQ worker deploy fails

• web of shop on main keeps crashing: systemd restarted it 5 times in the last 10 minutes. The Logs tab shows why.: The release went live and then kept dying. Read the Logs tab for the error and deploy a fix, or roll back. More.
• TCP connect to 127.0.0.1:8001 did not answer within 120s: dial tcp 127.0.0.1:8001: connect: connection refused: The app started but never answered on the port ox gave it. Listen on 127.0.0.1 at $PORT; the lines above the message are the app's own output. More.
• the app exited while starting (failed): The start command ran and stopped. The log shows the app's last lines, most often a missing variable or a wrong path to the built file. More.

Your visitors never see a failed deploy: the previous release keeps serving until the new one passes its health check.

Next steps

• The [workers] keys: processes that run next to the app.
• The Node.js guide: start scripts, migrations, PostgreSQL and Redis.
• The [app] keys: start, health check, memory and the rest.
• Service dashboards: your database's status, size, backups and data.
• Add a custom domain with one A record; Caddy gets the HTTPS certificate.
• Read the logs live, search them, or download them.

BullMQ worker FAQ

Do I need a Dockerfile or an ox.toml to deploy a BullMQ worker to a VPS?

No. ox does not use Docker, and ox check on a BullMQ worker repo with no ox.toml prints Ready to deploy. Write an ox.toml only to change what ox detected.

What does ox install on the server for BullMQ worker?

Only what the plan names: node 24 (ox's default). Your app's own dependencies are installed by the build into the release folder, not system-wide.

Why add a [workers] entry?

A BullMQ Worker processes jobs only while it runs, and ox runs only what the plan names. [workers] worker = "node worker.js" makes it a systemd service next to the app.

Related guides

• Deno FreshDeploy a Deno Fresh app to your own VPS: ox installs Deno 2, runs deno install and deno task build, then deno serve under systemd with Caddy for HTTPS.
• FlaskDeploy a Flask app to your own VPS: ox installs with uv from requirements.txt, runs gunicorn app:app under systemd behind Caddy, and adds PostgreSQL.

Every stack ox deploys, and the ones it does not yet, is on the Stacks page.