Laravel applications often need to handle background tasks like sending emails, processing images, or generating reports. While these tasks are essential, they can slow down your application if not managed properly. This is where Supervisor Laravel configuration becomes crucial for maintaining optimal performance.
Supervisor Laravel integration ensures your queue workers run continuously, automatically restart when they crash, and handle background jobs efficiently. Whether you’re building a small blog or a large-scale enterprise application, understanding how to configure Supervisor with Laravel queues will significantly improve your application’s reliability and user experience.
This comprehensive guide walks you through every step of setting up Supervisor Laravel queue workers, from basic installation to advanced production configurations. By the end, you’ll have a robust background job processing system that scales with your application’s needs.
What Is Supervisor and Why Laravel Needs It
Supervisor Laravel combines two powerful technologies to create a reliable background job processing system. Supervisor is a process control system that monitors and manages long-running processes on Unix-like operating systems, while Laravel queues provide an elegant API for deferring time-consuming tasks.
When you deploy Laravel applications to production, you need a way to ensure queue workers keep running even when they encounter errors or your server restarts. Laravel’s built-in php artisan queue:work command works perfectly for development, but it lacks the robustness needed for production environments.
Supervisor Laravel configuration solves this problem by:
- Automatically restarting queue workers when they stop unexpectedly
- Managing multiple worker processes for better performance
- Providing detailed logging and monitoring capabilities
- Ensuring workers start automatically after server reboots
Without proper process management, your background jobs might stop processing, leading to frustrated users and potential data loss. This makes Supervisor Laravel setup essential for any serious Laravel deployment.
For a comprehensive understanding of Supervisor fundamentals, check out our detailed guide on The Ultimate Guide to Supervisor Linux for Beginners, which covers installation and basic configuration across different Linux distributions.
Understanding Laravel Queues
Overview of Laravel Queue System
Laravel’s queue system provides a unified API for deferring time-consuming tasks to background processes. Instead of forcing users to wait for tasks like email sending or file processing, Laravel queues these operations for later execution by dedicated worker processes.
The queue system consists of several key components:
- Jobs: Individual tasks that need to be processed
- Queues: Named channels where jobs are stored
- Workers: Processes that retrieve and execute jobs
- Drivers: Storage mechanisms for queue data
Supervisor Laravel integration ensures these workers run reliably by monitoring their health and automatically restarting them when necessary.
Popular Drivers for Laravel Queues
Laravel supports multiple queue drivers, each with specific advantages:
Database Driver: Stores jobs in your application’s database using a simple table structure. Perfect for small to medium applications that want to avoid additional infrastructure complexity.
Redis Driver: Uses Redis as the queue backend, offering excellent performance and additional features like job prioritization and delayed execution. Ideal for high-traffic applications requiring fast job processing.
Amazon SQS: Leverages Amazon’s Simple Queue Service for cloud-native applications. Provides automatic scaling and high availability without managing queue infrastructure.
Beanstalkd: A lightweight, fast work queue designed specifically for background job processing. Offers good performance with minimal resource overhead.
When configuring Supervisor Laravel workers, your choice of queue driver affects the command-line options and resource requirements for your worker processes.
Common Use Cases for Queues in Laravel Apps
Laravel queues excel at handling various background tasks:
Email Processing: Send newsletters, notifications, and transactional emails without blocking the main application thread.
Image and File Processing: Resize images, generate thumbnails, or process uploaded documents asynchronously.
API Integrations: Sync data with external services, send webhooks, or update third-party systems.
Report Generation: Create complex reports, export data to various formats, or generate analytics summaries.
Database Maintenance: Clean up old records, update search indexes, or perform bulk data operations.
Each use case benefits from Supervisor Laravel configuration ensuring these critical background processes remain operational.
Preparing Your Server for Supervisor
Minimum System Requirements
Before setting up Supervisor Laravel workers, ensure your server meets the basic requirements:
Operating System: Ubuntu 18.04+, CentOS 7+, or any modern Linux distribution PHP Version: PHP 8.0 or newer (matching your Laravel requirements) Memory: Minimum 1GB RAM (2GB+ recommended for production) Storage: At least 10GB free space for logs and temporary files
Additional Dependencies:
- Redis server (if using Redis queue driver)
- MySQL/PostgreSQL (if using database queue driver)
- Composer for managing PHP dependencies
Installing Supervisor on Ubuntu and Other Linux Distros
Installing Supervisor is straightforward on most Linux distributions:
Ubuntu/Debian Systems:
# Update package repositories
sudo apt update
# Install Supervisor
sudo apt install supervisor
# Start and enable Supervisor service
sudo systemctl start supervisor
sudo systemctl enable supervisor
CentOS/RHEL Systems:
# Install EPEL repository
sudo yum install epel-release
# Install Supervisor
sudo yum install supervisor
# Start and enable Supervisor service
sudo systemctl start supervisord
sudo systemctl enable supervisord
Arch Linux:
# Install Supervisor
sudo pacman -S supervisor
# Start and enable service
sudo systemctl start supervisord
sudo systemctl enable supervisord
Verifying the Installation
Confirm your Supervisor Laravel setup foundation is ready:
# Check Supervisor version
supervisord --version
# Verify service status
sudo systemctl status supervisor
# Test command-line interface
supervisorctl version
# Check configuration directory
ls -la /etc/supervisor/conf.d/
You should see Supervisor running without errors and the configuration directory available for your Supervisor Laravel worker configurations.
Installing and Configuring Laravel Queue Worker
Setting Up Queue Drivers in .env
Configure your Laravel application’s queue driver in the .env file:
Database Driver Configuration:
QUEUE_CONNECTION=database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password
Redis Driver Configuration:
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
Amazon SQS Configuration:
QUEUE_CONNECTION=sqs
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
SQS_QUEUE=your_queue_name
After updating your .env file, clear the configuration cache:
php artisan config:clear
Creating a Simple Job in Laravel
Generate a sample job to test your Supervisor Laravel configuration:
# Create a new job class
php artisan make:job ProcessEmail
Edit the generated job file (app/Jobs/ProcessEmail.php):
<?php
namespace App\Jobs;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Log;
class ProcessEmail implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
protected $emailData;
public function __construct($emailData)
{
$this->emailData = $emailData;
}
public function handle()
{
// Simulate email processing
Log::info('Processing email for: ' . $this->emailData['recipient']);
// Add your email processing logic here
sleep(5); // Simulate processing time
Log::info('Email processed successfully');
}
}
Running Queue Worker Manually (Without Supervisor)
Test your queue setup before configuring Supervisor Laravel workers:
# Start a queue worker manually
php artisan queue:work
# For specific queue names
php artisan queue:work --queue=emails,default
# With timeout and memory limits
php artisan queue:work --timeout=60 --memory=512
Dispatch a test job from Laravel Tinker:
php artisan tinker
// Inside tinker
App\Jobs\ProcessEmail::dispatch(['recipient' => '[email protected]']);
You should see the job being processed by your manual worker. This confirms your Laravel queue setup works correctly before adding Supervisor Laravel management.
Creating a Supervisor Configuration File for Laravel
Understanding the Supervisor Config Syntax
Supervisor Laravel configurations use INI-style syntax that’s both human-readable and flexible. Each program section defines how Supervisor should manage a specific process.
The basic structure looks like this:
[program:program-name]
key=value
key2=value2
For Supervisor Laravel workers, you’ll primarily work with process management directives that control how your queue workers start, run, and restart.
Creating a Program Block for Laravel Queue Worker
Create a new configuration file for your Supervisor Laravel worker:
sudo nano /etc/supervisor/conf.d/laravel-queue.conf
Add the following configuration:
[program:laravel-queue-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-laravel-app/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/your-laravel-app/storage/logs/queue-worker.log
stopwaitsecs=3600
Key Directives Explained
process_name: Defines how individual processes are named when running multiple workers. The %(process_num)02d creates numbered instances like laravel-queue-worker_01, laravel-queue-worker_02.
command: The actual command Supervisor Laravel executes. This should be the full path to your Laravel application and the appropriate artisan command with any necessary flags.
autostart: Set to true to automatically start workers when Supervisor starts, ensuring your Supervisor Laravel setup is ready after server reboots.
autorestart: Configures automatic restart behavior. Set to true for queue workers to ensure they restart immediately if they crash or exit unexpectedly.
user: Specifies which system user should run the process. Use www-data or your web server user to maintain proper file permissions.
numprocs: Number of worker processes to start. For Supervisor Laravel setups, start with 2-4 workers and scale based on your application’s needs.
redirect_stderr: Combines error output with standard output for simplified logging and debugging.
stdout_logfile: Path where Supervisor Laravel writes worker output and errors. Ensure this directory exists and is writable by the specified user.
stopwaitsecs: How long Supervisor waits for graceful shutdown before forcefully killing processes. Set this to match your longest job execution time.
Saving and Enabling Supervisor Configuration
Saving the Config in /etc/supervisor/conf.d/
Ensure your Supervisor Laravel configuration file is properly saved and has correct permissions:
# Verify file exists and has proper permissions
sudo ls -la /etc/supervisor/conf.d/laravel-queue.conf
# Set appropriate permissions if needed
sudo chmod 644 /etc/supervisor/conf.d/laravel-queue.conf
# Verify configuration syntax
sudo supervisorctl reread
The reread command checks for syntax errors in your Supervisor Laravel configuration without actually starting any processes.
Rereading Supervisor Configs and Updating Processes
Apply your Supervisor Laravel configuration changes:
# Read new configuration files
sudo supervisorctl reread
# Update process configurations
sudo supervisorctl update
# Check status of all programs
sudo supervisorctl status
You should see output indicating your Laravel queue workers are available and their current status.
Starting Supervisor with Laravel Worker
Start your Supervisor Laravel workers:
# Start specific program
sudo supervisorctl start laravel-queue-worker:*
# Start all programs
sudo supervisorctl start all
# Check running status
sudo supervisorctl status laravel-queue-worker:*
Your Supervisor Laravel workers should now be running and ready to process background jobs.
Testing the Supervisor Setup
Queuing a Test Job
Verify your Supervisor Laravel configuration works by dispatching test jobs:
# Open Laravel Tinker
php artisan tinker
// Dispatch multiple test jobs
for ($i = 1; $i <= 5; $i++) {
App\Jobs\ProcessEmail::dispatch([
'recipient' => "user{$i}@example.com",
'subject' => "Test Email {$i}"
]);
}
Checking Job Processing via Logs
Monitor your Supervisor Laravel worker logs to confirm job processing:
# View real-time log output
sudo supervisorctl tail -f laravel-queue-worker:laravel-queue-worker_00
# Check Laravel application logs
tail -f /var/www/your-laravel-app/storage/logs/laravel.log
# View supervisor's own logs
tail -f /var/log/supervisor/supervisord.log
You should see log entries indicating jobs are being picked up and processed by your Supervisor Laravel workers.
Handling Failed Jobs
Laravel automatically handles failed jobs when using Supervisor Laravel configuration. Check failed jobs:
# View failed jobs table
php artisan queue:failed
# Retry failed jobs
php artisan queue:retry all
# Clear failed jobs
php artisan queue:flush
Configure failed job handling in your Laravel application by updating the config/queue.php file:
'failed' => [
'driver' => env('QUEUE_FAILED_DRIVER', 'database'),
'database' => env('DB_CONNECTION', 'mysql'),
'table' => 'failed_jobs',
],
Managing Supervisor Processes
Useful Supervisor Commands
Master these essential commands for managing your Supervisor Laravel workers:
# Check status of all processes
sudo supervisorctl status
# Check specific program status
sudo supervisorctl status laravel-queue-worker:*
# Stop specific workers
sudo supervisorctl stop laravel-queue-worker:*
# Start workers
sudo supervisorctl start laravel-queue-worker:*
# Restart workers (useful after code deployments)
sudo supervisorctl restart laravel-queue-worker:*
# Read real-time logs
sudo supervisorctl tail -f laravel-queue-worker:laravel-queue-worker_00
Log File Management and Debugging Issues
Effective log management is crucial for Supervisor Laravel deployments:
Rotate log files to prevent disk space issues:
[program:laravel-queue-worker]
stdout_logfile=/var/www/your-app/storage/logs/queue-worker.log
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=5
stderr_logfile=/var/www/your-app/storage/logs/queue-worker-error.log
stderr_logfile_maxbytes=50MB
stderr_logfile_backups=5
Common debugging commands:
# Check why a worker failed to start
sudo supervisorctl status laravel-queue-worker:*
# View error logs
sudo supervisorctl tail laravel-queue-worker:laravel-queue-worker_00 stderr
# Check system resources
top -p $(pgrep -f "queue:work")
Monitoring Queue Performance with Laravel Horizon
Laravel Horizon provides advanced monitoring for Supervisor Laravel setups:
# Install Horizon
composer require laravel/horizon
# Publish Horizon assets
php artisan horizon:install
# Configure Horizon for production
php artisan horizon:publish
Configure Horizon in config/horizon.php:
'environments' => [
'production' => [
'supervisor-1' => [
'connection' => 'redis',
'queue' => ['default', 'emails'],
'balance' => 'auto',
'processes' => 3,
'tries' => 3,
],
],
],
Start Horizon with Supervisor Laravel by creating a separate configuration:
[program:laravel-horizon]
process_name=%(program_name)s
command=php /var/www/your-laravel-app/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/your-laravel-app/storage/logs/horizon.log
Handling Multiple Queues and Workers
Running Multiple Workers for Different Queues
Supervisor Laravel configurations can handle multiple queue types with different priorities:
[program:laravel-queue-high]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-app/artisan queue:work --queue=high --sleep=1 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/queue-high.log
[program:laravel-queue-default]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-app/artisan queue:work --queue=default --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=4
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/queue-default.log
[program:laravel-queue-low]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-app/artisan queue:work --queue=low --sleep=5 --tries=1
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/queue-low.log
Assigning Priorities and Balancing Load
Configure queue priorities in your Laravel jobs:
<?php
namespace App\Jobs;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
class HighPriorityEmail implements ShouldQueue
{
use Queueable;
public function __construct()
{
$this->onQueue('high');
}
public function handle()
{
// High priority email processing
}
}
Dispatch jobs to specific queues:
// High priority
HighPriorityEmail::dispatch()->onQueue('high');
// Default priority
ProcessEmail::dispatch($data);
// Low priority
ReportGeneration::dispatch($data)->onQueue('low');
Scaling for High-Volume Applications
Scale your Supervisor Laravel setup for increased load:
Horizontal Scaling:
[program:laravel-queue-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-app/artisan queue:work --sleep=1 --tries=3 --max-time=3600
autostart=true
autorestart=true
user=www-data
numprocs=8
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/queue-worker.log
Resource Optimization:
# Monitor memory usage
watch -n 1 'ps aux | grep "queue:work" | grep -v grep'
# Adjust memory limits
php artisan queue:work --memory=256
# Set processing timeouts
php artisan queue:work --timeout=300
Best Practices for Production Environments
Running Supervisor as a Specific User
Create dedicated users for Supervisor Laravel workers to improve security:
# Create queue user
sudo useradd --system --no-create-home --shell /bin/false queue-user
# Set file ownership
sudo chown -R queue-user:queue-user /var/www/your-app/storage
# Update Supervisor configuration
[program:laravel-queue-worker]
user=queue-user
command=php /var/www/your-app/artisan queue:work
# ... other configuration
Log Rotation and Cleanup Strategies
Implement automated log rotation for Supervisor Laravel deployments:
Configure logrotate:
sudo nano /etc/logrotate.d/laravel-supervisor
/var/www/your-app/storage/logs/queue-*.log {
daily
missingok
rotate 14
compress
delaycompress
notifempty
sharedscripts
postrotate
supervisorctl restart laravel-queue-worker:*
endscript
}
Automatic cleanup script:
#!/bin/bash
# Clean old log files
find /var/www/your-app/storage/logs -name "*.log" -mtime +30 -delete
# Clean old failed jobs
cd /var/www/your-app && php artisan queue:prune-failed --hours=168
Security Considerations When Managing Supervisor
Secure your Supervisor Laravel setup:
Restrict configuration file permissions:
sudo chmod 600 /etc/supervisor/conf.d/laravel-queue.conf
sudo chown root:root /etc/supervisor/conf.d/laravel-queue.conf
Use environment variables for sensitive data:
[program:laravel-queue-worker]
command=php /var/www/your-app/artisan queue:work
environment=APP_ENV=production,DB_PASSWORD=%(ENV_DB_PASSWORD)s
Limit network access:
# Configure firewall rules
sudo ufw allow from 127.0.0.1 to any port 9001
sudo ufw deny 9001
Conclusion
Setting up Supervisor Laravel queue workers transforms your application’s background job processing from unreliable manual processes to robust, automatically managed workers. This comprehensive configuration ensures your Laravel applications handle background tasks efficiently while maintaining high availability and performance.
The Supervisor Laravel integration provides essential benefits including automatic worker restarts, detailed logging, and scalable process management. These features are crucial for production environments where reliability and performance directly impact user experience and business operations.
Remember that Supervisor Laravel configuration is just the foundation. Monitor your workers regularly, optimize based on actual usage patterns, and maintain your setup through regular updates and security patches. Start with basic configurations and gradually implement advanced features as your application’s requirements evolve.
Your Supervisor Laravel setup should now handle background jobs reliably, restart workers automatically, and provide the monitoring capabilities needed for production deployments. This foundation will serve your application well as it scales and grows in complexity.
Frequently Asked Questions (FAQ)
Troubleshooting Common Supervisor + Laravel Issues
Q: My Laravel workers keep stopping unexpectedly A: Check memory limits and ensure your jobs don’t consume excessive memory. Add --max-time=3600 to prevent long-running workers from consuming too many resources.
Q: Jobs are not being processed after deployment A: Restart your Supervisor Laravel workers after code deployments:
sudo supervisorctl restart laravel-queue-worker:*
Q: I’m getting permission denied errors A: Verify the user specified in your Supervisor configuration has proper permissions:
sudo chown -R www-data:www-data /var/www/your-app/storage
Do I Need Horizon if I Have Supervisor?
Supervisor Laravel configurations work perfectly without Horizon for basic queue management. However, Horizon provides additional benefits:
- Advanced Monitoring: Real-time queue metrics and job throughput
- Load Balancing: Automatic worker distribution across queues
- Job Retries: Sophisticated retry logic and failed job management
- Web Interface: Browser-based monitoring and control panel
Use Supervisor alone for simple applications or combine both for enterprise-level queue management.
Can I Use Supervisor with Docker and Laravel?
Yes, Supervisor Laravel works excellently in containerized environments:
Dockerfile example:
FROM php:8.2-fpm
# Install Supervisor
RUN apt-get update && apt-get install -y supervisor
# Copy Supervisor configuration
COPY docker/supervisor/laravel-queue.conf /etc/supervisor/conf.d/
# Copy application files
COPY . /var/www/html
# Start Supervisor
CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/supervisord.conf"]
Docker Compose configuration:
version: '3.8'
services:
queue-worker:
build: .
volumes:
- ./:/var/www/html
environment:
- APP_ENV=production
depends_on:
- redis
- database
This approach provides the benefits of Supervisor Laravel queue management within containerized deployments, offering both scalability and reliability for modern application architectures.
