# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🔌  PLUGIN
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**The Varaverk Unraid plugin — a web UI that wraps the entire script ecosystem.**
Scheduler, Monitor, Docker management, Partnership sync, Fallback state, and Arrs —
all surfaced inside the Unraid web interface as a first-class plugin.

> **Why this folder exists:** The scripts need a control surface. Managing a 50+ container
> homelab ecosystem from terminal windows is friction. The plugin turns configuration files
> into editable forms, cron schedules into a visual scheduler, and runtime log output into
> a live dashboard — without duplicating any of the logic that already lives in common.sh
> and the conf files.

---

## ━━━ THE PROBLEM THAT BUILT THIS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The script ecosystem works well from the command line, but day-to-day operation is not
the command line. Checking whether the nightly sync ran, adjusting a container's watchdog
limit, confirming the partnership fallback is active — all of that requires SSH sessions,
knowing which log files to look at, and remembering which conf variable controls what.

The plugin solves the visibility problem: one URL on any browser, on any device on the
Tailscale network, shows everything running and lets you act on it. No extra tooling,
no separate monitoring stack, no third-party dashboards.

---

## ━━━ WHAT THIS FOLDER CONTAINS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

```
Plugin/
├── dev_install.sh             # One-time developer setup: symlinks plugin into web server
├── Icons/                     # Source icon assets (1024px master files)
└── unraid/                    # The Unraid plugin application
    ├── Varaverk.page          # Main plugin entry point (Tasks menu)
    ├── VaraverkSettings.page  # Unraid Settings → Other Settings entry
    ├── api/                   # PHP API endpoints (called by JS via fetch)
    ├── css/                   # Plugin stylesheet
    ├── event/                 # Unraid event hooks (boot-time cron setup, array lifecycle)
    ├── icons/                 # Plugin icons served by emhttp
    ├── images/                # Plugin images
    ├── include/               # PHP business logic shared across pages
    ├── js/                    # Frontend JavaScript
    ├── pages/                 # Per-tab page includes (monitor, scheduler, docker, ...)
    └── run_job.sh             # Script runner invoked by the Scheduler
```

---

## ━━━ RELATIONSHIP TO THE REST OF THE REPO ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Plugin is a wrapper, never a reimplementation.** Every setting the plugin reads or writes
lives in `Configurations/master.conf` or `Configurations/host*.conf` — the same files the
shell scripts read. The plugin has no separate data store. If a conf file changes outside
the plugin (by hand, by SSH), the plugin reflects it on next load.

The one exception is `varaverk.cfg` on flash (`/boot/config/plugins/varaverk/varaverk.cfg`),
which holds a single bootstrap value: `SCRIPTS_DIR`. This is the path the plugin uses to
find the Configurations directory and all scripts. Everything else flows from there.

The plugin also taps `common.sh` indirectly — `include/config.php` mirrors
`resolve_tailscale_ip()` and `detect_host()` exactly, using the same logic as common.sh
so behaviour stays consistent without a shell dependency.

---

## ━━━ SCRIPTS IN THIS FOLDER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Script | Role | When It Runs |
|--------|------|--------------|
| `dev_install.sh` | Symlinks `Plugin/unraid/` into Unraid's web server | Once, manually, after cloning or moving the repo |

---

## ━━━ UNRAID INTEGRATION POINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| File | Where it appears in Unraid |
|------|---------------------------|
| `Varaverk.page` | Tasks menu item |
| `VaraverkSettings.page` | Settings → Other Settings tile |
| `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) |