Queue workers and scheduled tasks

Agovena needs two background processes in a native Linux installation:

1. A persistent queue worker for jobs such as mail, webhooks, subscriptions and provisioning.
2. A cronjob that runs the Laravel scheduler every minute.

The store can load without them, but queued work and scheduled tasks will stop.

1. Install cron

Use the tab for your operating system if cron is not installed yet:

sudo apt update
sudo apt install -y cron
sudo systemctl enable --now cron

sudo apt-get update
sudo apt-get install -y cron
sudo systemctl enable --now cron

2. Add the Agovena cronjob

Open the crontab for the same runtime user that can read the application and write storage/ and bootstrap/cache/. The supplied deployment uses www-data:

sudo -u www-data crontab -e

Add this one line:

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

Keep other cronjobs in the file. If PHP is installed somewhere else, use the path returned by command -v php. If your PHP-FPM and queue user is not www-data, replace that username in the command.

Check the saved entry:

sudo -u www-data crontab -l

3. Install the queue worker

Copy Agovena's systemd unit and enable it:

cd /var/www/agovena
sudo cp deploy/systemd/agovena-queue.service /etc/systemd/system/agovena-queue.service
sudo systemctl daemon-reload
sudo systemctl enable --now agovena-queue.service

The unit runs this worker:

/usr/bin/php /var/www/agovena/artisan queue:work --sleep=1 --tries=3 --timeout=60 --backoff=5 --max-time=3600

If your PHP path, application path or runtime user is different, edit /etc/systemd/system/agovena-queue.service before starting it. Then reload systemd again.

Check the worker:

sudo systemctl status agovena-queue.service
sudo journalctl -u agovena-queue.service -n 50 --no-pager

Use either this systemd unit or the supplied Supervisor configuration for one worker. Do not run both for the same queue.

4. Check scheduled tasks

Run these commands from the application directory:

cd /var/www/agovena
php artisan schedule:list
php artisan schedule:run
php artisan agovena:doctor

schedule:list shows the registered schedule. schedule:run executes tasks that are due, so it changes application state and is not only a diagnostic.

The scheduler covers recurring application work such as webhook delivery, deferred payment reconciliation, subscription renewals, provisioning synchronization and backup schedules. Which tasks run also depends on enabled modules and store settings.

Check Admin → Cron statistics, Failed jobs and Updates after the first minute has passed.

5. Restart after updates

Workers keep the loaded application code in memory. Restart them after deploying new files or changing the environment:

cd /var/www/agovena
php artisan queue:restart
sudo systemctl restart agovena-queue.service

The process manager must start the worker again if it exits. Keep the scheduler cronjob in place during updates unless the update guide tells you to pause it temporarily.

6. Docker Compose

Docker Compose runs worker with queue:work and scheduler with schedule:work. Do not add the native host cronjob for the Compose scheduler. Follow the Docker Compose guide and keep both services running:

docker compose -f docker-compose.prod.yml up -d worker scheduler
docker compose -f docker-compose.prod.yml ps

7. Troubleshoot background work

If queued work is not processed:

1. Check systemctl status agovena-queue.service.
2. Read the last worker logs with journalctl.
3. Check Admin → Failed jobs.
4. Confirm that the queue connection in .env matches the configured database or Redis service.
5. Run php artisan agovena:doctor and read warnings as well as the exit code.

If scheduled work is not running, check the crontab, the PHP path, the runtime user and the scheduler heartbeat. For payments or provisioning, check the external provider before retrying a failed job to avoid a duplicate external action.