pi-kit/docs/workflow.md

Pi-Kit Image Workflow

This documents the current workflow and the target workflow once profiles + first‑boot automation are implemented. It is meant to be a practical, repeatable checklist.

0) Keep a golden base image (do this first)

1. Boot the known‑good base Pi.
2. Verify core services:
   • Nginx + Pi‑Kit dashboard
   • DietPi dashboard
3. Update the system if needed.
4. Run the prep scrub + verify:
   • sudo ./pikit-prep.sh
   • ./pikit-smoke-test.sh
   • (optional) sudo ./pikit-prep.sh --check-only
5. Image the SD card with DietPi Imager.
6. Store it as the golden base (e.g., images/base/pikit-base-YYYYMMDD.img.xz).

1) Build a profile image (current/manual workflow)

1. Identify the SD card:
   • lsblk
2. Flash the golden base image to SD:
   • sudo ./flash_sd.sh qemu-dietpi/shared/base.img.xz /dev/sdX
3. Boot the Pi and install/configure services manually.
   • Avoid port 80/443 (Pi‑Kit already uses those).
4. Add dashboard services using the UI (Add Service modal).
5. Open any needed ports in ufw (done as part of testing/config):
   • sudo ufw allow from <LAN subnet> to any port <port>
6. Run the prep scrub + verify:
   • sudo ./pikit-prep.sh
   • ./pikit-smoke-test.sh
   • (optional) sudo ./pikit-prep.sh --check-only
7. Image the SD card via the QEMU DietPi VM:
   • Insert the SD card into your desktop.
   • Identify it with lsblk.
   • Start QEMU with passthrough:
     • ./qemu-dietpi/run-dietpi.sh /dev/sdX
   • SSH in:
     • ssh -i qemu-dietpi/ssh/id_ed25519 -p 2222 root@localhost
   • In the VM, go to the shared mount and run DietPi Imager:
     • cd /mnt/images
     • dietpi-imager
   • After imaging, shut down the VM:
     • shutdown
8. Store the image as the profile name (e.g., images/profiles/dns-stack.img.xz).

2) Build a profile image (target workflow with profiles + first‑boot)

1. Flash the golden base image to SD.
2. Boot the Pi and install/configure services manually.
3. Create or export the profile file locally: profiles/<name>/profile.json.
   • Includes additional services and firewall ports only.
   • Planned: export a profile from the running Pi (services + ufw) to avoid manual edits.
4. Apply the profile to the Pi (planned script, optional if already configured):
   • Writes /etc/pikit/profile.json (for first‑boot).
   • Merges services into /etc/pikit/services.json (idempotent).
5. Run the drift check (planned script):
   • Confirms services + ports match the profile + base.
6. Run the prep scrub + verify:
   • sudo ./pikit-prep.sh
   • ./pikit-smoke-test.sh
   • (optional) sudo ./pikit-prep.sh --check-only
7. Image the SD card with DietPi Imager.

First boot on the end‑user device will:

• Regenerate unique identity + TLS certs.
• Ensure the profile’s firewall ports are open (LAN‑only).
• Show a progress overlay until complete.

Optional: to skip the first‑boot update step for faster startup, create /etc/pikit/firstboot.conf with:

PIKIT_FIRSTBOOT_UPDATES=0

3) Flashing an image to SD

Use the helper:

• sudo ./flash_sd.sh <image.img.xz> /dev/sdX

4) Manufacturing / imaging checklist (production)

1. Start from the golden base image (stored in images/base/).
2. Flash it to a known‑good SD card.
3. Boot and verify:
   • http://pikit.local and https://pikit.local
   • dashboard loads
   • first‑boot completes
4. Apply any required profile/services.
5. Run prep + verify:
   • sudo ./pikit-prep.sh
   • ./pikit-smoke-test.sh
6. Power down cleanly.
7. Image the SD card (DietPi Imager via QEMU or on‑device).
8. Name and archive the image:
   • Base: images/base/pikit-base-YYYYMMDD-dietpi9.20.1.img.xz
   • Profile: images/profiles/pikit-<profile>-YYYYMMDD.img.xz
   • Testing/staging: images/staging/pikit-<profile>-YYYYMMDD-rcN.img.xz
9. Smoke test the flashed image on a second SD card:
   • boot → first‑boot → dashboard → services

Notes

• Profiles are additive to the base image defaults; do not include Pi‑Kit or DietPi dashboard entries in profiles.
• Keep RESCUE.md in /root and /home/dietpi only (not in /var/www).
• Prep enforces a password change for dietpi on first login; set PIKIT_FORCE_PASSWORD_CHANGE=0 to skip.
• After the password change, a one‑time SSH hardening tip is shown on login.
• End-user defaults: OS security unattended upgrades on; Pi-Kit updater auto-check on stable channel, auto-apply off (user can change in dashboard).