pi-kit/pikit-prep-spec.md

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.

---