Cron & queue workers

Almost everything time-driven in Zodiac Tech CRM — reminders, WhatsApp appointment sweeps, Meta syncs, billing lifecycle, backups, e-mail sequences — rides on one cron entry hitting Laravel's scheduler every minute. On production installs the queue should be database, drained by the same cron (or a supervised worker on VPS).

Who this is for#

• Super-admin / hosting admin — wiring the cron line.
• Developer — choosing queue strategy per host.
• Support — "e-mails/reminders aren't sending" almost always ends here.

Prerequisites: the app is installed and reachable.

Step 1 — Add the cron entry#

Standard (Terminal/SSH available or cPanel Cron Jobs):

* * * * * cd /home/YOURUSER/crm-app && php artisan schedule:run >> /dev/null 2>&1

Shared hosting without a usable PHP binary path: use cPanel's shown PHP binary:

* * * * * /usr/local/bin/ea-php84 /home/YOURUSER/crm-app/artisan schedule:run >> /dev/null 2>&1

No SSH and no artisan cron available — the shipped fallback runner:

* * * * * php /home/YOURUSER/public_html/crm/cron.php

cron.php drains queued jobs (up to 30 per run, within a ~55-second budget) across all named queues, then runs schedule:run — a complete replacement for both the worker and the scheduler. It requires storage/installed.lock, and if you open it in a browser it refuses to work unless you set a CRON_SECRET first.

Expected result: within two minutes, storage/logs/laravel.log starts showing scheduled task activity, and queued e-mails/jobs stop accumulating in the jobs table.

Step 2 — Configure the queue#

The shipped .env.example already sets QUEUE_CONNECTION=database. Jobs are partitioned into named queues — default, webhooks, automations, integrations, notifications, exports, ai-sdr, mail — so heavy work (exports, AI) cannot delay time-sensitive work (webhooks, mail).

Step 3 — Drain the queue#

Shared hosting (recommended): add a second cron entry that runs a finite worker every minute:

* * * * * cd /home/YOURUSER/crm-app && php artisan queue:work --queue=default,webhooks,automations,integrations,notifications,exports,ai-sdr,mail --stop-when-empty --max-time=55 >> /dev/null 2>&1

--stop-when-empty exits when there is nothing to do; --max-time=55 guarantees the run ends before the next minute's cron fires. Combined with the scheduler entry from Step 1, this needs no long-running process. (The cron.php fallback already does this for you.)

VPS / dedicated (supervised worker): run a persistent worker with a process supervisor, and list the named queues explicitly:

php artisan queue:work --queue=default,webhooks,automations,integrations,notifications,exports,ai-sdr,mail --tries=3 --timeout=120

After every deploy, restart workers so they pick up new code:

php artisan queue:restart

The full schedule#

Everything below is registered in routes/console.php. Every task runs with withoutOverlapping(10) (a stuck run never blocks the slot for a day) and logs a structured warning — schedule task failed: <name> — if it throws.

Failed jobs#

With database queues, failures land in the failed_jobs table:

php artisan queue:failed          # list
php artisan queue:retry all       # retry everything
php artisan queue:failed-forget all  # discard

Webhook deliveries and automations are designed to be retry-safe (idempotent), so queue:retry all is normally safe. Investigate recurring failures via storage/logs/laravel.log.

Common mistakes#

• Adding the schedule entry but not the worker drain (with database) — scheduled dispatches work but queued jobs never run.
• Two queue:work processes on the same queue without --stop-when-empty supervision — duplicated processing on non-idempotent jobs.
• Forgetting that cron runs as a different user/php.ini — test the command manually and check storage/logs.
• Using sync in production "because it works" — page loads get slow and a mail timeout blocks the request.
• Not running queue:restart after deploys (supervised workers keep old code).

Troubleshooting#

Technical details#

• Schedule definition: routes/console.php (all tasks; withoutOverlapping(10) + onFailure logging).
• Shared-host runner: root cron.php (30 jobs/55 s across default,webhooks,automations,integrations,notifications,exports,ai-sdr,mail, then schedule:run).
• Nightly backup gate: App\Settings\GeneralSettings->auto_nightly_backup or config('leadhub.backups.auto_nightly').
• Backup command: leadhub:backup (--prune=DAYS optional).

Related guides#

• Backups & restore
• Environment variables
• Queues, jobs & scheduler
• Daily checks