SupportConsole
llms.txtSign in

Run queue workers and the Laravel scheduler

llms.txt

Two things in a Laravel application only work while something keeps running on the server: the queue worker, which processes jobs such as sending email, and the scheduler, which runs your scheduled tasks every minute. SrvYard runs the first as a Supervisor process and the second as a cron job, and both are managed from the site, with no SSH session.

This article shows how to add a queue worker with the form (which builds the queue:work command for you), what each option does, how workers pick up new code after a deployment, and how to switch the scheduler on and check that it is running. For other long-running commands see Background processes for a site; for Horizon see The Laravel panel.

Before you begin

  • A deployed site. Processes run from the deployed application, so SrvYard refuses to create one before the first deployment finishes: "Deploy the site first: processes run from the deployed application."
  • A queue connection that is not sync. Set QUEUE_CONNECTION to database, redis or another real driver in the site's environment. Workers on sync have nothing to do.
  • Permission to manage queues. Owners and admins have it; viewers see the processes but not the buttons.
  • Redis or the database ready, depending on the driver. See Redis, Memcached and cache services.

1. Open the Processes tab

Open the site and choose Processes.

The Processes tab
Background processes above, scheduled jobs below.
  1. Add background process. Opens the form in step 2.
  2. The process table. One row per Supervisor program: its name, its command underneath, how many copies run and its status.
  3. Status. Running is the healthy state. The others are Creating, Starting, Stopping, Restarting, Stopped, Failed, Deleting and Unknown. While a process is changing state its row menu is disabled.
  4. Scheduled jobs. The cron jobs of this site, including the Laravel scheduler once you switch it on (step 5).

2. Add a queue worker

Press Add background process. A sheet opens with the Queue worker tab selected.

The queue worker form
The queue worker form builds the queue:work command for you.
  1. connection. The queue connection to read from, for example redis. Leave it empty to use the application's default connection. Letters, digits, ., _ and - only.
  2. --queue. The queues to process, comma separated and in priority order, for example high,default. Empty means the connection's default queue. Up to 20 names.
  3. --timeout (seconds). How long one job may run before the worker kills it. Default 60.
  4. Preview. The exact command Supervisor will run, rebuilt as you type. Use Copy to take it elsewhere.
  5. Create background process. Creates the Supervisor configuration on the server and starts the worker. The toast says "Creating the background process..." and the row appears as Creating, then Running.

The other fields:

Field Meaning Default and range
Name (optional) Names the Supervisor program. Lowercase letters, digits, - and _, unique on the server. queue- plus the site name
php The PHP version the worker uses. Only versions installed on the server are listed. The site's version
processes How many identical workers run side by side. 1, from 1 to 50
--backoff (seconds) Delay before a failed job is retried. Not passed
--sleep (seconds) How long to wait when the queue is empty. 3
--rest (seconds) Pause between jobs. Not passed
--tries How often a job is tried before it fails. Not passed (the job's own setting applies)
--memory (MB) A worker restarts itself above this limit. 128, from 32
--env The environment name passed to queue:work. Not passed
--force Run even while the application is in maintenance mode. Off

SrvYard always runs the worker as the site's Linux user, from the application folder, starts it automatically with the server and restarts it when it exits. A graceful stop gets the time shown in the Graceful shutdown setting, which you can read about under Supervisor configuration on the Custom tab.

Tip

Set --timeout lower than your connection's retry_after (for Redis, in config/queue.php), or a slow job can be started a second time while the first is still running.

3. Control a worker

Open the row menu (the three dots).

The row menu of a process
Control a worker from its row menu.
  1. Restart. Stops and starts the worker. Start and Stop do what they say.
  2. View logs. Opens the worker's log file with Auto refresh and Refresh. It shows the last lines of what the worker printed.
  3. Edit. Opens the process in the form to change its command, number of copies or shutdown time. An edited queue worker is shown as a plain command, so the option fields are not offered again.

Deleting a process asks for confirmation and removes its Supervisor configuration and log from the server.

4. Make workers pick up new code

A queue worker loads the application once and keeps it in memory, so after a deployment it still runs the old code. The default deploy script ends with $RESTART_QUEUES(), which runs php artisan queue:restart and, when Laravel Horizon is installed, horizon:terminate. Workers finish their current job, exit and Supervisor starts fresh ones on the new release.

If you wrote your own script, keep that line (or srvyard_restart_queues) at the end. Saving the .env with Restart queue workers ticked does the same for a changed environment, as described in Edit environment variables.

5. Switch on the scheduler

The Laravel scheduler needs one cron entry that runs every minute. You do not write it.

The Scheduler switch on the Laravel card
The scheduler switch is on the Laravel card of the overview.
  1. Scheduler. On the Overview tab, in the Laravel card, turn the switch on. SrvYard adds a job named Laravel scheduler that runs php artisan schedule:run every minute as the site user, in the application folder and with the site's PHP. Turning the switch off removes the job.

The job then shows on the Processes tab under Scheduled jobs, with its frequency and status (Installed once the server has it). The same list is in the server's own scheduler, which you reach through the link in the card description. See Scheduled commands on a server for every job on the machine.

Note

The scheduler only starts tasks that your application defines in routes/console.php (or the console kernel). Switching it on does not create tasks. To be told if the minute tick ever stops, add a heartbeat on the site's Observe tab and ping it from a scheduled task.

Troubleshooting

  • "Deploy the site first: processes run from the deployed application." Deploy once, then add the worker.
  • The worker shows Failed. Open View logs. Typical causes are a wrong connection name, a missing PHP extension such as redis, or an application error at boot. Fix it, then Restart.
  • Jobs are queued but nothing runs. Check the worker is Running, that its connection and --queue match what the application dispatches to, and that QUEUE_CONNECTION is not sync. See Jobs are not being processed.
  • The worker runs old code. The deploy script no longer ends with $RESTART_QUEUES(), or the deployment failed before that line.
  • "The name has already been taken." Process names are unique per server. Pick another or leave Name empty.
  • The scheduler switch does nothing. You need the permission to manage integrations, and the card must have been able to read the site. See The Laravel panel.
  • Scheduled tasks run twice. Another cron entry, perhaps added by hand on the server's scheduler, runs schedule:run as well. Delete one of them.
Last updated 2026-10-247 min readNeed help? Contact support
PreviousEdit environment variablesNextRun background processes for a site