Queue workers

Queue workers run php artisan queue:work for a Laravel container app, or the command you give them for any other stack, such as bundle exec sidekiq, celery -A app worker or a Procfile worker: line. They are separate instances of your app's own image, so long jobs never slow down web requests and keep running while the web instances sleep. Workers pull jobs from your app's dply Valkey store or its dply Postgres or MySQL database, the same way queue:work does on a server.

If you would rather not run workers at all, a Queues resource pushes each batch of jobs into your app over HTTP and scales to zero with it. Use workers when jobs are long, need steady throughput, or rely on the Redis or database queue drivers.

Requirements#

• The app uses Container delivery.
• On a stack other than Laravel, a command for each worker. dply suggests one from your Procfile, Sidekiq, Solid Queue, GoodJob or Celery when it finds them.
• On Laravel, a queue store both the app and the workers can reach: dply Valkey, or a dply Postgres or MySQL database. SQLite lives inside one container and cannot be shared.

If the app has no shared queue store, adding workers offers to start one for you (below). Workers you added earlier show Needs setup with an Add dply Valkey for the queue button that starts it and deploys.

Add queue workers#

1. Open your app's Overview and select Add resource.
2. Choose Queue workers. The Queue workers sheet opens with three choices:
   • Queues: prefilled with the queue names dply found in your code at the last build, most urgent first. It reads config/horizon.php, the queue values in config/queue.php, and onQueue('…') or $queue = '…' in app/ and routes/. Edit the list as you like. If Horizon defines several supervisors and your plan has worker groups, each extra supervisor gets its own workers.
   • When workers run: Start when jobs arrive (nothing runs while the queue is empty, and a waiting job starts a worker in a few seconds) or Always on (one worker runs all the time). Each shows its monthly cost.
   • Processes: jobs each worker runs at once, prefilled for the app's size: one per 96 MB after a 192 MB reserve (1 to 8; 8 on 1 GB).
3. If the app uses SQLite, the sheet adds dply Valkey for the queue: the smallest size, which sleeps when idle. Choose Use a Postgres or MySQL database instead to use a database.
4. Choose Add and deploy, or Add, deploy later to deploy yourself.

Timeouts, tries, memory and the other options below keep their defaults. Change them in the workers' settings afterwards.

When workers are running, dply sets QUEUE_CONNECTION to the connection they pull from, unless you set it yourself under Environment, so the jobs your app dispatches reach the workers.

Settings#

Under Worker options:

The sheet shows the exact command your workers run.

Workers use the app's instance size (see Container apps) unless you choose a Worker size. A worker rarely needs the web container's memory, and memory is most of what an always-on instance costs, so a smaller size usually cuts the workers' bill by two thirds or more. The change applies on the next deploy, which moves the running workers to the new size; the old ones stop once the new ones start. Each instance is named worker-0, worker-1, … and runs your image with DPLY_ROLE=worker. On stop, a worker lets its current job finish. A worker that exits right after starting is restarted with a back-off.

Autoscaling#

Turn on Autoscale to add workers when jobs back up:

• Always on: instances that always run. 0 lets the workers scale to zero: one starts when jobs arrive and stops five minutes after the queue empties.
• Up to: the most instances that can run.
• Add one at: jobs waiting per process before another instance starts (1–1000, default 10).
• Or when a job waits: also add an instance when the oldest ready job has waited this many seconds (0–3600, default 60; 0 turns it off).

dply reads the backlog about every 10 seconds, straight from the queue store, so checking never wakes your web instances. It scales up at once and scales down after five quiet minutes. While delayed jobs exist, at least one worker stays. A dply store that is asleep holds no new jobs, so it is not woken to be checked.

The cost line under the settings shows the monthly range, from the always-on count to the maximum. Extra instances are billed only while they run.

Worker groups#

A group is another set of workers for other queues, sized and scaled on its own, so a flood on one queue cannot hold up another. Under Groups, select Add a group, then set its Queues, Instances, Processes, Autoscale and up to. Its instances are named worker-{group}-N. A group shares the main group's connection and Worker options.

Plan limits#

Limits apply per app, across the main group and every extra group.

If your settings ask for more than your plan allows, the sheet says so and only what fits is deployed: extra groups are dropped and instances are trimmed, main group first.

Workers are billed as container compute on the app's size.

Check, pause and test#

In the Queue workers sheet:

• Check workers shows the jobs waiting on each queue and the failed-job count, and lists every worker with its state (Running, Stopping, Stopped, Exited, Idle (scaled down), Paused), where it is running and its round trip to the database and Redis.
• Start stopped workers starts any worker that should be running and is not.
• Send test job queues php artisan inspire on the first queue.
• Pause stops every worker, letting running jobs finish. Jobs wait on the queue until you Resume. Deploys and autoscaling leave paused workers stopped. Pausing also pauses a scheduler running in worker-0.
• Remove takes the workers away on the next deploy.

The app's Jobs section (under Extend) summarizes the workers next to the app's queues: processes and instances, the queues and connection they read, extra groups, whether the scheduler runs in a worker, and live N of M running with the failed-job count. Its controls link back to this sheet on Overview.

Failed jobs#

Select Failed jobs in the sheet to read your app's own failed-job store: each job's class, queue, connection, when it failed, attempts, error and stack trace. Retry puts a job back on its queue; Delete removes it. Retry all and Delete all act on every failed job.

Logs#

Select Logs in the sheet for the last hour of worker output, newest first: each job as it runs and finishes (RUNNING, DONE, FAIL), and each worker starting, restarting and stopping. Lines arrive about a minute after they happen. Build & deploy logs → What your app is printing also filters by queue worker.

Alerts#

Two notification events cover workers. Route them under Notification channels:

• Queue jobs failing: jobs logged FAIL in the last few minutes.
• Queue workers keep exiting: workers exited right after starting three or more times.

Each is sent at most once every 30 minutes per app.

The scheduler in a worker#

With the Laravel scheduler on and at least one always-on worker, the scheduler runs as php artisan schedule:work in worker-0, so the web instances can sleep. See Scheduled tasks.

Related#

• Container apps
• Queues
• Valkey (Redis)
• Scheduled tasks