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.

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

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

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