Before diving into explaining why, let us explain what a supervisor is.
Supervisor is a process monitoring tool that manages background workers.
It is similar to PHP-FPM:
✅ PHP-FPM handles HTTP requests
✅ Supervisor handles console (queue) workers
How do Laravel queues work?
When a queue worker starts, Laravel boots a new application instance and keeps it in memory.
That same instance is reused to process multiple jobs. This is great for performance, but it creates one important issue:
👉 If you deploy new code, the running workers will NOT see the changes.
Why do we restart the queue after deployment?
After deploying new code, we need to restart the workers so they can load the latest version of the application.
In Laravel, we do this using: php artisan queue: restart
This command tells workers to finish their current job and then stop gracefully.
What actually happens behind the scenes?
When you run queue:restart:
Laravel sends a SIGTERM signal to all queue workers, and workers finish their current job (they don’t stop immediately)
✅ They exit gracefully
✅ Supervisor automatically starts new workers
✅ New workers load the latest deployed code
⚒️ Important configuration: stopwaitsec
The supervisor has a setting called stopwaitsec.
This defines how long it waits before forcefully stopping a worker.
If a worker does not stop within this time, 👉 Supervisor sends SIGKILL (force kill). That means the job will be terminated immediately, even if it’s not finished.
📍 Best practice
Make sure: 👉 stopwaitsec is longer than your longest running job.
Example:
If your longest job takes 5 minutes
Set stopwaitsec = 600 (10 minutes)
This ensures jobs finish safely during deployments.
