From 7e4db7b50427c28bff304cdbd4f70e5c9e6ab07f Mon Sep 17 00:00:00 2001 From: Gmer4Lfe Date: Sat, 4 Jul 2026 23:00:57 -0400 Subject: [PATCH] Fix stale plugin docs and dead links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- Plugin/Manual-Plugin.md | 89 +++++++++++++++------------- Plugin/README-Plugin.md | 2 +- Plugin/unraid/VaraverkSettings.page | 5 -- Plugin/unraid/include/unraid_api.php | 2 +- 4 files changed, 51 insertions(+), 47 deletions(-) diff --git a/Plugin/Manual-Plugin.md b/Plugin/Manual-Plugin.md index 33dcf79..a9e2a62 100644 --- a/Plugin/Manual-Plugin.md +++ b/Plugin/Manual-Plugin.md @@ -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 `` 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' - - - - -]> - - -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//` +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 - +```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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ diff --git a/Plugin/README-Plugin.md b/Plugin/README-Plugin.md index 8ea1fef..0199cde 100644 --- a/Plugin/README-Plugin.md +++ b/Plugin/README-Plugin.md @@ -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 | diff --git a/Plugin/unraid/VaraverkSettings.page b/Plugin/unraid/VaraverkSettings.page index 8daa9d9..0ca9695 100644 --- a/Plugin/unraid/VaraverkSettings.page +++ b/Plugin/unraid/VaraverkSettings.page @@ -30,9 +30,4 @@ _(Scripts directory)_: style="color:#555;text-decoration:none;"> Issues -  ·  - - Changelog - diff --git a/Plugin/unraid/include/unraid_api.php b/Plugin/unraid/include/unraid_api.php index 28d1a3d..8cc1bd1 100644 --- a/Plugin/unraid/include/unraid_api.php +++ b/Plugin/unraid/include/unraid_api.php @@ -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.