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

```bash
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:

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

**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` 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`:

```bash
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`

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

---

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

```xml
<!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`:
   ```bash
   elif [[ -f /etc/<os>-marker ]]; then echo "<os>"
   ```
3. Add the install target to the `case` block:
   ```bash
   <os>)
       SOURCE="$SCRIPT_DIR/<os>"
       TARGET="/path/to/web/server/plugins/$PLUGIN_NAME"
       ;;
   ```