bible/rules/patterns/alpine-livecd/contract.md

Contract: Alpine LiveCD Build

Version: 1.0

Purpose

Rules for building bootable Alpine Linux ISO images with custom overlays using mkimage.sh. Applies to any project that needs a LiveCD: hardware audit, rescue environments, kiosks.

See README.md for detailed examples and build snippets.

Rules

• Every project must have mkimg.<name>.sh.
• arch is mandatory in the mkimage profile. If it is missing, mkimage.sh may exit 0 without building anything.
• The apkovl generator genapkovl-<name>.sh must be present in the current working directory when mkimage.sh runs.
• ~/.mkimage/ is for mkimg profiles only. Do not assume mkimage will find genapkovl there.
• Run builds in /var/tmp, not /tmp. LiveCD builds often exceed typical /tmp tmpfs size.
• Preserve expensive mkimage cache sections between builds when possible. Regenerate the apkovl section every build.
• For RAM-loaded modloops, prefer faster squashfs settings such as lz4 unless the project explicitly optimizes for smallest ISO size.
• Long builds must run in a resilient session (screen, tmux, or equivalent) so SSH disconnects do not kill the build.
• linux-firmware-none alone is not sufficient for real hardware targets. Include firmware packages matching the expected NIC/storage hardware.
• Pin all build-critical versions in one shared versions file sourced by the build scripts. Do not hardcode versions inline in multiple scripts.