Keep queue workers running

1. Prepare Laravel and verify one job cycle

Run these commands from the deployed Laravel project root. Replace /var/www/easyplex everywhere in this guide with the real absolute path. The PHP CLI binary may be versioned on your server, such as /usr/bin/php8.2; confirm it with command -v php.

cd /var/www/easyplex
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
php artisan queue:work --once --tries=3 --timeout=300
php artisan queue:failed

Use one of these production queue settings:

# Database queue
QUEUE_CONNECTION=database

# Or Redis, after configuring a working Redis connection
QUEUE_CONNECTION=redis

Do not run both process managers. Installing the Supervisor and systemd examples together creates duplicate workers and can process more jobs concurrently than intended.

2A. Supervisor configuration

Use this option on Ubuntu/Debian servers with Supervisor. Install it with sudo apt install supervisor, then create /etc/supervisor/conf.d/easyplex-worker.conf:

[program:easyplex-worker]
process_name=%(program_name)s_%(process_num)02d
directory=/var/www/easyplex
command=/usr/bin/php /var/www/easyplex/artisan queue:work --queue=default --sleep=3 --backoff=5 --tries=3 --timeout=300 --memory=256 --max-time=3600
user=www-data
numprocs=1
autostart=true
autorestart=true
startsecs=5
startretries=3
stopasgroup=true
killasgroup=true
stopwaitsecs=360
redirect_stderr=true
stdout_logfile=/var/www/easyplex/storage/logs/worker.log
stdout_logfile_maxbytes=20MB
stdout_logfile_backups=5

Load and verify Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start easyplex-worker:*
sudo supervisorctl status easyplex-worker:*
sudo tail -f /var/www/easyplex/storage/logs/worker.log

A healthy status contains RUNNING. If the process repeatedly enters BACKOFF or FATAL, inspect the worker log and storage/logs/laravel.log; do not hide the error by increasing restart counts.

2B. systemd configuration

Use this option when the server manages application processes directly with systemd. Create /etc/systemd/system/easyplex-worker.service:

[Unit]
Description=EasyPlex Laravel queue worker
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/easyplex
ExecStart=/usr/bin/php /var/www/easyplex/artisan queue:work --queue=default --sleep=3 --backoff=5 --tries=3 --timeout=300 --memory=256 --max-time=3600
Restart=always
RestartSec=5
TimeoutStopSec=360
KillSignal=SIGTERM
StandardOutput=journal
StandardError=journal
SyslogIdentifier=easyplex-worker

[Install]
WantedBy=multi-user.target

Load and verify systemd

sudo systemctl daemon-reload
sudo systemctl enable --now easyplex-worker
sudo systemctl status easyplex-worker
sudo journalctl -u easyplex-worker -f

A healthy status contains active (running). After editing the unit file, run daemon-reload before restarting the service.

3. Safe deployment procedure

1. Enable maintenance mode if the deployment changes database or public behavior: php artisan down.
2. Deploy the PHP source and run composer install --no-dev --optimize-autoloader.
3. Run php artisan migrate --force and php artisan optimize:clear.
4. Run php artisan queue:restart. Existing workers finish their current job and restart under the selected process manager.
5. Leave maintenance mode with php artisan up, then verify worker status and logs.

cd /var/www/easyplex
php artisan down
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
php artisan queue:restart
php artisan up

# Choose the status command matching your manager:
sudo supervisorctl status easyplex-worker:*
sudo systemctl status easyplex-worker

4. Failed-job inspection and recovery

php artisan queue:failed
tail -f storage/logs/laravel.log

php artisan queue:retry FAILED_JOB_ID
php artisan queue:retry all

Destructive command: php artisan queue:flush deletes all failed-job records. Do not use it as routine troubleshooting.

5. Configure the scheduler separately

The queue worker executes queued jobs; it does not trigger Laravel’s scheduled commands. Add this independent cron entry for the web-server user:

* * * * * cd /var/www/easyplex && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

cd /var/www/easyplex
php artisan schedule:list
php artisan schedule:run

Production verification checklist