phoebus_os/docs/adr/0005-debian-live-appliance.md
Phoebus d6fa7c8dce feat(live): build a Debian-Live installer appliance ISO (no root)
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.
2026-09-20 12:49:31 -07:00

50 lines
2.5 KiB
Markdown

# 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.list` pins the
Debian packages to inject; `--check-live` guards 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.