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.
269 lines
11 KiB
Markdown
269 lines
11 KiB
Markdown
# 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)
|
|
|
|
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**
|
|
|
|
```sh
|
|
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**
|
|
|
|
```sh
|
|
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**
|
|
|
|
```sh
|
|
# 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**
|
|
|
|
```sh
|
|
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**
|
|
|
|
```sh
|
|
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.
|