Worker runtime: Nitro scheduled task vs dedicated Coolify worker (decide + spike)

[peetzweg]

Part of #106 — decide and prove out where the refresh worker runs, then wire a minimal job end-to-end.

Options (from research)

A. Nitro in-process scheduledTasks. Nitro does fire scheduled tasks on the node-server preset via an in-process croner engine — no external trigger needed (the "doesn't fire on Node" belief is Vercel/Cloudflare-preset-specific). Config via the nitro/vite plugin (experimental.tasks: true + scheduledTasks), tasks in server/tasks/…. Lowest infra.
Downside: a long, rate-limited job shares the web process (memory contention) and is killed with no resume on every web redeploy (Coolify replaces the container; croner does no catch-up).

B. Dedicated Coolify worker. Coolify has built-in container-level Scheduled Tasks (5-field cron). Run the job in a separate worker service (own container, own resource limits, own deploy) — survives web deploys, isolates load, separate logs. Downside: one extra Coolify resource + the job image needs its deps (a reported gotcha: curl: not found in slim images — call node or install curl).

Middle ground: keep the job code as a shared script/package in this repo (our scripts/* already are the worker), housed in the worker container, triggered by Coolify's scheduler.

Recommendation

Given our jobs are GitHub-rate-limited and occasionally multi-minute, lean B (dedicated Coolify worker) for the heavy refresh; Nitro tasks stay fine for light/idempotent jobs. Confirm with a small spike.

Acceptance criteria

• Decision recorded (A vs B vs hybrid) with rationale
• Spike: one real job (e.g. backfill-orgs.ts or the sub-issue-A hot-tier pass) running on the chosen runner on the Coolify box, on a schedule, surviving a web redeploy
• Jobs confirmed idempotent + checkpointed (resume after a killed run)
• Ops notes: where logs land, how to trigger a manual run, how secrets/DATABASE_URL/GITHUB_TOKEN reach the worker

References

• Nitro Tasks: https://nitro.build/docs/tasks
• TanStack Start hosting / Nitro config: https://tanstack.com/start/latest/docs/framework/react/guide/hosting
• Coolify scheduled tasks / cron: https://coolify.io/docs/knowledge-base/cron-syntax , How to setup Scheduled Task in nextjs project coollabsio/coolify#3228
• Coolify host-cron limitation (container-level only): [Feature]: Server-level scheduled tasks (host cron, not container-level) coollabsio/coolify#8500

[peetzweg]

Concrete, reusable worker entrypoints now exist (both in #104):

• scripts/backfill-orgs.ts — fills orgs with lifetime org-scoped totals, smallest-first, cross-run resumable.
• scripts/discover-orgs.ts — finds + records orgs to track.

Both are already idempotent, checkpointed, and rate-limit-polite (paced under GitHub's hourly limit with a 500-request floor for live traffic), and both need the read:org token. So the spike here can schedule/wrap these rather than write new fetch logic — which also keeps the "job code as a shared script the worker calls" option (leaning: dedicated Coolify worker) cheap to stand up.