97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# 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`
|
||
- (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`
|
||
- (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`
|
||
- (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.
|
||
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`
|
||
6) Power down cleanly.
|
||
7) Image the SD card (DietPi Imager via QEMU or on‑device).
|
||
8) Label and archive the image (include date + profile name).
|
||
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.
|