78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# 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).
|
|
|