Fix stale plugin docs and dead links

- unraid_api.php comment still told you to run Deployment/deploy.sh, deleted a while back - VaraverkSettings.page linked to a CHANGELOG.md that doesn't exist anywhere in the repo - Manual-Plugin.md / README-Plugin.md described manually heredoc-ing the .plg locally and a .txz-based install that isn't wired up — rewritten to describe the actual install flow (raw .plg URL via Plugins -> Install Plugin), with plugin_setup.sh's dev-symlink role called out separately from that install path
Fix dead/incorrect vars in Plugin/ found during full codebase audit
2026-07-04 23:00:57 -04:00 · 2026-07-04 23:00:26 -04:00
13 changed files with 97 additions and 88 deletions
@@ -948,6 +948,7 @@
    WEBGUI_URL="http://localhost"
    WEBGUI_TIMEOUT=5        # seconds before curl gives up on WebGUI check
    WEBGUI_NGINX_WAIT=15    # seconds after nginx restart before rechecking
+    WEBGUI_PHP_WAIT=10      # seconds after php-fpm restart before rechecking
    WEBGUI_EMHTTP_WAIT=30   # seconds after emhttp restart before rechecking

 # ==============================================================================================
@@ -943,6 +943,7 @@
    WEBGUI_URL="http://localhost"
    WEBGUI_TIMEOUT=5        # seconds before curl gives up on WebGUI check
    WEBGUI_NGINX_WAIT=15    # seconds after nginx restart before rechecking
+    WEBGUI_PHP_WAIT=10      # seconds after php-fpm restart before rechecking
    WEBGUI_EMHTTP_WAIT=30   # seconds after emhttp restart before rechecking

 # ==============================================================================================
@@ -9,26 +9,20 @@ For folder overview see `README-Plugin.md`. For web app logic see the headers in

 ## ━━━ FIRST-TIME INSTALL ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

-### Prerequisites
+Not yet published to Community Applications — this is a niche, self-hosted install for now.

- Repo cloned onto the target Unraid server
- `/boot/config/plugins/varaverk/varaverk.plg` exists on flash (see PLG SETUP below)
+### Install via the Unraid UI (the actual install path)

-### Steps
+**Plugins → Install Plugin → Enter URL of remote plugin file**, paste the raw `.plg` URL:

-```bash
-cd Plugin/
-./plugin_setup.sh
-```
+- Your own servers (Gitea): `https://git.gmer4lfe.com/FailedProxy/Varaverk/raw/branch/main/Plugin/varaverk.plg`
+- Public/anyone else (GitHub): `https://raw.githubusercontent.com/FailedProxy/Varaverk/main/Plugin/varaverk.plg`

-This creates:
-
-```
-/usr/local/emhttp/plugins/varaverk  →  Plugin/unraid/   (symlink)
-```
-
-Changes to any file under `Plugin/unraid/` take effect immediately in the browser —
-no restart, no reinstall.
+Unraid downloads the `.plg`, saves it to `/boot/config/plugins/varaverk.plg` itself
+(nothing to copy by hand), then runs its `<FILE>` steps: clones the repo onto flash
+(Gitea → Tailscale peer → `GITEA_DOMAIN` → GitHub fallback chain — same install script
+either way, so both URLs above end up in the same place), then symlinks the web files.
+See `varaverk.plg`'s inline comments for the exact clone/fallback logic.

 ### Verify

@@ -42,25 +36,13 @@ Go to **Settings → Other Settings** — a Varaverk tile should also appear the
 The `.plg` file registers Varaverk with Unraid's plugin system. It enables the cron
 mechanism (`update_cron`) and makes the plugin appear on the **Plugins** management page.

-Create it once on flash — it persists across reboots:
+`Plugin/varaverk.plg` is tracked in the repo — it's a real plugin descriptor (version,
+GitHub links, changelog) maintained by `build.sh`, not hand-authored. Normally you never
+touch flash directly — installing via the URL above (or the update button on the Plugins
+page, once installed) handles placing/refreshing `/boot/config/plugins/varaverk.plg` for you.

