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
This commit is contained in:
Gmer4Lfe
2026-07-04 23:00:57 -04:00
parent f7fa75fdfb
commit 7e4db7b504
4 changed files with 51 additions and 47 deletions
+49 -40
View File
@@ -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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1 -1
View File
@@ -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 |
-5
View File
@@ -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>
+1 -1
View File
@@ -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.