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.
11 KiB
Plan: Debian-Live installer appliance, Gentoo-only target
Status: In progress · Author: session 2026-09-20 · Companion:
docs/adr/0005-debian-live-appliance.md
Progress: an actual ISO now builds with installer/live/build.sh (no root),
firmware-boots (UEFI), presents a serial console, and runs the static installer
from the live medium. A full install from the appliance reached the Portage
stage; the detached-boot verification is the remaining gate. See
docs/VM-BOOT-VERIFICATION.md.
This plan replaces the reference Gentoo LiveGUI medium as the installer appliance with a Debian-Live image, while keeping the installed system 100% Gentoo. The live medium is replaceable plumbing; Phoebus's identity lives in the target.
1. Goal and non-goals
Goal. A reproducible, low-maintenance "Phoebus installer" ISO whose only jobs are: boot reliably on UEFI (and, where possible, legacy) hardware, bring up networking, provide disk/encryption/filesystem tooling, run the static Rust installer, and bootstrap a Gentoo target. The appliance disappears at reboot.
Non-goals.
- Do not make Debian part of the installed system. Nothing from the appliance is copied into the target except the target image it downloads/stages.
- Do not configure Gentoo using Debian tools. After the stage3 is extracted,
all configuration is written as Gentoo files and executed via
chroot+ Portage (emerge,bootctl,kernel-install,systemctl,getuto). - Do not rebuild a Gentoo live environment on the build VPS.
- Do not weaken LUKS2, Btrfs, systemd, UEFI, package signature verification, or the proven BLS boot path.
2. Hard rules (override any "move fast" instruction)
- Live ≠ target. The appliance's package manager, init and config tools
must never run against the target root. Target writes go through
TargetRoot; target commands go throughchrootinto the Gentoo tree. - The Rust installer stays static (
+crt-static). The live libc must not be a dependency of the installer binary. glibc is still required to run fetched third-party binaries such as OpenCode. - Never log or transmit secrets. API keys, LUKS passphrases and passwords stay in 0600 files; no secrets in the ISO, the build logs, or the model context.
- Signature verification stays on (
binrepos.conf verify-signature = true; stage3 pinned SHA-256 or signed DIGESTS). No global~amd64. - Verification is executed evidence. A phase is
VERIFIEDonly when its verification command ran and its raw result is recorded. "It compiles" is not evidence. - Never point
DISKat/dev/*. All destructive tests run on a disposable qcow2 in the VM harness. - The ISO is not a source artifact. Build output and the ISO stay gitignored; only the recipe is tracked.
3. Target architecture
Debian-Live appliance ISO (built by installer/live/, tracked as a recipe)
| boots UEFI; brings up network; provides tools below
v
phoebus-installer (static Rust binary; unchanged interface)
| --check-live (new preflight)
v
partition / LUKS2 / Btrfs / mount target (live tools)
|
v
download verified Gentoo systemd stage3 (curl + SHA-256)
|
v
extract into target (tar)
|
v
write Gentoo config; chroot; emerge kernel/desktop (Portage, target-side)
|
v
systemd-boot + BLS; reboot; appliance is gone; target is Gentoo
4. Live appliance prerequisites (derived from the executor)
These are the only host-side programs the installer invokes. Everything else
(emerge, bootctl, kernel-install, systemctl, getuto, gpg) runs
inside the target chroot and comes from stage3/Portage.
| Purpose | Programs (from code) | Debian package |
|---|---|---|
| Partitioning | sgdisk, partprobe, wipefs, blkid, udevadm |
gdisk, util-linux, udev |
| Filesystems | mkfs.fat, mkfs.btrfs, btrfs, mkswap, truncate, chattr |
dosfstools, btrfs-progs, util-linux, e2fsprogs |
| Encryption | cryptsetup |
cryptsetup |
| Mounting | mount, umount, chroot |
util-linux |
| Probing | lsblk, lspci, lsusb |
util-linux, pciutils, usbutils |
| Fetch/verify | curl, tar, xz, zstd, openssl |
curl, tar, xz-utils, zstd, openssl |
| Certificates | CA bundle | ca-certificates |
| Networking | NetworkManager or dhcp | network-manager, iproute2 |
| Optional | mokutil, systemd-cryptenroll, gpg, opencode |
mokutil, systemd, gnupg |
The list is checked in code (--check-live), not only in prose, so the recipe
and the installer cannot drift.
5. Phases
Work the lowest-numbered phase whose exit gate is not VERIFIED. Each task
records its verification and commits separately.
Phase 0 — Preserve and instrument
- Tag the current Gentoo-live state:
git tag -a v0.2.0-gentoo-live -m "Gentoo LiveGUI appliance reference". - Record the current appliance/proven-boot evidence location
(
docs/VM-BOOT-VERIFICATION.md) and the exact harness boot args. - Add a
livemodule inphoebus-corewithREQUIRED_LIVE_TOOLS(the table above) andOPTIONAL_LIVE_TOOLS, as pure data. - Add a failing
--check-livecoverage test (the flag does not exist yet).
Verification
git tag --list 'v0.2.0-gentoo-live'
cd installer-rs && cargo test -p phoebus-core live
cargo test -p phoebus-installer --test cli_coverage
Exit gate: the tag exists and the live data module has unit tests.
Phase 1 — --check-live preflight (works on any appliance)
phoebus-executor::live::check(exec) -> LiveReportusingfind_in_path, separating required-missing (fatal) from optional-missing (warning).phoebus-installer --check-live: print the roster and exit non-zero if a required tool is missing; never mutate anything.- Add
--check-livetotests/cli_coverage.rs. - Run the installer's own preflight at the start of
--installso a broken appliance fails before partitioning.
Verification
cargo test --workspace
./target/debug/phoebus-installer --check-live # on the dev host
./target/debug/phoebus-installer --config test.conf --dry-run --install
Exit gate: --check-live reports correctly on the dev host and the test
suite is green.
Phase 2 — Boot-agnostic VM harness
- Extend
installer/tests/vm/serial-driver.pyandrun-vm.shto accept an appliance descriptor: either the current-kernel/-initrd+ append (Gentoo) or extraction of a Debian-Live kernel/initrd (/live/vmlinuz,/live/initrd.img) with aboot=live console=ttyS0append. - Keep the Gentoo path working (do not regress the proven boot path).
- Document the two modes in
installer/tests/vm/README.md.
Verification
# Gentoo reference still installs (regression):
python3 installer/tests/vm/serial-driver.py install # existing config
Exit gate: the existing Gentoo appliance still installs and boots through the refactored harness.
Phase 3 — Debian-Live build recipe (build host required)
- Add
installer/live/: -build.sh—lb config+lb buildwrapper with pinned distribution (bookworm), UEFI+BIOS hybrid,console=ttyS0, a live user, and the package list. -config/package-lists/phoebus.list.chroot— the Phase 0 tool set plus firmware and networking. -config/hooks/live/*.hook.chroot— copy the static installer, the pinned OpenCode manifest, and a recovery helper readme into the image. -overlay/— small files (motd, recovery notes); no secrets. -verify.sh—phoebus-release manifest+verifyon the ISO. - Add
liveoutput to.gitignore(installer/live/*.iso,build/). - Document prerequisites (
live-build,debootstrap, root or apodman/docker/distroboxcontainer) indocs/DEVELOPMENT.md.
Verification
cd installer/live && ./build.sh && ./verify.sh
Exit gate: a Phoebus-installer ISO builds reproducibly and its manifest
verifies. (Blocked if no host with live-build/debootstrap is available;
record the blocker and the exact command.)
Phase 4 — VM verification of the Debian appliance
- Boot the Debian appliance in the disposable VM (Phase 2 harness).
phoebus-installer --check-livepasses inside the appliance.- Full encrypted UEFI install to a fresh qcow2; detached boot; record
LUKS unlock, login,
systemctl is-system-running = running,0 failed units,NO_SECRET_LEAKindocs/VM-BOOT-VERIFICATION.md. - Prove the target is Gentoo-only: in the booted target, confirm
emerge --version,/etc/gentoo-release, and the absence ofapt/Debian config in the target.
Verification
python3 installer/tests/vm/serial-driver.py install # Debian appliance
python3 installer/tests/vm/serial-driver.py boot
Exit gate: the detached boot evidence exists and matches the Gentoo-live baseline.
Phase 5 — Adopt and document
- Make the Debian appliance the recommended/default in docs; keep the Gentoo-live recipe as a documented fallback until Phase 4 is verified.
- Update
README.md,docs/ARCHITECTURE.md,docs/DEVELOPMENT.md,docs/FINDINGS.md,docs/ROADMAP.md,docs/STATUS.md,docs/CHANGELOG.md,docs/HANDOFF.md. - Add ADR 0005 (
docs/adr/0005-debian-live-appliance.md). - Include Debian's licence/attribution in the ISO payload metadata.
Exit gate: no tracked doc references the Gentoo LiveGUI as the appliance,
and make test is green.
Phase 6 — Release automation and recovery (later)
phoebus-release: alivesubcommand that builds the manifest from the ISO and refuses to publish without a passing verification.- Biweekly scheduled build + VM smoke test + atomic publish (roadmap 14).
- Promote the appliance into the recovery environment (roadmap 15): network, LUKS open/close, Btrfs mount, Portage/kernel repair helpers.
6. Risks and decisions to settle
- Secure Boot. The appliance's boot chain is unsigned and unverified. Record it as unverified rather than implying support.
- Non-free firmware. Decide whether the appliance carries non-free firmware for real hardware; Debian-Live makes this a config choice.
- Licensing/redistribution. A Debian-based ISO must carry Debian's licences and attribution; this is a distribution obligation, not an afterthought.
- Networking. NetworkManager vs
dhcpcdon the appliance; the installer only needs a working route and DNS. - Live auto-login. The appliance runs as a live user; secrets still come from 0600 files supplied at install time. Confirm no secret is baked in.
--check-livecompleteness. Keep the required list derived from code so a new executor program adds a check.- Build host.
live-build/debootstrapare not installed on the current dev host; the recipe should also run in a container.
7. Definition of done
The appliance role is complete when: a Debian-Live ISO builds reproducibly from
a tracked recipe; the VM harness boots it; --check-live passes; a full
encrypted install + detached boot is recorded; the target is demonstrably
Gentoo-only; and the docs, changelog and handoff state exactly what was
verified and what was not.