Skip to content

Source: docs/adr/0009-scheduler-and-queue-worker.md. Edit it there; this page is generated at build time.

The scheduler is one line in deploy's crontab and the worker is a systemd user unit, and every deploy installs both ​

Neither existed anywhere until now, and both fail silently when they are missing. Without schedule:run, scheduled content never goes live. Without a worker, app:refresh-merchant-prices queues batches nobody runs, and prices degrade to "Check {merchant}" CTAs once they pass their TTL (ADR 0006). The done-when for issue #24 is that a tag deploy leaves both running on the new code with nobody having configured either by hand. So both are defined in the repo and installed by deploy/recipe/runtime.php, which deploy.php requires after Deployer's recipe/laravel.php.

The worker is a systemd user unit owned by deploy, and its only root step is loginctl enable-linger deploy, run once. A system unit in /etc/systemd/system would need root every time the unit changed. That means either a person running install after the release (the change and the deploy drift apart) or a sudoers entry for the deploy user (the one privilege ADR 0007 and #18 were written to avoid). A user unit lives in ~deploy/.config/systemd/user/, so the deploy can rewrite and reload it as deploy. Lingering is what makes that user's systemd manager start at boot instead of only while someone is logged in. Supervisor was never a candidate: the box already has systemd, and a second process manager adds a config language and gives up the journal. Checked on the box on 2026-09-19: the user manager runs inside this LXC container, and systemctl --user reaches it from a stripped environment (only HOME, PATH and XDG_RUNTIME_DIR set) like the runner's service has. That is why the recipe passes XDG_RUNTIME_DIR explicitly.

One worker, queue:work database --queue=default --sleep=3 --timeout=60 --max-time=3600. There is one job class, and it spends its time waiting on a merchant API that asks for calls to be spread out (ADR 0006). A second worker would mostly add contention for the throttle. --timeout=60 has to stay below the database connection's retry_after of 90. Otherwise a slow job is handed to a second attempt while the first is still writing prices. tests/Feature/QueueWorkerUnitTest.php pins that relationship, because nothing else would notice. --tries is deliberately left out: RefreshAffiliateLinkPrices declares $tries = 3, and the job's own value beats the worker flag (Worker.php, vendored Laravel 13.30.1), so the flag would only mislead a reader. --max-time restarts the process hourly, to shed leaked memory and as a backstop for a deploy whose reload did not arrive.

Restart=always, not on-failure. queue:restart and --max-time both end the worker with exit 0, so on-failure would leave it stopped after every deploy, and the test pins this too.

A deploy moves the worker with queue:restart, never systemctl restart. Deployer 8.0.5's Laravel flow already ends with artisan:reload. On Laravel 12.41 or later that runs php artisan reload, which on our vendored 13.30.1 calls queue:restart and schedule:interrupt (read from ReloadCommand.php). queue:restart lets the running job finish before the process exits, where a systemctl restart would kill it mid-batch. The unit's ExecStart goes through current, so systemd's restart lands on the new release. The recipe installs the unit and enables it with --now straight after deploy:symlink, while the deploy lock is still held. daemon-reload means a changed unit file takes effect at that restart, and the first deploy starts the worker.

Rollback reloads too. Deployer's rollback task only flips the symlink; nothing in the Laravel recipe hooks it. Left alone, a rolled-back box keeps the newer release's worker for up to an hour. after('rollback', 'artisan:reload') closes that gap, and the test pins it. Rollback does not reinstall the unit file, so a release that changed the unit keeps its version after a rollback. That is acceptable while the unit changes this rarely, and it is the first thing to look at if it ever matters.

The scheduler is one line in deploy's crontab, managed by Deployer's contrib/crontab.php. crontab:sync rewrites only the lines between its ###< blog-filament and ###> blog-filament markers, runs as deploy without sudo, and runs on every deploy after the flip. So the line in the repo is the line on the box. The line cds into current every minute, so it follows the live release with no reload at all:

* * * * * cd /var/www/blog-filament/current && /usr/bin/php artisan schedule:run -q 2>&1 | logger -t blog-filament-schedule

Logs go to the journal, and the journal rotates them. The worker's stdout lands in deploy's user journal (journalctl --user -u blog-filament-worker). The scheduler's -q keeps errors and nothing else, and logger tags them blog-filament-schedule. So a scheduler that cannot boot leaves a line somewhere, rather than in /dev/null like the old Hostinger advice. The journal on this box is persistent and size-capped by journald's defaults, so neither needs a logrotate rule. Whether scheduled tasks actually ran on time is not a log question: the admin's Scheduler page answers it (#25). The application's own log, storage/logs/, is the gap. The default LOG_STACK=single writes one file that grows forever. Production should set LOG_STACK=daily, which keeps LOG_DAILY_DAYS (default 14). That is a line in .env.production, not code, so it lands with the encrypted env (ADR 0007).

What this gives up: the worker and the scheduler exist only once a deploy has run, and enable-linger has to be done by root before the first one. systemctl status as root does not show a user unit. systemctl --user status blog-filament-worker, run as deploy, is the command that does.