What the Queue Does
Commerce uses Laravel's queue system to process background jobs asynchronously. If the queue worker is not running, none of the following will work:
- Transactional emails (welcome emails, invoices, password resets)
- Service provisioning (account creation, suspension, termination)
- Domain registration, transfer, and renewal jobs
- Renewal invoice generation
- Webhook delivery
Symptoms of a Stopped Queue
| Symptom | Likely Cause |
|---|---|
| No emails being sent | Queue worker stopped |
| Services stuck in "Pending Provisioning" | Queue worker stopped or job failed |
| Domain registration never completes | Queue worker stopped or job failed |
| Invoices not generated at renewal | Queue worker stopped or scheduler issue |
Checking Queue Status
Check if the worker process is running:
ps aux | grep "queue:work"
If you see a php artisan queue:work process, the worker is running.
If using Supervisor:
supervisorctl status
Look for your queue worker entry (e.g., opterius-queue-worker). It should show RUNNING.
Restarting the Queue
Graceful restart (finishes the current job then restarts):
php artisan queue:restart
This sets a flag that tells the worker to stop after its current job completes. Supervisor will then auto-restart it. The worker does not restart itself — supervisor must be configured with autorestart=true.
If not using Supervisor, start manually:
php artisan queue:work --sleep=3 --tries=3 --timeout=60
Run this in a screen or tmux session, or set it up with Supervisor for persistence.
Setting Up Supervisor
Create a Supervisor config file at /etc/supervisor/conf.d/opterius-queue.conf:
[program:opterius-queue-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /opt/opterius/artisan queue:work --sleep=3 --tries=3 --timeout=60
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/supervisor/opterius-queue-worker.log
stopwaitsecs=3600
Apply the config:
supervisorctl reread
supervisorctl update
supervisorctl start opterius-queue-worker
[!TIP] Set
stopwaitsecsto at least as long as your longest job timeout. If a provisioning job takes 60 seconds andstopwaitsecsis 10, Supervisor will kill the job mid-run when you do a graceful restart.
Checking Failed Jobs
Jobs that fail after exhausting their retry attempts are moved to the failed jobs table:
php artisan queue:failed
Retrying Failed Jobs
Retry a single failed job:
php artisan queue:retry {id}
Retry all failed jobs:
php artisan queue:retry all
Flush all failed jobs (clears the list without retrying — use with care):
php artisan queue:flush
Queue Configuration
Key queue settings in .env:
| Variable | Recommended Value | Description |
|---|---|---|
QUEUE_CONNECTION |
database |
Uses MySQL to store jobs — reliable and no extra services needed |
QUEUE_FAILED_DRIVER |
database-uuids |
Stores failed jobs in the database for inspection |
Laravel Horizon (Optional)
Horizon is an optional queue monitoring dashboard built by the Laravel team. It provides a real-time web UI showing throughput, job runtimes, and failures.
Install with:
composer require laravel/horizon
php artisan horizon:install
php artisan migrate
Access at /horizon (restricted to staff by default). Horizon replaces the plain queue:work command with php artisan horizon.
[!IMPORTANT] Horizon is a convenience tool, not a requirement. The standard
queue:workcommand works perfectly well for most Commerce installations. Only install Horizon if you need visibility into job throughput or are debugging performance issues.