-```bash
-mkdir -p /boot/config/plugins/varaverk
-
-cat > /boot/config/plugins/varaverk.plg <<'EOF'
-<?xml version='1.0' standalone='yes'?>
-<!DOCTYPE PLUGIN [
-<!ENTITY name    "varaverk">
-<!ENTITY author  "gmer4lfe">
-<!ENTITY version "2026.05.28">
-]>
-<PLUGIN name="&name;" author="&author;" version="&version;" launch="varaverk/monitor" icon="/plugins/varaverk/icons/varaverk.png">
-</PLUGIN>
-EOF
-```
-
-The `.plg` has no packages and no remote URLs — it is local-only and is not published
-to Community Applications.
+`plugin_setup.sh` is a separate, optional dev convenience — see below — not part of the
+install path above.

 **Cron flow on every boot:**
 1. `event/disks_mounted/rebuild_cron` fires
@@ -71,6 +53,24 @@ to Community Applications.

 ---

+## ━━━ DEV CONVENIENCE: plugin_setup.sh ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Not part of the install path above — a manual, optional tool for pointing the running
+web server directly at an arbitrary repo clone (e.g. a dev checkout that isn't at
+`/boot/config/plugins/varaverk`), bypassing the fixed-path symlink the `.plg` recreates
+every boot.
+
+```bash
+cd Plugin/
+./plugin_setup.sh
+```
+
+This creates `/usr/local/emhttp/plugins/varaverk → Plugin/unraid/` (or `Plugin/<os>/`
+for other platforms) pointing at wherever this repo currently lives, so edits show up
+in the browser instantly. Re-run it any time the repo moves — see REPO MOVE PROCEDURE below.
+
+---
+
 ## ━━━ SCRIPTS DIRECTORY SETTING ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 `SCRIPTS_DIR` tells the plugin where to find the Configurations directory and all
@@ -104,25 +104,34 @@ CUSTOM_SCRIPTS_DIR="/boot/config/plugins/user.scripts/Varaverk/Scripts"

 ## ━━━ REPO MOVE PROCEDURE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

-If the repo is cloned to a new path:
+If a dev checkout using `plugin_setup.sh` (see above) is moved to a new path:

 1. Re-run `plugin_setup.sh` — removes the stale symlink and creates a new one pointing at the new path
 2. Update `SCRIPTS_DIR` in Settings → Other Settings → Varaverk (or edit `varaverk.cfg` directly on flash)

 The `.plg` on flash does not need to change — it has no path references.

+This doesn't apply to a normal install (via the raw `.plg` URL) — that always lives at
+the fixed path `/boot/config/plugins/varaverk`, there's no separate location to move.
+
 ---

 ## ━━━ UPDATING THE PLUGIN VERSION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

-The version in `/boot/config/plugins/varaverk.plg` is cosmetic for a local plugin —
-Unraid does not check it against anything remote. Update it when you want the Plugins
-management page to reflect when the plugin was last changed:
+`build.sh` rewrites the `version` and `sha256` entities in `Plugin/varaverk.plg` to match
+each release build — don't hand-edit them. The `sha256`/packaged `.txz` aren't currently
+consumed by anything (see the CHANGES entry in `varaverk.plg` — install is git-clone +
+symlink, not package-based), so today this is mostly cosmetic version tracking:

