pi-kit/PLAN.md

Pi-Kit Updater Plan

Goals

• Add seamless in-dashboard updates for Pi-Kit assets (web UI, api script, helper scripts).
• Allow manual check/apply + rollback; optional daily auto-check with a status chip.
• Use release tarballs (not git clones) from Gitea; verify hashes; stage before swap; keep one backup.
• Keep UX friendly: clear progress, errors, and “update available” indicator.

Release Format (Gitea)

• Release asset: pikit-<version>.tar.gz containing:
  • pikit-web/ (built assets only, no node_modules)
  • pikit-api.py
  • helper scripts/configs that should overwrite
  • manifest.json (see below)
• manifest.json fields:
  • version (string)
  • changelog (url)
  • files: array of { path, sha256, mode? }
  • post_install (optional array of commands or service restarts)
• Optional: detached signature in future (ed25519), not in v1.

On-device Updater (Python helper)

• Location: /usr/local/bin/pikit-updater.py (invoked by API and timer).
• State file: /var/lib/pikit-update/state.json (latest, current, last_check, last_result, progress, backup_path).
• Steps for apply:
  1. Fetch manifest (HTTP GET release URL).
  2. Download tarball to /var/tmp/pikit-update/<version>/bundle.tar.gz.
  3. Verify SHA256 against manifest.
  4. Unpack to staging dir.
  5. Backup current managed files to /var/backups/pikit/<ts>/ (keep 1 latest).
  6. Rsync staged files to destinations:
     • /var/www/pikit-web/ (built assets)
     • /usr/local/bin/pikit-api.py
  7. Restart services: dietpi-dashboard-frontend, api service (if exists), maybe nginx reload.
  8. Update state; mark current version file /etc/pikit/version.
• Rollback: restore latest backup and restart services.
• Concurrency: use lockfile in /var/run/pikit-update.lock.

API additions (pikit-api.py)

• GET /api/update/status -> returns state.json contents + current version.
• POST /api/update/check -> fetch manifest only, update state.
• POST /api/update/apply -> spawn updater apply (can run inline for v1) and stream status.
• POST /api/update/rollback -> restore last backup.
• POST /api/update/auto -> enable/disable daily timer.

Timer

• systemd timer: pikit-update.timer/service running check daily (e.g., 04:20).
• Writes last_check and latest_version to state.

UI changes (pikit-web)

• Top-bar chip: “Updates: Up to date / Update available / Checking…”.
• New “Updates” modal (not the OS auto-updates) for Pi-Kit releases:
  • Show current vs latest version, changelog link.
  • Buttons: Check, Download & Install, Rollback, View logs.
  • Progress states + errors.
• Hook into existing status refresh: call /api/update/status.

Safety / Edge

• Preflight disk space check before download.
• Handle offline: clear message.
• If apply fails, auto rollback.
• Skip overwriting user-edited config? For v1 assume assets/api are managed; nginx site left unchanged.

Implementation steps

1. Add current version markers (maybe file in repo, read by UI).
2. Implement updater helper script with check/apply/rollback + state.
3. Add systemd service/timer units template (install script TBD, for now keep files in repo).
4. Extend pikit-api.py with new endpoints calling updater functions.
5. Extend UI (status chip + modal) and wire to API.
6. Add mock responses for dev (mock-update-status.json).
7. Test locally (mock) and on device (manual apply pointing to a dummy URL or skip download logic for now).

Open questions / assumptions

• Release hosting: use Gitea releases at https://git.44r0n.cc/44r0n7/pi-kit/releases/latest (JSON API? or static URLs). For v1, hardcode base URL env var or config.
• Services to restart: assume dietpi-dashboard-frontend and pikit-api (if we add a service file). Need to verify actual service names on device.
• Device perms: updater runs as root (via sudo from API). Ensure API endpoint requires auth (existing login).