Single-source the scheduler help from markdown the AI index can read
This commit is contained in:
Gmer4Lfe
@@ -307,6 +307,7 @@ if (is_dir('/var/log/varaverk')) {
|
||||
<div>
|
||||
<select id="vv-ai-kind" title="Restrict retrieval to one kind of source">
|
||||
<option value="">All sources</option>
|
||||
<option value="ui">WebUI — how the pages work</option>
|
||||
<option value="readme">README — what things are</option>
|
||||
<option value="manual">Manual — how to do things</option>
|
||||
<option value="header">Script headers</option>
|
||||
|
||||
@@ -0,0 +1,171 @@
|
||||
# Scheduler
|
||||
|
||||
Everything that runs on a timer is decided here. The page is the front end for two files:
|
||||
`schedule.json` holds when things fire, and `master.conf` holds which steps an orchestrator
|
||||
actually calls. Every control below writes to one of those two — nothing on this page needs a
|
||||
conf file opened by hand.
|
||||
|
||||
**An orchestrator is a job that calls other scripts in order.** The orchestrator has the cron
|
||||
entry; its steps do not. That one fact explains most of the behaviour below.
|
||||
|
||||
---
|
||||
|
||||
## Stopping one step without disabling the whole job
|
||||
|
||||
The common case: a nightly job is fine, but one script inside it should stop running.
|
||||
|
||||
1. Find the orchestrator's card — for example **Daily Sync Maintenance**.
|
||||
2. Click **Steps ▸** on the right of its row. The list of scripts it calls expands.
|
||||
3. Toggle off the one you want stopped.
|
||||
|
||||
The orchestrator keeps running on its schedule and simply skips that step. Under the hood the
|
||||
toggle comments the script out of that orchestrator's array in `master.conf`, which is the same
|
||||
edit you would make by hand — the toggle is just the safe way to make it.
|
||||
|
||||
Turn it back on with the same toggle. The commented line is left in place, so the step keeps its
|
||||
position in the sequence rather than being appended to the end.
|
||||
|
||||
> The button is called **Steps**, not Advanced. There is a separate **Advanced** button at the
|
||||
> top right of the panel that does something quite different — see *Advanced mode* below.
|
||||
|
||||
## Turning an orchestrator off entirely
|
||||
|
||||
Toggle the orchestrator itself off. Its cron entry stops firing and **every step inside it is
|
||||
suppressed** — an enabled step under a disabled orchestrator does not run, because the
|
||||
orchestrator is what calls it.
|
||||
|
||||
If you still want one of those scripts running while its orchestrator is off, give that step its
|
||||
own cron expression. With the orchestrator off, a step's cron field becomes live and it fires
|
||||
standalone.
|
||||
|
||||
## Running something right now
|
||||
|
||||
**Run** fires the script immediately and resets its cron timer, so the next scheduled fire is a
|
||||
full interval later rather than a few minutes away.
|
||||
|
||||
**Dry Run** passes `--dry-run`. Nothing is written to disk, and the full output is shown rather
|
||||
than a summary — with the cleanup scripts, reading the list of what *would* be removed is the
|
||||
entire point. Anything destructive offers both, and Run asks for confirmation first.
|
||||
|
||||
## Changing when something runs
|
||||
|
||||
Type into the cron field. It saves when the field loses focus, shows the schedule back to you in
|
||||
plain English, and turns red if the expression is invalid.
|
||||
|
||||
Two shortcuts worth knowing:
|
||||
|
||||
- **Suggested cron** — in the Orch tree on the right, each script shows a suggested cron badge.
|
||||
Click it to apply and save that schedule instantly.
|
||||
- **Cron Calculator** — accepts an expression or plain English, shows a description plus the next
|
||||
five fire times, and **Apply** pushes it into the cron field you last used.
|
||||
|
||||
For array events, put `array_start` or `array_stop` in the cron field instead of an expression.
|
||||
A badge appears and the script fires on Unraid's array start or stop. This works for any
|
||||
orchestrator or custom script.
|
||||
|
||||
## Finding out why something failed
|
||||
|
||||
**Log** opens that script's log in the right-hand panel. It auto-scrolls to the newest line,
|
||||
pauses when you scroll up, and resumes when you return to the bottom. **Invert** puts newest
|
||||
lines at the top. The **Search** box in the toolbar filters and highlights matches while dimming
|
||||
everything else.
|
||||
|
||||
Two blocks on the Scheduler Info panel get you there faster:
|
||||
|
||||
- **Recent Activity** — the last 24 runs. Click any row to open that log. Expands itself when
|
||||
there are errors.
|
||||
- **Recent Errors** — the most recent error per script over 7 days, so a failure that happened
|
||||
once at 3am is still visible days later.
|
||||
|
||||
The status dot in the Orch tree is green, orange or red for the last run's outcome, dim if the
|
||||
script has never run. Hover for detail.
|
||||
|
||||
## Stopping a script that is stuck
|
||||
|
||||
**Stop** sends SIGTERM, waits 3 seconds, then SIGKILL, and clears any lock files the script left
|
||||
behind.
|
||||
|
||||
Locks are never cleared automatically anywhere in Varaverk, and that is deliberate — a lock that
|
||||
looks stale may belong to a job that is still working. Stop is the explicit way to say you have
|
||||
decided otherwise.
|
||||
|
||||
## Moving a script between orchestrators
|
||||
|
||||
Use **Arrange** to drag scripts between orchestrators. Dropping one onto the right-hand panel
|
||||
removes it from its orchestrator. Nothing is written until you click **Save Arrangement**, which
|
||||
commits the new order to `master.conf`.
|
||||
|
||||
Order matters — an orchestrator runs its steps in the sequence shown.
|
||||
|
||||
## Adding your own script
|
||||
|
||||
Custom scripts live in `$CUSTOM_SCRIPTS_DIR`, outside the git repo. Any `*.sh` placed there is
|
||||
detected and listed automatically; it does not have to be registered anywhere. Being outside the
|
||||
repo means a `git pull` never touches your scripts and they are never committed by accident.
|
||||
|
||||
**+ Folder** creates a collapsible subfolder in Custom Scripts that you can drag scripts into.
|
||||
|
||||
While editing, **Cancel** discards your changes and returns to the Scheduler Info panel. The file
|
||||
on disk is never touched until you press Save.
|
||||
|
||||
---
|
||||
|
||||
## Reference — the controls on a job row
|
||||
|
||||
| Control | What it does |
|
||||
|---|---|
|
||||
| **Toggle** | Enable/disable. Saves immediately to `schedule.json` |
|
||||
| **Cron field** | Schedule. Auto-saves on focus-out; plain-English hint; red border means invalid |
|
||||
| **⚙ Cog** | Settings panel — the script's own header, matching README/Manual sections, and its config fields |
|
||||
| **Script name** | Jumps to that script's entry in the Orch tree on the right |
|
||||
| **Run** | Execute now; resets the cron timer |
|
||||
| **Dry Run** | Execute with `--dry-run`; writes nothing |
|
||||
| **Log** | Open this script's log in the right panel |
|
||||
| **Verbose** | Appends `--log` for per-item detail in the output |
|
||||
| **Steps ▸** | Expand the scripts this orchestrator calls |
|
||||
|
||||
## Reference — orchestrator and step behaviour
|
||||
|
||||
| State | Behaviour |
|
||||
|---|---|
|
||||
| Orchestrator **ON** | Sole trigger. Cron fires the orchestrator, which calls its steps in sequence |
|
||||
| Orchestrator **OFF** | Never runs automatically. Steps are suppressed; each can take its own cron |
|
||||
| Step, orchestrator ON | Toggle comments/uncomments the script in `master.conf` |
|
||||
| Step, orchestrator ON, no conf array | The orchestrator hardcodes the call — the toggle is display-only |
|
||||
| Step, orchestrator OFF | Enter a cron to run it standalone |
|
||||
| Rsync badge | Toggle writes `TIER_RSYNC_ENABLED` straight to `master.conf` |
|
||||
| Rsync, orchestrator OFF | Needs both a location and a standalone cron before it will fire independently |
|
||||
|
||||
## Reference — the Scheduler Info panel
|
||||
|
||||
The right-hand panel is the default view and everything returns to it. **← Scheduler Info** comes
|
||||
back here from any log, editor, conf form or script view.
|
||||
|
||||
- **Notification board** — how many jobs are scheduled out of the total, and what is running now.
|
||||
- **Next Runs** — what fires next, and when.
|
||||
- **Recent Activity** / **Recent Errors** — described above.
|
||||
- **Cron Calculator** — described above.
|
||||
|
||||
## Reference — Advanced mode
|
||||
|
||||
The **Advanced** button at the top right turns blue when active. It is a display and editing
|
||||
mode, unrelated to the **Steps ▸** expander on each orchestrator:
|
||||
|
||||
- The ⚙ cog switches to an enriched view — full script source, documentation and config together.
|
||||
- Raw conf editing unlocks, including direct buttons for each conf file.
|
||||
- **Git Pull** appears on the notification board, which pulls the latest scripts and runs a conf
|
||||
upgrade.
|
||||
|
||||
Raw conf editing writes the file directly. The toggles elsewhere on this page are surgical — they
|
||||
preserve the comment blocks that document every threshold — so prefer them where one exists.
|
||||
|
||||
## Reference — what this page writes
|
||||
|
||||
| File | Written by |
|
||||
|---|---|
|
||||
| `schedule.json` | Every toggle and cron field |
|
||||
| `master.conf` | Step toggles, Save Arrangement, rsync tier flags, raw conf editing |
|
||||
| `CUSTOM_SCRIPTS_DIR` | The custom script editor |
|
||||
|
||||
Cron changes take effect on the next cron rebuild. Nothing here edits the running crontab
|
||||
directly — `varaverk.cron` is regenerated from `schedule.json`.
|
||||
@@ -59,6 +59,15 @@
|
||||
// api/savefolders.php folder grouping api/reorderarray.php
|
||||
// api/rsync_standalone.php
|
||||
require_once dirname(__DIR__) . '/include/scheduler.php';
|
||||
require_once dirname(__DIR__) . '/include/docs.php';
|
||||
|
||||
// Live values for the `$VAR` markers in pages/readme/*.md. Conf variables, plus the derived
|
||||
// path constants — those are not conf keys, but they are exactly what a reader needs resolved
|
||||
// rather than described.
|
||||
$_vv_doc_vars = array_merge(vv_conf_vars(), [
|
||||
'CUSTOM_SCRIPTS_DIR' => CUSTOM_SCRIPTS_DIR,
|
||||
'SCRIPTS_DIR' => SCRIPTS_DIR,
|
||||
]);
|
||||
|
||||
// Setup mode — auto-open a conf file and force the editing sequence
|
||||
$vv_setup_conf = preg_match('/^[\w.]+\.conf$/', $_GET['vv_setup'] ?? '')
|
||||
@@ -495,38 +504,14 @@ $runningScripts = array_unique($runningScripts);
|
||||
<span class="vv-sug-chevron">▾</span>
|
||||
<span class="vv-sug-title">How do I use this</span>
|
||||
</div>
|
||||
<!-- Rendered from pages/readme/scheduler-readme.md, not maintained here. That file is
|
||||
also what the AI tab retrieves, so the panel you read and the answer the
|
||||
assistant gives are the same text and cannot drift — the same argument that
|
||||
makes this page parse script PURPOSE blocks instead of restating them. -->
|
||||
<div class="vv-sug-body vv-info-body">
|
||||
<ul class="vv-info-cols">
|
||||
<li><strong>Toggle</strong> — saves immediately to schedule.json</li>
|
||||
<li><strong>Cron field</strong> — auto-saved on focus-out; hint shows plain English; red border = invalid</li>
|
||||
<li><strong>⚙ Cog</strong> — opens settings panel: script header + matching README/Manual sections + config fields</li>
|
||||
<li><strong>Script name</strong> — click navigates to the matching entry in the Orch tree (right panel)</li>
|
||||
<li><strong>Run</strong> — fires script immediately; resets the cron timer so next fire is one full interval later</li>
|
||||
<li><strong>Dry Run</strong> — same as Run but passes <code>--dry-run</code>; no changes written to disk</li>
|
||||
<li><strong>Log</strong> — opens script log here; auto-scrolls; use Search box to filter/highlight lines</li>
|
||||
<li><strong>Stop</strong> — SIGTERM → 3 s → SIGKILL; clears stuck lock files</li>
|
||||
<li><strong>Verbose</strong> — appends <code>--log</code> flag for per-item detail output</li>
|
||||
<li><strong>Cancel</strong> — discards changes and returns here; file is never touched until Save</li>
|
||||
<li><strong>⚡ Array events</strong> — set any cron field to <code>array_start</code> or <code>array_stop</code>; badge appears; fires on Unraid array start/stop; works on any orch or custom script</li>
|
||||
<li><strong>Arrange</strong> — drag scripts between orchs; drop to right panel removes from orch; Save Arrangement commits to master.conf</li>
|
||||
<li><strong>+ Folder</strong> — collapsible subfolder in Custom Scripts; drag scripts in</li>
|
||||
<li><strong>Suggested cron</strong> — click the cron code badge in the Orch tree to apply and save instantly</li>
|
||||
<li><strong>Status dot (tree)</strong> — green/orange/red ● = last run ok/warn/error; dim = never run; hover for detail</li>
|
||||
<li><strong>Cron Calculator</strong> — type an expression or plain English; shows description + next 5 fires; Apply pushes to last-focused cron field</li>
|
||||
<li><strong>Recent Activity</strong> — last 24 runs; click a row to open that log; auto-expands on errors</li>
|
||||
<li><strong>Recent Errors</strong> — last error per script (7 days); click to open log; auto-expands on new errors</li>
|
||||
<li><strong>Advanced</strong> — top-right button, turns blue; ⚙ shows enriched view (header + docs + config); raw conf editing unlocked</li>
|
||||
<li><strong>Log search</strong> — filter box in toolbar when log is open; highlights matches, dims others</li>
|
||||
<li><strong>← Scheduler Info</strong> — returns here from any log, editor, conf, or script view</li>
|
||||
<li class="vv-info-sep">Orchestrator & Child Behaviour</li>
|
||||
<li><strong>Orch ON</strong> — sole trigger; cron fires the orch; it calls children in sequence</li>
|
||||
<li><strong>Orch OFF</strong> — never runs automatically; children suppressed; each can get its own standalone cron</li>
|
||||
<li><strong>Child (orch ON)</strong> — toggle comments/uncomments the script in master.conf</li>
|
||||
<li><strong>Child (orch ON, no array)</strong> — orch hardcodes the call; toggle is display-only</li>
|
||||
<li><strong>Child (orch OFF)</strong> — enter a cron to run it standalone</li>
|
||||
<li><strong>Rsync badge</strong> — toggle writes TIER_RSYNC_ENABLED directly to master.conf</li>
|
||||
<li><strong>Rsync (orch OFF)</strong> — fill location + standalone cron + Save; both required for independent firing</li>
|
||||
</ul>
|
||||
<div class="vv-doc">
|
||||
<?= vv_docs_render('Plugin/unraid/pages/readme/scheduler-readme.md', $_vv_doc_vars) ?>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user