phoebus_os/docs/PLAN-DEBIAN-LIVE.md
Phoebus 27795f7998
Some checks are pending
ci / test (push) Waiting to run
docs(live): record the Debian-Live appliance install and detached boot
The appliance ISO firmware-boots, installs (INSTALL_RC=0, NO_SECRET_LEAK) and
the installed disk boots detached as Gentoo-only (Portage, no apt, systemd
running, 0 failed units). Two anomalies are recorded rather than hidden: the
target hostname and a first-boot DHCP timing observation.
2026-09-20 13:49:49 -07:00

12 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, runs the static installer from the live medium, completes a full install (INSTALL_RC=0, all stages, NO_SECRET_LEAK), and the installed disk boots detached as a Gentoo-only system (running, 0 failed units). Remaining: the --check-live preflight (Phase 1), a reproducible in-repo ISO build check, and two open anomalies (target hostname and DHCP timing) noted in 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)

  1. 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 through chroot into the Gentoo tree.
  2. 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.
  3. 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.
  4. Signature verification stays on (binrepos.conf verify-signature = true; stage3 pinned SHA-256 or signed DIGESTS). No global ~amd64.
  5. Verification is executed evidence. A phase is VERIFIED only when its verification command ran and its raw result is recorded. "It compiles" is not evidence.
  6. Never point DISK at /dev/*. All destructive tests run on a disposable qcow2 in the VM harness.
  7. 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 live module in phoebus-core with REQUIRED_LIVE_TOOLS (the table above) and OPTIONAL_LIVE_TOOLS, as pure data.
  • Add a failing --check-live coverage 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) -> LiveReport using find_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-live to tests/cli_coverage.rs.
  • Run the installer's own preflight at the start of --install so 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.py and run-vm.sh to 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 a boot=live console=ttyS0 append.
  • 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 build wrapper 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 + verify on the ISO.
  • Add live output to .gitignore (installer/live/*.iso, build/).
  • Document prerequisites (live-build, debootstrap, root or a podman/docker/distrobox container) in docs/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-live passes 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_LEAK in docs/VM-BOOT-VERIFICATION.md.
  • Prove the target is Gentoo-only: in the booted target, confirm emerge --version, /etc/gentoo-release, and the absence of apt/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: a live subcommand 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 dhcpcd on 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-live completeness. Keep the required list derived from code so a new executor program adds a check.
  • Build host. live-build/debootstrap are 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.