Background worker
apps/worker runs one loop that executes several jobs for every active tenant.
| Job | Default cadence | Does | Variable |
|---|---|---|---|
imports |
every 5 s | Claims one pending import job per tenant (queued with POST /v1/imports/upload) and processes it in batches of 100 rows |
WORKER_POLL_INTERVAL_SECONDS |
reminders |
every 60 s | Creates appointment and follow-up reminder notifications according to notification settings; never duplicates | WORKER_REMINDER_INTERVAL_SECONDS |
schedules |
every 60 s | Runs due report schedules, stores the export, emails it if SMTP is configured, and sets the next run | WORKER_SCHEDULE_INTERVAL_SECONDS |
cleanup |
hourly | Deletes pending public submissions whose confirmation link expired, and their uploaded files | WORKER_CLEANUP_INTERVAL_SECONDS |
Set a job's interval to 0 to disable it. The worker runs the database migrations at start-up, and stops cleanly on SIGINT/SIGTERM.
Note: Imports run from the File Uploads wizard are processed by the API immediately, not by the worker.
Logs
[worker] started; jobs: imports/5s, reminders/60s, schedules/60s, cleanup/3600s
[worker] reminders acme: 3
[worker] imports acme: 1
[worker] schedules acme/<id> failed: <message>
Troubleshooting
| Symptom | Check |
|---|---|
| No reminders | Worker running? Reminders enabled in Settings → Notifications? Staff assigned? |
| Scheduled reports never run | Worker running? Schedule Enabled? Next run in the past? Errors in the worker log? |
| Scheduled report runs but no email | SMTP configured for the worker container too (it reads .env) |
| Queued imports stuck in Pending | Worker running and connected to the same database |
| Inactive tenant ignored | Expected: only active tenants are processed |