Install, configure, and manage Laravel queue workers using Supervisor on a Linux server

🛠 Step 1: Install Supervisor

For Ubuntu/Debian

sudo apt update && sudo apt install supervisor -y

For CentOS/RHEL

sudo yum install supervisor -y

🚀 Step 2: Enable and Start Supervisor

Enable Supervisor to start on boot and start the service:

sudo systemctl enable --now supervisor

Check its status:

sudo systemctl status supervisor

If Supervisor is not running, start it manually:

sudo systemctl start supervisor

📁 Step 3: Create a Supervisor Configuration for Laravel Queue

1. Open a new Supervisor config file:

   sudo nano /etc/supervisor/conf.d/laravel-worker.conf
   

2. Add the following content (modify the paths according to your Laravel project directory):

   [program:laravel-worker]
   process_name=%(program_name)s_%(process_num)02d
   command=php /var/www/html/your-laravel-project/artisan queue:work --tries=3
   autostart=true
   autorestart=true
   numprocs=1
   user=www-data
   redirect_stderr=true
   stdout_logfile=/var/www/html/your-laravel-project/storage/logs/worker.log
   

   Explanation of the options:

   • command → Runs php artisan queue:work
   • autostart=true → Automatically starts when Supervisor starts
   • autorestart=true → Restarts automatically if it crashes
   • numprocs=1 → Runs 1 worker process
   • user=www-data → Runs as the web server user (modify if needed)
   • stdout_logfile → Logs worker output (useful for debugging)

3. Save the file (CTRL + X, then Y, then Enter).

🔄 Step 4: Reload and Start Supervisor

1. Tell Supervisor to read the new config:

   sudo supervisorctl reread
   

2. Update Supervisor with new programs:

   sudo supervisorctl update
   

3. Start the Laravel queue worker:

   sudo supervisorctl start laravel-worker
   

4. Check the status of the worker:

   sudo supervisorctl status
   

🛠 Step 5: Ensure Supervisor Runs on System Reboot

Run this to make sure Supervisor restarts when the server reboots:

sudo systemctl enable supervisor

🔍 Step 6: Monitor Supervisor and Laravel Worker

Check if the worker is running:

sudo supervisorctl status

Restart the worker if needed:

sudo supervisorctl restart laravel-worker

Stop the worker:

sudo supervisorctl stop laravel-worker

Check Supervisor logs for errors:

sudo tail -f /var/log/supervisor/supervisord.log

Check Laravel queue logs:

tail -f /var/www/html/your-laravel-project/storage/logs/worker.log

🚀 Step 7: Test the Queue

1. Make sure your .env file is set to use a queue driver other than sync (e.g., database, redis, etc.):

   QUEUE_CONNECTION=database
   

2. Run migrations if using a database queue:

   php artisan queue:table
   php artisan migrate
   

3. Dispatch a test job:

   php artisan queue:work
   

4. If your job gets processed, Supervisor is working correctly!

✅ Summary of Commands

🎯 Final Thoughts

• If Supervisor fails to start, check its logs (/var/log/supervisor/supervisord.log).
• If jobs are not processing, check Laravel’s logs (storage/logs/laravel.log).
• If the queue stops working after reboot, ensure Supervisor is enabled (sudo systemctl enable supervisor).