-```xml
-<!ENTITY version "2026.05.28">
+```bash
+cd Plugin/
+./build.sh              # today's date as version
+./build.sh 2026.09.01    # explicit version
 ```

+Commit and push. The version shown on the Plugins page updates next time Unraid
+re-fetches the `.plg` (the Plugins page's Update action, or a fresh install).
+
 ---

 ## ━━━ ADDING A NEW OS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -120,4 +120,4 @@ No other files need changing.
 | `event/disks_mounted/rebuild_cron` | Fires on every boot — copies `.plg`, rebuilds cron |
 | `event/disks_mounted/array_start_jobs` | Fires when array starts |
 | `event/disks_unmounting/array_stop_jobs` | Fires when array stops |
-| `/boot/config/plugins/varaverk.plg` | Registers the plugin with Unraid's plugin system (lives on flash, not in repo) |
+| `Plugin/varaverk.plg` | Registers the plugin with Unraid's plugin system — tracked in-repo; installed via its raw URL through Plugins → Install Plugin (see Manual-Plugin.md), which Unraid saves to `/boot/config/plugins/varaverk.plg` itself |
@@ -30,9 +30,4 @@ _(Scripts directory)_:
     style="color:#555;text-decoration:none;">
    Issues
  </a>
-  &nbsp;·&nbsp;
-  <a href="https://github.com/FailedProxy/Varaverk/blob/main/CHANGELOG.md" target="_blank"
-     style="color:#555;text-decoration:none;">
-    Changelog
-  </a>
 </div>
@@ -123,7 +123,7 @@ if [[ "$SHOW_STATUS" == true ]]; then
    echo "━━━━━ $ICON_SUMMARY WEBGUI WATCHDOG STATUS ━━━━━"
    echo "$ICON_HOST    Identity:    $MY_ID ($LOCAL_SERVER_NAME)"
    echo "$ICON_WEBGUI  URL:         $WEBGUI_URL"
-    echo "$ICON_WEBGUI  Timeouts:    curl=${WEBGUI_TIMEOUT}s nginx=${WEBGUI_NGINX_WAIT}s php=${WEBGUI_PHP_WAIT:-10}s emhttp=${WEBGUI_EMHTTP_WAIT}s"
+    echo "$ICON_WEBGUI  Timeouts:    curl=${WEBGUI_TIMEOUT}s nginx=${WEBGUI_NGINX_WAIT}s php=${WEBGUI_PHP_WAIT}s emhttp=${WEBGUI_EMHTTP_WAIT}s"
    echo ""

    if curl -sf --max-time "$WEBGUI_TIMEOUT" "$WEBGUI_URL" >/dev/null 2>&1; then
@@ -227,8 +227,8 @@ if [[ "$RECOVERY_OK" == false ]]; then
            error "php-fpm restart command failed"
        fi

-        log "Waiting ${WEBGUI_PHP_WAIT:-10}s for php-fpm to recover..."
-        sleep "${WEBGUI_PHP_WAIT:-10}"
+        log "Waiting ${WEBGUI_PHP_WAIT}s for php-fpm to recover..."
+        sleep "$WEBGUI_PHP_WAIT"

        if check_webgui; then
            RECOVERY_ACTION="php-fpm restart"
@@ -83,7 +83,8 @@ $winArrayDefs = [
    'intermediate' => ['INTERMEDIATE_MAINTENANCE_SCRIPTS', "{$myId}_INTERMEDIATE_SYNC_SHARES"],
    'daily'        => ['DAILY_MAINTENANCE_SCRIPTS',        "{$myId}_DAILY_SYNC_SHARES"],
    'weekly'       => ['WEEKLY_MAINTENANCE_SCRIPTS',       "{$myId}_WEEKLY_SYNC_SHARES"],
-    'monthly'      => ['MONTHLY_MAINTENANCE_SCRIPTS',      "{$myId}_MONTHLY_SYNC_SHARES"],
+    // monthly_maintenance.sh has no rsync section (ZFS scrub/SMART tests only) — no shares var exists.
+    'monthly'      => ['MONTHLY_MAINTENANCE_SCRIPTS',      null],
    'fallback'     => [null,                               null],
 ];
 $winArrays = [];
@@ -14,7 +14,7 @@ function vv_arr_known_hosts(): array {
 }

 function vv_arr_node_names(): array {
-    return array_map(fn($name) => $name, vv_arr_known_hosts());
+    return vv_arr_known_hosts();
 }

 // ── Discovery ─────────────────────────────────────────────────────────────────
@@ -123,9 +123,9 @@ function vv_fetch_arr_live(array $arr): array {
 // ── Log stats ─────────────────────────────────────────────────────────────────

 function vv_arr_cleanup_stats(string $type): array {
-    $slugs = ['sonarr' => 'Media/sonarr_cleanup',
-              'radarr' => 'Media/radarr_cleanup',
-              'lidarr' => 'Media/lidarr_cleanup'];
+    $slugs = ['sonarr' => 'Arrs_Stack/sonarr_cleanup',
+              'radarr' => 'Arrs_Stack/radarr_cleanup',
+              'lidarr' => 'Arrs_Stack/lidarr_cleanup'];
    $base = LOG_DIR . '/' . ($slugs[$type] ?? '');
    $out  = ['last_run' => null, 'end' => null, 'status' => null,
             'tracked'  => null, 'total' => null,
@@ -181,9 +181,9 @@ function vv_arr_cleanup_stats(string $type): array {
 }

 function vv_arr_discovery_stats(string $type): array {
-    $slugs = ['sonarr' => 'Media/playback_aware_sonarr_discovery',
-              'radarr' => 'Media/playback_aware_radarr_discovery',
-              'lidarr' => 'Media/playback_aware_lidarr_discovery'];
+    $slugs = ['sonarr' => 'Arrs_Stack/playback_aware_sonarr_discovery',
+              'radarr' => 'Arrs_Stack/playback_aware_radarr_discovery',
+              'lidarr' => 'Arrs_Stack/playback_aware_lidarr_discovery'];
    $base = LOG_DIR . '/' . ($slugs[$type] ?? '');
    $out  = ['last_run' => null, 'status' => null, 'added' => null];

@@ -225,7 +225,7 @@ function vv_arr_discovery_stats(string $type): array {
 }

 function vv_arr_sync_stats(): array {
-    $base = LOG_DIR . '/Media/arr_sync';
+    $base = LOG_DIR . '/Arrs_Stack/arr_sync';
    $out  = ['last_run' => null, 'status' => null, 'added' => null,
             'nodes'    => null, 'blocklist_count' => null];

@@ -255,7 +255,7 @@ function vv_arr_sync_stats(): array {
 }

 function vv_arr_recovery_stats(): array {
-    $base = LOG_DIR . '/Media/arrs_failed_stalled_recovery';
+    $base = LOG_DIR . '/Arrs_Stack/arrs_failed_stalled_recovery';
    $out  = ['last_run' => null, 'status' => null, 'fixed' => 0, 'searched' => 0];

    $jf = $base . '.json';
@@ -28,10 +28,11 @@ const VV_SCRIPT_CONF_SECTIONS = [
    // Media
    'Media/media_cleaner.sh'                          => ['Media Cleaner'],
    'Media/media_shares_permissions.sh'               => ['Media Permissions'],
-    'Media/arrs_failed_stalled_recovery.sh'           => ['Arr Failed/Stalled Recovery'],
-    'Media/radarr_cleanup.sh'                         => ['Arr Cleanup'],
-    'Media/lidarr_cleanup.sh'                         => ['Arr Cleanup'],
-    'Media/sonarr_cleanup.sh'                         => ['Arr Cleanup'],
+    // Arrs Stack
+    'Arrs_Stack/arrs_failed_stalled_recovery.sh'      => ['Arr Failed/Stalled Recovery'],
+    'Arrs_Stack/radarr_cleanup.sh'                    => ['Arr Cleanup'],
+    'Arrs_Stack/lidarr_cleanup.sh'                    => ['Arr Cleanup'],
+    'Arrs_Stack/sonarr_cleanup.sh'                    => ['Arr Cleanup'],
    // Monitors
    'Monitors/cert_monitor.sh'                        => ['Certificate Monitor'],
    'Monitors/backup_verify.sh'                       => ['Backup Verify'],
@@ -97,12 +97,7 @@ function vv_dk_webui(string $name, array $portMap): string {
    if (!preg_match('/<WebUI>(.*?)<\/WebUI>/s', $xml, $m)) return '';
    $url = trim($m[1]);
    if (!$url) return '';
-    static $localIp = null;
-    if ($localIp === null) {
-        $localIp = trim(shell_exec("ip route get 8.8.8.8 2>/dev/null | awk '/src/{for(i=1;i<=NF;i++)if(\$i==\"src\")print \$(i+1)}'") ?: '');
-        if (!$localIp) $localIp = gethostbyname(gethostname());
-    }
-    $url = str_replace('[IP]', $localIp, $url);
+    $url = str_replace('[IP]', vv_local_ip(), $url);
    $url = preg_replace_callback('/\[PORT:(\d+)\]/', fn($pm) => $portMap[$pm[1]] ?? $pm[1], $url);
    return $url;
 }
@@ -1,5 +1,6 @@
 <?php
 require_once __DIR__ . '/config.php';
+require_once __DIR__ . '/docker.php';

 function vv_container_webui(string $name, array $portMap): string {
    $template = '/boot/config/plugins/dockerMan/templates-user/my-' . $name . '.xml';
@@ -22,10 +23,10 @@ function vv_container_webui(string $name, array $portMap): string {
 }

 function vv_get_docker_folders(): array {
-    $folderFile = '/boot/config/plugins/folder.view3/docker.json';
-    $folderData = file_exists($folderFile)
-        ? (json_decode(@file_get_contents($folderFile), true) ?: [])
-        : [];
+    // Varaverk's own docker_folders.json is the primary store (see include/docker.php) —
+    // reading folder.view3's mirror directly here left this widget empty on any host
+    // without that optional third-party plugin installed.
+    $folderData = vv_dk_read_json();

    // One docker ps call: names, status, port mappings
    $raw = shell_exec("docker ps -a --format '{{.Names}}\t{{.Status}}\t{{.Ports}}' 2>/dev/null") ?? '';
@@ -247,7 +247,7 @@ function vv_local_host_stats(): array {

 // ── Confirmed schema (Unraid 7.3, introspected 2026-05-31) ───────────────────
 // Adding a new host: add HOSTn="hostname" to master.conf and HOSTn_UNRAID_API_KEY
-// to hostn.conf, then run Deployment/deploy.sh. No schema work needed.
+// to hostn.conf, then push and pull as usual. No schema work needed.
 //
 // If a future Unraid version renames a field, the affected function falls back
 // to local reads and the api banner lists the fallback — fix by updating the GQL.
@@ -83,7 +83,7 @@ function vv_wd_local_system(): array {
    $mem      = vv_memory_breakdown();
    $loadRaw  = @file_get_contents('/proc/loadavg') ?: '0';
    $daemonOk = (trim(shell_exec('docker info >/dev/null 2>&1; echo $?') ?: '1') === '0');
-    $oomCount = (int)trim(@file_get_contents('/tmp/system_watchdog_oom.db') ?: '0');
+    $oomCount = (int)trim(@file_get_contents(STATE_DIR . '/system_watchdog_oom.db') ?: '0');
    $cores    = (int)($sys['cpu_cores'] ?: (int)(trim(shell_exec('nproc 2>/dev/null') ?: '1')));
    return [
        'mem_total'  => (int)($mem['total_kb'] * 1024),
@@ -155,7 +155,7 @@ function vv_wd_local_states(string $restartLogPath): array {
    }

    // Growth baseline info (container count + age in seconds)
-    $growthFile     = '/tmp/watchdog_appdata_growth.db';
+    $growthFile     = STATE_DIR . '/watchdog_appdata_growth.db';
    $baselineCount  = file_exists($growthFile) ? max(0, count(file($growthFile)) - 0) : 0;
    $baselineAgeSec = file_exists($growthFile) ? time() - (int)filemtime($growthFile) : null;

@@ -187,23 +187,28 @@ function vv_wd_remote_data(string $ip, string $sshKey, string $restartLogPath):
    // /proc/meminfo is passed as a raw section (not awk-parsed) to avoid quoting
    // fragility — escapeshellarg() single-quotes the whole command so awk \$2
    // inside double-quotes is unreliable across Unraid builds.
-    $cmd = "printf 'UPTIME:%s\nLOAD:%s\nCORES:%s\nDAEMON:%s\nOOM:%s\nBASELINECOUNT:%s\nBASELINEAGE:%s\n---MEMINFO---\n%s\n---RW---\n%s\n---DOCK---\n%s\n---SKIP---\n%s\n---SYS---\n%s\n---REBOOT---\n%s\n---RESTART---\n%s\n---STORAGE---\n%s\n---NETWORK---\n%s\n' "
+    // State files live under the REMOTE's own SCRIPTS_DIR/State_Files (may differ
+    // from ours in flash mode) — resolve it once, same idiom as vv_remote_state_cmd().
+    $restartLogName = basename($restartLogPath);
+    $cmd = 'sd=$(grep -m1 SCRIPTS_DIR= /boot/config/plugins/varaverk/varaverk.cfg 2>/dev/null'
+         . ' | cut -d\'"\' -f2); sd="${sd:-/boot/config/plugins/varaverk}"; '
+        . "printf 'UPTIME:%s\nLOAD:%s\nCORES:%s\nDAEMON:%s\nOOM:%s\nBASELINECOUNT:%s\nBASELINEAGE:%s\n---MEMINFO---\n%s\n---RW---\n%s\n---DOCK---\n%s\n---SKIP---\n%s\n---SYS---\n%s\n---REBOOT---\n%s\n---RESTART---\n%s\n---STORAGE---\n%s\n---NETWORK---\n%s\n' "
        . '"$(cat /proc/uptime|cut -d\" \" -f1)" '
        . '"$(cat /proc/loadavg|cut -d\" \" -f1)" '
        . '"$(nproc)" '
        . '"$(docker info >/dev/null 2>&1 && echo ok || echo err)" '
-        . '"$(cat /tmp/system_watchdog_oom.db 2>/dev/null||echo 0)" '
-        . '"$(wc -l < /tmp/watchdog_appdata_growth.db 2>/dev/null||echo 0)" '
-        . '"$(stat -c %Y /tmp/watchdog_appdata_growth.db 2>/dev/null||echo 0)" '
+        . '"$(cat "$sd/State_Files/system_watchdog_oom.db" 2>/dev/null||echo 0)" '
+        . '"$(wc -l < "$sd/State_Files/watchdog_appdata_growth.db" 2>/dev/null||echo 0)" '
+        . '"$(stat -c %Y "$sd/State_Files/watchdog_appdata_growth.db" 2>/dev/null||echo 0)" '
        . '"$(cat /proc/meminfo 2>/dev/null)" '
-        . '"$(cat /tmp/resource_watchdog_state.db 2>/dev/null)" '
-        . '"$(cat /tmp/container_watchdog_state.db 2>/dev/null)" '
-        . '"$(cat /boot/config/system_watchdog_failed.db 2>/dev/null)" '
-        . '"$(cat /tmp/system_watchdog_state.db 2>/dev/null)" '
-        . '"$(cat /boot/config/system_watchdog_reboots.db 2>/dev/null)" '
-        . '"$(cat ' . escapeshellarg($restartLogPath) . ' 2>/dev/null)" '
-        . '"$(cat /tmp/storage_watchdog_state.db 2>/dev/null)" '
-        . '"$(cat /tmp/network_watchdog_state.db 2>/dev/null)"';
+        . '"$(cat "$sd/State_Files/resource_watchdog_state.db" 2>/dev/null)" '
+        . '"$(cat "$sd/State_Files/container_watchdog_state.db" 2>/dev/null)" '
+        . '"$(cat "$sd/State_Files/docker_watchdog_failed.db" 2>/dev/null)" '
+        . '"$(cat "$sd/State_Files/system_watchdog_state.db" 2>/dev/null)" '
+        . '"$(cat "$sd/State_Files/system_watchdog_reboots.db" 2>/dev/null)" '
+        . '"$(cat "$sd/data/' . $restartLogName . '" 2>/dev/null)" '
+        . '"$(cat "$sd/State_Files/storage_watchdog_state.db" 2>/dev/null)" '
+        . '"$(cat "$sd/State_Files/network_watchdog_state.db" 2>/dev/null)"';

    $out = vv_pt_ssh($ip, $sshKey, $cmd, 8);
    if (!$out) return null;