Laravel Queue Workers with Supervisor and Redis

Introduction

Background job processing is essential for any non-trivial Laravel application. Sending emails, processing uploads, generating reports, and syncing with third-party APIs all belong in queues rather than blocking HTTP requests. Redis provides the queue backend, and Supervisor ensures worker processes stay running and restart automatically after failures or deployments.

This guide walks through the full setup on an Ubuntu production server.

Installing Redis and Supervisor

sudo apt update
sudo apt install -y redis-server supervisor

# Ensure Redis starts on boot
sudo systemctl enable redis-server
sudo systemctl start redis-server

# Verify
redis-cli ping

Laravel Queue Configuration

Update your .env file:

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null

Laravel supports multiple queues with different priorities. Define them in config/queue.php:

'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => env('REDIS_QUEUE', 'default'),
    'retry_after' => 90,
    'block_for' => 5,
],

Supervisor Configuration

Create a Supervisor configuration file for your queue workers:

sudo tee /etc/supervisor/conf.d/laravel-worker.conf > /dev/null <<EOF
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/app/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600 --queue=high,default,low
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=4
redirect_stderr=true
stdout_logfile=/var/log/supervisor/laravel-worker.log
stopwaitsecs=3600
EOF

Key settings explained:

• numprocs=4: Runs four worker processes in parallel
• max-time=3600: Workers restart hourly to prevent memory leaks
• tries=3: Failed jobs are retried up to three times
• queue=high,default,low: Processes queues in priority order
• stopwaitsecs=3600: Allows workers to finish long-running jobs before stopping

Starting Workers

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

# Check status
sudo supervisorctl status

Deployment Integration

After deploying new code, restart workers gracefully so they pick up the latest changes:

# In your deployment script
php artisan queue:restart

This sends a signal to workers to finish their current job and then restart. Supervisor automatically starts fresh processes.

Failed Job Handling

Configure a failed jobs table and monitor it:

php artisan queue:failed-table
php artisan migrate

# View failed jobs
php artisan queue:failed

# Retry a specific job
php artisan queue:retry <job-id>

# Retry all failed jobs
php artisan queue:retry all

For a containerized approach, see our guide on Docker Compose for Laravel development. Our server management service includes Supervisor setup and queue monitoring as part of our managed infrastructure offering.

Redis and Supervisor form a battle-tested combination for Laravel queue processing. Four worker processes with priority queues handle most application workloads, and Supervisor ensures everything stays running without manual intervention.