Varaverk/Plugin/Manual-Plugin.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔌 PLUGIN — Manual

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Setup procedures, deployment steps, and operational reference. For folder overview see README-Plugin.md. For web app logic see the headers in unraid/include/.

---

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

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

Install via the Unraid UI (the actual install path)

Plugins → Install Plugin → Enter URL of remote plugin file, paste the raw .plg URL:

• 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

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

Navigate to the Unraid web UI. Varaverk should appear in the Tasks menu. Go to Settings → Other Settings — a Varaverk tile should also appear there.

---

━━━ PLG SETUP ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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.

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.

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
2. Copies varaverk.plg to /var/log/plugins/
3. Calls vv_cron_rebuild() → writes varaverk.cron → calls update_cron
4. Unraid merges varaverk.cron into /etc/cron.d/root
5. crond picks up all Varaverk jobs

---

━━━ 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.

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 repo scripts.

Set it via: Settings → Other Settings → Varaverk → Scripts directory

Default: /boot/config/plugins/varaverk

The value is stored in /boot/config/plugins/varaverk/varaverk.cfg:

SCRIPTS_DIR="/boot/config/plugins/varaverk"

All other configuration lives in Configurations/master.conf and Configurations/host*.conf.

CUSTOM_SCRIPTS_DIR is a separate, optional override for where the Scheduler tab's Custom Scripts feature reads/writes user-authored scripts (see Manual.md → Custom Scripts). It's intentionally not under SCRIPTS_DIR — Custom Scripts are personal, non-repo tooling and must never end up inside the git-tracked plugin folder.

Default: /boot/config/plugins/user.scripts/Varaverk/Scripts

# in varaverk.cfg, alongside SCRIPTS_DIR
CUSTOM_SCRIPTS_DIR="/boot/config/plugins/user.scripts/Varaverk/Scripts"

---

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

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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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:

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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

plugin_setup.sh is built to support multiple OS targets. To add one:

1. Create Plugin/<os>/ with the OS-appropriate web app files
2. Add the OS marker to detect_os() in plugin_setup.sh:

   elif [[ -f /etc/<os>-marker ]]; then echo "<os>"
   

3. Add the install target to the case block:

   <os>)
       SOURCE="$SCRIPT_DIR/<os>"
       TARGET="/path/to/web/server/plugins/$PLUGIN_NAME"
       ;;