Add installer/live/build.sh: overlay the static installer, the OpenCode manifest and the Debian tools the standard live image lacks (cryptsetup, btrfs-progs, gdisk, dosfstools, parted, util-linux-extra) onto a Debian-Live stable base, patch the boot config for a serial console, and preserve the hybrid BIOS+UEFI boot. The live squashfs is never repacked and libc is never bundled, so the appliance is unchanged and the target remains Gentoo-only. Records ADR 0005 and the implementation plan.
2.5 KiB
ADR 0005: Debian-Live installer appliance, Gentoo-only target
- Status: Accepted
- Date: 2026-09-20
Context
The installer is a statically linked Rust binary that treats the live medium as replaceable plumbing. Rebuilding a Gentoo live environment for every ISO would require compiling a distribution on a small build host, which conflicts with the "no release VPS" constraint and adds no value to the product: the live medium only has to boot, network, and provide disk/encryption/filesystem tooling.
The reference Gentoo LiveGUI medium has served this role and is kept as a fallback, but it ties the appliance to Gentoo maintenance.
Decision
The installer appliance is a Debian-Live (stable) image with the Phoebus payload overlaid, and the target remains 100% Gentoo:
- The live medium partitions, encrypts and formats the target, downloads a
verified Gentoo systemd stage3, and drives Portage inside
chroot. - The appliance's package manager, init and configuration tools are never run
against the target. Target configuration is written as Gentoo files
(
/etc/portage/*,/etc/kernel/*,/etc/fstab, ...) and executed by Gentoo tools inside the chroot. - The ISO is produced without root by leaving the Debian-Live squashfs untouched
and overlaying
/phoebus(the installer,sys, OpenCode manifest, and the Debian packages the standard image lacks). Bundling libc is forbidden; only the libraries the live image lacks are shipped. - The boot configuration is made serial-console visible and auto-booting.
Debian is chosen for a binary, boring, glibc userspace: broad tool availability, compatibility with fetched third-party binaries such as OpenCode, and a low-maintenance, automatable build. Void is a reasonable alternative (glibc, binary packages); Alpine is rejected for musl/BusyBox compatibility friction.
Consequences
- The appliance becomes replaceable plumbing; Phoebus's identity stays in the target.
- The build is a small overlay (
installer/live/build.sh) rather than a distro rebuild, and can run without root. - The live image lacks some tools, so
installer/live/tools.listpins the Debian packages to inject;--check-liveguards against drift. - Recursive-boot and Secure Boot are not verified; non-free firmware and Debian licence/attribution for the appliance are open items.
- The rootless overlay means the live filesystem's own packages are unchanged, so the appliance tracks the upstream Debian-Live image.