Varaverk/Plugin/README-Plugin.md

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

🔌 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 platform adapter + plugin application
    ├── adapter.sh             # Platform adapter — provides platform_*() API to all scripts
    ├── 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

# Future platform adapters follow the same structure:
# Plugin/truenas/adapter.sh   — TrueNAS adapter (future)
# Plugin/ubuntu/adapter.sh    — Ubuntu/Debian adapter (future)

---

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

---

━━━ THE PLATFORM ADAPTER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Plugin/unraid/adapter.sh is the Unraid platform adapter. It is sourced automatically by load_config.sh whenever PLATFORM=unraid is detected (via /etc/unraid-version).

Every bash script in the ecosystem calls platform_*() functions instead of OS-specific commands directly. The adapter translates those calls into Unraid-specific implementations.

platform_storage_healthy          # is the array up and shfs mounted?
platform_is_maintenance_running   # parity check or sync in progress?
platform_is_service_running       # is a named service process alive?
platform_restart_service          # restart via rc.d (Unraid) or systemctl (future)
platform_stop_service             # stop a named service
platform_is_mover_running         # Unraid mover active?
platform_get_mover_pid            # PID of the mover process
platform_stop_user_scripts        # kill Unraid user.scripts background jobs
platform_send_os_notification     # dynamix notify (Unraid) or equivalent
platform_get_disk_states          # reads disks.ini (Unraid) or equivalent
platform_get_temp_thresholds      # reads dynamix.cfg (Unraid) or equivalent
platform_is_service_enabled       # docker.cfg / domain.cfg enabled check
platform_require_cmd              # verify a platform command exists

Adding a new platform: Create Plugin/<platform>/adapter.sh implementing the same function names. load_config.sh detects the OS at runtime and sources the correct adapter. No other files need changing.

---

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