A Beginner’s Guide to Laravel Queue Workers with Supervisor on CloudPanel

April 10, 2026

This guide will work over 92% times on all ubuntu/dembian server – with or without cloudpanel. If you are not using cloudpanel or any control panel, then you have to make sure you install REDIS

If you’re running a Laravel application on a CloudPanel server, setting up queue workers properly is one of those things you can’t afford to ignore. Background jobs—like sending emails, processing uploads, or handling payments—depend on a reliable queue system. And that’s where Supervisor comes in.

But here’s the mistake many beginners make: they jump straight into installing and configuring Supervisor without first checking what already exists. That’s how configurations get overwritten, workers conflict, and things quietly break.

Let’s walk through this the right way—from verification to setup, Redis configuration, and safe updates.

Step 1: Confirm if Supervisor Is Already Installed

Before doing anything, you need to confirm whether Supervisor is already installed on your server. CloudPanel environments are often reused or pre-configured, so don’t assume you’re starting from scratch.

Run this command:

which supervisord

If Supervisor is installed, you’ll see a path like:

/usr/bin/supervisord

If nothing shows up, it’s likely not installed.

Next, check the version:

supervisord --version

If you get a version number, you’re good. If you see “command not found,” it’s not installed.

Now check the service status (this is the most reliable check):

sudo systemctl status supervisor

If it says active (running) → Supervisor is already running
If it says inactive (dead) → It’s installed but not running
If it says Unit not found → Not installed at all

Finally, check if any queue workers already exist:

ls /etc/supervisor/conf.d/

If you see something like:

laravel-worker.conf

That means someone (maybe you) has already configured a worker. Don’t overwrite it blindly—inspect it first.

Also check running processes:

sudo supervisorctl status

If you see RUNNING, your queue workers are already active.

Step 2: Install Supervisor (If Needed)

If Supervisor is not installed, install it with:

sudo apt update
sudo apt install supervisor -y

Then enable and start it:

sudo systemctl enable supervisor
sudo systemctl start supervisor

At this point, Supervisor is ready—but it’s not doing anything yet.

Step 3: Set Up Supervisor on a CloudPanel Server

CloudPanel uses a specific directory structure, so your Laravel app is typically located here:

/home/cloudpanel/htdocs/yourdomain.com

You’ll now create a Supervisor configuration for your queue worker.

Create a new config file:

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

Add this basic configuration:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/cloudpanel/htdocs/yourdomain.com/artisan queue:work redis --sleep=3 --tries=3 --timeout=90
autostart=true
autorestart=true
user=cloudpanel
numprocs=2
redirect_stderr=true
stdout_logfile=/home/cloudpanel/htdocs/yourdomain.com/storage/logs/worker.log

Important things to adjust:

Replace yourdomain.com with your actual app path
Ensure the user is cloudpanel (default for CloudPanel)
Adjust numprocs depending on your server capacity

This configuration tells Supervisor to:

Run your Laravel queue worker
Restart it if it crashes
Run multiple processes for concurrency
Log output for debugging

Step 4: Configure Laravel Queue for Redis

Now let’s make sure Laravel itself is set up correctly.

Open your .env file and update:

QUEUE_CONNECTION=redis

Also ensure Redis is properly configured:

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

If Redis is not installed, install it:

sudo apt install redis-server -y
sudo systemctl start redis

Test Redis:

redis-cli ping

Expected response:

PONG

Step 5: Start and Register the Worker

After creating your Supervisor config, you need to load it:

sudo supervisorctl reread
sudo supervisorctl update

Then start the worker:

sudo supervisorctl start laravel-worker:*

Check status:

sudo supervisorctl status

If everything is correct, you should see:

laravel-worker:laravel-worker_00   RUNNING

Step 6: Updating Queue Configuration Safely

This is where many beginners break things.

If you change anything in:

.env
queue.php
Supervisor config

You must restart things properly.

1. Restart Laravel Queue Workers

php artisan queue:restart

This tells workers to gracefully restart after finishing current jobs.

2. Reload Supervisor (if config changed)

If you edited the Supervisor config file:

sudo supervisorctl reread
sudo supervisorctl update

Then restart:

sudo supervisorctl restart laravel-worker:*

3. Clear and Cache Config

Whenever you change .env, run:

php artisan config:cache

Step 7: Debugging and Monitoring

Don’t just “set and forget” your queue system.

Check logs regularly:

storage/logs/worker.log

Check failed jobs:

php artisan queue:failed

Retry failed jobs:

php artisan queue:retry all

Final Advice for Beginners

Here’s the truth: queues don’t fail loudly. They fail silently.

So you need to be disciplined about:

Checking Supervisor status
Watching logs
Restarting workers after changes

If you skip these, you’ll end up with jobs stuck in the queue and no clear error.

Start simple:

One worker
Redis queue
Basic logging

Then scale up as your app grows.

If you want to level up later, consider using Laravel Horizon. It gives you a dashboard, metrics, and better control over Redis queues—but only after you’ve mastered the basics above.