Add dashboard UI updates and settings modal
This commit is contained in:
Aaron
391
pikit-prep-spec.md
Normal file
391
pikit-prep-spec.md
Normal file
@@ -0,0 +1,391 @@
|
||||
# Pi-Kit DietPi Image Prep Spec
|
||||
|
||||
This file defines how to design a **prep script** for a DietPi-based Pi-Kit image.
|
||||
|
||||
The script’s job:
|
||||
Prepare a running Pi-Kit system to be cloned as a “golden image” **without** removing any intentional software, configs, hostname, or passwords.
|
||||
|
||||
---
|
||||
|
||||
## 0. Context & Goals
|
||||
|
||||
**Starting point**
|
||||
|
||||
- OS: DietPi (Debian-based), already installed.
|
||||
- Extra software: web stack, Pi-Kit dashboard, DNS/ad-blocker, DBs, monitoring, etc.
|
||||
- System has been used for testing (logs, histories, test data, junk).
|
||||
|
||||
**Goal**
|
||||
|
||||
- Prepare system for cloning as a product image.
|
||||
- **KEEP**:
|
||||
- All intentionally installed packages/software.
|
||||
- All custom configs (web, apps, DietPi configs, firewall).
|
||||
- Current hostname.
|
||||
- Existing passwords (system + services) as shipped defaults.
|
||||
- **RESET/CLEAR**:
|
||||
- Host-unique identity data (machine-id, SSH host keys, etc.).
|
||||
- Logs, histories, caches.
|
||||
- Test/personal accounts and data.
|
||||
|
||||
---
|
||||
|
||||
## 1. Discovery Phase (MUST HAPPEN BEFORE SCRIPT DESIGN)
|
||||
|
||||
Before writing any code, inspect the system and external docs.
|
||||
|
||||
The AI MUST:
|
||||
|
||||
1. **Detect installed components**
|
||||
- Determine which key packages/services are present, e.g.:
|
||||
- Web server (nginx, lighttpd, apache2, etc.).
|
||||
- DNS/ad-blocker (Pi-hole or similar).
|
||||
- DB engines (MariaDB, PostgreSQL, SQLite usage).
|
||||
- Monitoring/metrics (Netdata, Uptime Kuma, etc.).
|
||||
- Use this to decide which cleanup sections apply.
|
||||
|
||||
2. **Verify paths/layouts**
|
||||
- For each service or category:
|
||||
- Confirm relevant paths/directories actually exist.
|
||||
- Do not assume standard paths without checking.
|
||||
- Example: Only treat `/var/log/nginx` as Nginx logs if:
|
||||
- Nginx is installed, AND
|
||||
- That directory exists.
|
||||
|
||||
3. **Consult upstream docs (online)**
|
||||
- Check current:
|
||||
- DietPi docs and/or DietPi GitHub.
|
||||
- Docs for major services (e.g. Pi-hole, Nginx, MariaDB, etc.).
|
||||
- Use docs to confirm:
|
||||
- Data vs config locations.
|
||||
- Safe cache/log cleanup methods.
|
||||
- Prefer documented behavior over guesses.
|
||||
|
||||
4. **Classify actions**
|
||||
- For each potential cleanup:
|
||||
- Mark as **safe** if clearly understood and documented.
|
||||
- Mark as **uncertain** if layout deviates or docs are unclear.
|
||||
- Plan to:
|
||||
- Perform safe actions.
|
||||
- Skip uncertain actions and surface them for manual review.
|
||||
|
||||
5. **Fail safe**
|
||||
- If something doesn’t match expectations:
|
||||
- Do NOT plan a destructive operation on it.
|
||||
- Flag it as “needs manual review” in the confirmation phase.
|
||||
|
||||
---
|
||||
|
||||
## 2. Identity & Host-Specific Secrets
|
||||
|
||||
**DO NOT CHANGE:**
|
||||
|
||||
- Hostname (whatever it currently is).
|
||||
- Any existing passwords (system or service-level) that are part of the appliance defaults.
|
||||
|
||||
**RESET/CLEAR:**
|
||||
|
||||
1. **Machine identity**
|
||||
- Clear:
|
||||
- `/etc/machine-id`
|
||||
- `/var/lib/dbus/machine-id` (if present)
|
||||
- Rely on OS to recreate them on next boot.
|
||||
|
||||
2. **Random seed**
|
||||
- Clear persisted random seed (e.g. `/var/lib/systemd/random-seed`) so each clone gets unique entropy.
|
||||
|
||||
3. **SSH host keys**
|
||||
- Remove all SSH **host key** files (server keys only).
|
||||
- Leave user SSH keypairs unless explicitly identified as dev/test and safe to remove.
|
||||
|
||||
4. **SSH known_hosts**
|
||||
- Clear `known_hosts` for:
|
||||
- `root`
|
||||
- `dietpi` (or primary DietPi user)
|
||||
- Any other persistent users
|
||||
|
||||
5. **VPN keys (conditional)**
|
||||
- If keys are meant to be unique per device:
|
||||
- Remove WireGuard/OpenVPN private keys and per-device configs embedding them.
|
||||
- If the design requires fixed server keys:
|
||||
- KEEP server keys.
|
||||
- REMOVE test/client keys/profiles that are tied to dev use.
|
||||
|
||||
6. **TLS certificates (conditional)**
|
||||
- REMOVE:
|
||||
- Let’s Encrypt/ACME certs tied to personal domains.
|
||||
- Per-device self-signed certs that should regenerate.
|
||||
- KEEP:
|
||||
- Shared CAs/certs only if explicitly part of product design.
|
||||
|
||||
---
|
||||
|
||||
## 3. Users & Personal Traces
|
||||
|
||||
1. **Accounts**
|
||||
- KEEP:
|
||||
- Accounts that are part of the product.
|
||||
- REMOVE:
|
||||
- Test-only accounts (users created for dev/debug).
|
||||
|
||||
2. **Shell histories**
|
||||
- Clear shell histories for all remaining users:
|
||||
- `root`, `dietpi`, others that stay.
|
||||
|
||||
3. **Home directories**
|
||||
- For users that remain:
|
||||
- KEEP:
|
||||
- Intentional config/dotfiles (shell rc, app config, etc.).
|
||||
- REMOVE:
|
||||
- Downloads, random files, scratch notes.
|
||||
- Editor backup/swap files, stray temp files.
|
||||
- Debug dumps, one-off scripts not part of product.
|
||||
- For users that are removed:
|
||||
- Delete their home dirs entirely.
|
||||
|
||||
4. **SSH client keys**
|
||||
- REMOVE:
|
||||
- Clearly personal/test keys (e.g. with your email in comments).
|
||||
- KEEP:
|
||||
- Only keys explicitly required by product design.
|
||||
|
||||
---
|
||||
|
||||
## 4. Logs & Telemetry
|
||||
|
||||
1. **System logs**
|
||||
- Clear:
|
||||
- Systemd journal (persistent logs).
|
||||
- `/var/log` files + rotated/compressed variants, where safe.
|
||||
|
||||
2. **Service logs**
|
||||
- For installed services (web servers, DNS/ad-blockers, DBs, etc.):
|
||||
- Clear their log files and rotated versions.
|
||||
|
||||
3. **Monitoring/metrics**
|
||||
- For tools like Netdata, Uptime Kuma, etc.:
|
||||
- KEEP:
|
||||
- Config, target definitions.
|
||||
- CLEAR:
|
||||
- Historical metric/alert data (TSDBs, history files, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 5. Package Manager & Caches
|
||||
|
||||
1. **APT**
|
||||
- Clear:
|
||||
- Downloaded `.deb` archives.
|
||||
- Safe APT caches (as per documentation).
|
||||
|
||||
2. **Other caches**
|
||||
- Under `/var/cache` and `~/.cache`:
|
||||
- CLEAR:
|
||||
- Caches known to be safe and auto-regenerated.
|
||||
- DO NOT CLEAR:
|
||||
- Caches that are required for correct functioning or very expensive to rebuild, unless docs confirm safety.
|
||||
|
||||
3. **Temp directories**
|
||||
- Empty:
|
||||
- `/tmp`
|
||||
- `/var/tmp`
|
||||
|
||||
4. **Crash dumps**
|
||||
- Remove crash dumps and core files (e.g. `/var/crash` and similar locations).
|
||||
|
||||
---
|
||||
|
||||
## 6. Service Data vs Config (Per-App Logic)
|
||||
|
||||
General rule:
|
||||
|
||||
> Keep configuration & structure. Remove dev/test data, history, and personal content.
|
||||
|
||||
The AI must apply this using detected services + docs.
|
||||
|
||||
### 6.1 Web Servers (nginx / lighttpd / apache2)
|
||||
|
||||
- KEEP:
|
||||
- Main config and site configs that define Pi-Kit behavior.
|
||||
- App code in `/var/www/...` (or equivalent Pi-Kit web root).
|
||||
- CLEAR:
|
||||
- Access/error logs.
|
||||
- Non-critical caches if docs confirm they’re safe to recreate.
|
||||
|
||||
### 6.2 DNS / Ad-blockers (Pi-hole or similar)
|
||||
|
||||
- KEEP:
|
||||
- Upstream DNS settings.
|
||||
- Blocklists / adlists / local DNS overrides.
|
||||
- DHCP config if it is part of the product’s behavior.
|
||||
- CLEAR:
|
||||
- Query history / statistics DB.
|
||||
- Log files.
|
||||
- DO NOT:
|
||||
- Change the current admin password (it is the product default).
|
||||
|
||||
### 6.3 Databases (MariaDB, PostgreSQL, SQLite, etc.)
|
||||
|
||||
- KEEP:
|
||||
- DB schema.
|
||||
- Seed/default data required for every user.
|
||||
- REMOVE/RESET:
|
||||
- Dev/test user accounts (with your email, etc.).
|
||||
- Test content/records not meant for production image.
|
||||
- Access tokens, session records, API keys tied to dev use.
|
||||
- For SQLite-based apps:
|
||||
- Decide per app (based on docs) whether to:
|
||||
- Ship a pre-seeded “clean” DB, OR
|
||||
- Let it auto-create DB on first run.
|
||||
|
||||
### 6.4 Other services (Nextcloud, Jellyfin, Gotify, Uptime Kuma, etc.)
|
||||
|
||||
For each detected service:
|
||||
|
||||
- KEEP:
|
||||
- Global config, ports, base URLs, application settings needed for Pi-Kit.
|
||||
- CLEAR:
|
||||
- Personal/dev user accounts.
|
||||
- Your media/content (unless intentionally shipping sample content).
|
||||
- Notification endpoints tied to your own email / Gotify / Telegram, unless explicitly desired.
|
||||
|
||||
If docs or structure are unclear, mark cleanup as **uncertain** and surface in confirmation instead of guessing.
|
||||
|
||||
---
|
||||
|
||||
## 7. Networking & Firewall
|
||||
|
||||
**HARD CONSTRAINTS:**
|
||||
|
||||
- Do NOT modify hostname.
|
||||
- Do NOT weaken/remove the product firewall rules.
|
||||
|
||||
1. **Firewall**
|
||||
- Detect firewall system in use (iptables, nftables, UFW, etc.).
|
||||
- KEEP:
|
||||
- All persistent firewall configs that define Pi-Kit’s security behavior.
|
||||
- DO NOT:
|
||||
- Flush or reset firewall rules unless it’s clearly a dev-only configuration (and that’s confirmed).
|
||||
|
||||
2. **Other networking state**
|
||||
- Safe to CLEAR:
|
||||
- DHCP lease files.
|
||||
- DNS caches.
|
||||
- DO NOT ALTER:
|
||||
- Static IP/bridge/VLAN config that appears to be part of the intended appliance setup.
|
||||
|
||||
---
|
||||
|
||||
## 8. DietPi-Specific State & First-Boot Behavior
|
||||
|
||||
1. **DietPi automation/config**
|
||||
- Identify DietPi automation configuration (e.g. `dietpi.txt`, related files).
|
||||
- KEEP:
|
||||
- The intended defaults (locale, timezone, etc.).
|
||||
- Any automation that is part of Pi-Kit behavior.
|
||||
- AVOID:
|
||||
- Re-triggering DietPi’s generic first-boot flow unless that is intentionally desired.
|
||||
|
||||
2. **DietPi logs/temp**
|
||||
- CLEAR:
|
||||
- DietPi-specific logs and temp files.
|
||||
- KEEP:
|
||||
- All DietPi configuration and automation files.
|
||||
|
||||
3. **Pi-Kit first-boot logic**
|
||||
- Ensure any Pi-Kit specific first-run services/hooks are:
|
||||
- Enabled.
|
||||
- Not dependent on data being cleaned (e.g., they must not require removed dev tokens/paths).
|
||||
|
||||
---
|
||||
|
||||
## 9. Shell & Tooling State
|
||||
|
||||
1. **Tool caches**
|
||||
- For root and main user(s), CLEAR:
|
||||
- Safe caches in `~/.cache` (pip, npm, cargo, etc.), if not needed at runtime.
|
||||
- Avoid clearing caches that are critical or painful to rebuild unless doc-backed.
|
||||
|
||||
2. **Build artifacts**
|
||||
- REMOVE:
|
||||
- Source trees, build directories, and other dev artifacts that are not part of final product.
|
||||
|
||||
3. **Cronjobs / timers**
|
||||
- Audit:
|
||||
- User crontabs.
|
||||
- System crontabs.
|
||||
- Systemd timers.
|
||||
- KEEP:
|
||||
- Jobs that are part of Pi-Kit behavior.
|
||||
- REMOVE:
|
||||
- Jobs/timers clearly used for dev/testing only.
|
||||
|
||||
---
|
||||
|
||||
## 10. Implementation Requirements (For the Future Script)
|
||||
|
||||
When generating the actual script, the AI MUST:
|
||||
|
||||
1. **Error handling**
|
||||
- Check exit statuses where relevant.
|
||||
- Handle missing paths/directories gracefully:
|
||||
- If a path doesn’t exist, skip and log; do not fail hard.
|
||||
- Avoid wide-destructive operations without validation:
|
||||
- No “blind” deletions on unverified globs.
|
||||
|
||||
2. **Idempotency**
|
||||
- Script can run multiple times without progressively breaking the system.
|
||||
- After repeated runs, image should remain valid and “clean”.
|
||||
|
||||
3. **Conservative behavior**
|
||||
- If uncertain about an operation:
|
||||
- Do NOT perform it.
|
||||
- Log a warning and mark for manual review.
|
||||
|
||||
4. **Logging**
|
||||
- For each major category (identity, logs, caches, per-service cleanup, etc.):
|
||||
- Log what was targeted and outcome:
|
||||
- `cleaned`
|
||||
- `skipped (not installed/not found)`
|
||||
- `skipped (uncertain; manual review)`
|
||||
- Provide a summary at the end.
|
||||
|
||||
---
|
||||
|
||||
## 11. Mandatory Pre-Script Confirmation Step
|
||||
|
||||
**Before writing any script, the AI MUST:**
|
||||
|
||||
1. **Present a system-specific plan**
|
||||
- Based on discovery + docs, list:
|
||||
- Exactly which paths, files, DBs, and data types it intends to:
|
||||
- Remove
|
||||
- Reset
|
||||
- Leave untouched
|
||||
- For each item or group: a short explanation of **why**.
|
||||
|
||||
2. **Highlight conflicts / ambiguities**
|
||||
- If any cleanup might:
|
||||
- Affect passwords,
|
||||
- Affect hostname,
|
||||
- Affect firewall rules,
|
||||
- Or contradict this spec in any way,
|
||||
- The AI must:
|
||||
- Call it out explicitly.
|
||||
- Explain tradeoffs and propose a safe option.
|
||||
|
||||
3. **Highlight extra opportunities**
|
||||
- If the AI finds additional cleanup opportunities not explicitly listed here (e.g., new DietPi features, new log paths):
|
||||
- Describe them clearly.
|
||||
- Explain pros/cons of adding them.
|
||||
- Ask whether to include them.
|
||||
|
||||
4. **Wait for explicit approval**
|
||||
- Do NOT generate the script until:
|
||||
- The user (me) has reviewed the plan.
|
||||
- Conflicts and extra opportunities have been discussed.
|
||||
- Explicit approval (with any modifications) has been given.
|
||||
|
||||
Only after that confirmation may the AI produce the actual prep script.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user