82 lines
4.0 KiB
Markdown
82 lines
4.0 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.
|
|
|
|
## Current status (2025-12-11)
|
|
- Version markers and mock update status in place.
|
|
- UI has release chip + modal; buttons call real `/api/update/*`.
|
|
- API implements check/apply/rollback with staging, SHA256 verify, backup, deploy, restart, rollback.
|
|
- Release tooling: `tools/release/make-release.sh` + README; SHA256 baked into manifest.
|
|
- Missing: auto-check timer, lockfile, backup pruning, real release publishing.
|
|
|
|
## Remaining work
|
|
- Publish real release bundles + manifest to Gitea.
|
|
- Add lock around apply/check to prevent overlap.
|
|
- Add backup pruning (keep last N).
|
|
- Add systemd timer/service to run check daily and surface status.
|
|
- Optional: protect nginx/site overrides; add disk-space preflight.
|
|
|
|
## 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).
|