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

Prerequisites

• Repo cloned onto the target Unraid server
• /boot/config/plugins/varaverk/varaverk.plg exists on flash (see PLG SETUP below)

Steps

cd Plugin/
./plugin_setup.sh

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.

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.

Create it once on flash — it persists across reboots:

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.

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

---

━━━ SCRIPTS DIRECTORY SETTING ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SCRIPTS_DIR is the only plugin-level setting. It tells the plugin where to find the Configurations directory and all 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.

---

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

If the repo is cloned 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.

---

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

<!ENTITY version "2026.05.28">

---

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