How to Configure Supervisor on Linux: A Step-by-Step Guide

Laravel relies on background tasks and queue workers to handle things like sending emails, processing file uploads, and other time-consuming tasks. By pushing these operations to a queue, your application can remain fast and responsive for users.

However, for queues to function properly, we need a queue worker to process jobs as they come in.

Queue Worker can be started using the Artisan command below:

php artisan queue:work

The issue with this approach is that the worker keeps running until manually stopped or the terminal session is closed. This is fine for development, but in production, it's not ideal—if the worker stops due to a timeout or queue:restart, it won’t restart automatically. That’s where a process monitor like Supervisor comes in.

Why Use Supervisor?

Supervisor is a process monitor tool that ensures queue workers keep running. If a worker crashes or stops for any reason, Supervisor will restart it automatically. It also allows you to run multiple queue workers concurrently for better performance.

Installing Supervisor

To install Supervisor on a Linux environment, run:

sudo apt-get install supervisor

Configuring Supervisor for Laravel Queues

Supervisor configuration files are typically located in /etc/supervisor/conf.d. Create a new configuration file to manage your queue workers:

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

Add the following configuration:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path-to-project/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=azureuser
numprocs=8
redirect_stderr=true
stdout_logfile=/path/worker.log
stopwaitsecs=3600

This configuration:

• Runs queue:work as a background process.

• Automatically restarts the worker if it stops.

• Runs 8 worker processes simultaneously for better job handling.

• Logs output to /path/worker.log.

Applying the Configuration

Once the configuration file is created, Supervisor needs to recognize the changes:

sudo supervisorctl reread
> laravel-worker: available

sudo supervisorctl update
> laravel-worker: added process group

Now, start the queue worker:

sudo supervisorctl start laravel-worker:*

To check the status of running workers:

sudo supervisorctl status laravel-worker:*

Restarting the Queue After Code Changes

Since queue:work runs as a daemon, any changes in the application won't take effect immediately. You need to restart the queue:

php artisan queue:restart

This sends a restart signal to all workers.

Final Thoughts

Laravel utilizes background tasks and queue workers to improve application performance by handling time-consuming tasks asynchronously.

Using a Supervisor ensures that your Laravel queue workers run smoothly in the background without manual intervention. It helps prevent unexpected downtimes and optimizes job processing. If you're running a Laravel application in production, setting up Supervisor is a must.

Supervisor can restart stopped processes and manage them efficiently. This guide explains how to install and configure Supervisor on a Linux environment to manage Laravel queue workers effectively.