How to Set Up Laravel Queue Worker on Ubuntu with Supervisor (With Study Case & Implementation)

Laravel provides a powerful queue system that allows you to run time-consuming tasks like sending emails, resizing images, or processing payments in the background. But in a production environment, we need a reliable way to keep the queue worker running 24/7.

That’s where Supervisor comes in — a Linux process monitor that ensures your Laravel queue worker keeps running and automatically restarts it if it crashes. In this article, you’ll learn:

• ✅ What Supervisor is and why you need it
• ✅ How to configure Laravel for queues
• ✅ How to create and dispatch a real job
• ✅ How to set up Supervisor on Ubuntu
• ✅ How to monitor and control the worker

What Is Supervisor?

Supervisor is a process control system for Unix-like operating systems. It allows you to:

• Run background tasks (like Laravel queue workers)
• Restart them automatically if they crash
• Launch them on system boot
• Manage them from the terminal (start, stop, restart)

Why Laravel Needs Supervisor

When you run a Laravel worker with:

php artisan queue:work

…it will stop if:

• The SSH session ends
• The server restarts
• An error crashes the process

With Supervisor, your worker will:

• Run in the background
• Restart automatically if it fails
• Start at boot
• Be monitored and controlled easily

📚 Study Case: Background Email After User Registers

🎯 Problem

You want to send a welcome email every time a user registers. But you don’t want to make the user wait while the email is being sent.

✅ Solution

Use Laravel’s queue system to defer the email to a background process. Supervisor will keep that process running in production.

Step 1: Setup Queue Driver in Laravel

Open your .env file and set:

QUEUE_CONNECTION=database

Then run:

php artisan queue:table
php artisan migrate

This creates a jobs table to store pending background tasks.

Step 2: Create a Job to Send Email

Create the job class:

php artisan make:job SendWelcomeEmail

Update app/Jobs/SendWelcomeEmail.php:

use App\Models\User;
use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public User $user) {}

    public function handle()
    {
        Mail::to($this->user->email)->send(new WelcomeMail($this->user));
    }
}

Now create the mailable class:

php artisan make:mail WelcomeMail --markdown=emails.welcome

Update the email template in resources/views/emails/welcome.blade.php:

@component('mail::message')
# Welcome, {{ $user->name }}

Thanks for joining our platform.

@component('mail::button', ['url' => url('/login')])
Login Now
@endcomponent

Thanks,<br>
{{ config('app.name') }}
@endcomponent

Then, in your controller (e.g. RegisterController):

use App\Jobs\SendWelcomeEmail;

public function register(Request $request)
{
    $user = User::create($request->all());

    // Dispatch job to queue
    SendWelcomeEmail::dispatch($user);

    return response()->json(['message' => 'User registered successfully.']);
}

Step 3: Test Locally

Try running the worker manually:

php artisan queue:work

Register a new user. You should see the job being processed, and the email sent in the terminal.

Step 4: Install Supervisor on Ubuntu

On your Ubuntu server, run:

sudo apt update
sudo apt install supervisor

Then create a config file:

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

Add the following config:

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

Notes: Replace /var/www/your-laravel-app with the actual path to your Laravel project.

• --sleep=3 : Wait 3 seconds before checking again if no jobs are available
• --tries=3 : Retry a failed job 3 times before marking it as failed
• --timeout=90 : Kill the job if it runs longer than 90 seconds (useful for stuck jobs)

Step 5: Start and Monitor Supervisor

Reload the config:

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

Check status:

sudo supervisorctl status

Monitor logs:

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

Conclusion

Using Laravel queues with Supervisor gives you a powerful, scalable, and production-ready solution for handling background jobs. Supervisor ensures that your queue worker:

• Runs in the background
• Recovers automatically from failure
• Keeps your app fast and reliable

With this setup, you're ready to confidently handle tasks like email sending, notifications, file processing, and more — all asynchronously.