Cron and Heartbeat - softerfish/fyuhls GitHub Wiki

Cron and Heartbeat

Fyuhls uses one server cron entry as a heartbeat. That heartbeat wakes the internal task runner, and the task runner decides which jobs are due.

This means you do not create one server cron job for every maintenance task. You run the Fyuhls cron entry every minute, and Fyuhls handles the per-task schedule internally.

The one command that matters

Run the Fyuhls cron entry every minute:

* * * * * php /home/yourusername/fyuhls/src/Cron/Run.php

Replace the path with your real install path.

What heartbeat means

The heartbeat is the last successful report-in from the cron runner.

If heartbeat is healthy:

  • mail queue can move
  • stats can refresh
  • storage and monitoring jobs can run
  • multipart cleanup can keep up
  • rewards and fraud jobs can process on time

If heartbeat is stale:

  • the site can still load
  • but background behavior starts drifting

What cron is responsible for

Fyuhls cron handles background work such as:

  • cleanup of stale temporary data
  • multipart upload-session expiry and quota release
  • multipart reconciliation and checksum finishing
  • queued remote URL imports
  • outbound mail queue processing
  • storage audits and monitoring
  • dashboard and stats refreshes
  • reward summaries and payout support jobs
  • fraud maintenance jobs when rewards are enabled
  • Nginx completion-log ingestion for completion-aware workflows

How task frequency works

Your server cron still runs every minute.

Inside Fyuhls, each managed task has its own interval in minutes. Those intervals are stored and edited in:

  • Admin > Config Hub > Cron Jobs

Changing those values changes the internal schedule. It does not rewrite your server crontab.

How to read the Cron Jobs page

Important signals:

  • System Healthy / Cron Jobs Offline

    • this is the heartbeat health view
  • Scheduled Cron Jobs

    • shows each task name, interval, last run, runtime, and last status
  • Never

    • means no successful run has been recorded yet
    • for expected core or enabled-feature tasks, that is a real signal to investigate
  • Trigger All Tasks Now

    • useful for testing only
    • not a replacement for a real cron entry

Common task groups

Cleanup and upload-state tasks

  • cleanup
  • upload_sessions
  • upload_reconcile
  • checksum_jobs

These matter when uploads stall, reserved quota sticks around, or object-storage state drifts.

Queue tasks

  • remote_uploads
  • mail_queue

These matter when remote imports or email stop moving.

Storage and monitoring tasks

  • storage_audit
  • server_monitoring
  • refresh_stats

These matter when dashboard stats go stale, nodes look unhealthy, or capacity numbers drift.

Rewards and fraud tasks

When rewards are enabled, Fyuhls can register:

  • reward_flush
  • reward_rollup
  • fraud_cleanup
  • fraud_scores
  • fraud_clearance

If those still show Never on a live site that should be using them, the usual causes are:

  • rewards are disabled
  • cron is running the wrong install path
  • the live runner is older than the web code
  • the task is failing before it records success

Why a task can show Never

Common reasons:

  • the task is feature-gated and that feature is off
  • cron is not running
  • cron is running the wrong filesystem path
  • the live runner does not register that task
  • the task is failing before success is recorded
  • the install is fresh and the task has not cycled yet

Most common cron mistakes

Running the wrong path

The admin UI can show the current app while the server cron still points at:

  • an old install
  • a staging copy
  • a previous folder name

Running it less often than expected

Fyuhls expects the runner every minute. Slower schedules cause background behavior to feel stale.

Assuming manual trigger replaces real cron

It does not. It is only a test tool.

Forgetting CLI PHP differences

Sometimes web PHP and CLI PHP are not the same binary or config. If cron fails while the site works, compare the PHP versions and CLI extensions.

How to troubleshoot cron safely

Use this order:

  1. confirm the exact server cron command and full file path
  2. confirm the runner file exists at that path
  3. confirm cron is scheduled every minute
  4. check heartbeat freshness on the Cron Jobs page
  5. inspect last-run times for the tasks you care about
  6. use Trigger All Tasks Now only as a test
  7. check System Status and recent errors if tasks still do not move

Best practices

  • always run the Fyuhls cron entry every minute
  • use the exact live install path, not a guessed one
  • re-check the cron path after moving or cloning the app
  • treat Never on expected tasks as a real signal
  • check cron first whenever many unrelated background features feel stale

Short version

Fyuhls cron is a one-minute heartbeat that wakes the scheduler.

If heartbeat is healthy, background features keep moving. If heartbeat is stale, the site may still load, but email, uploads, rewards, stats, and cleanup slowly stop behaving like a live system.

⚠️ **GitHub.com Fallback** ⚠️