Compare commits
No commits in common. "27795f7998e7f25fec5857aa89873a326c160471" and "8dbf6240469fe3006ec83a4a84369598501ae1cd" have entirely different histories.
27795f7998
...
8dbf624046
13 changed files with 0 additions and 621 deletions
5
.gitignore
vendored
5
.gitignore
vendored
|
|
@ -33,8 +33,3 @@ credentials
|
||||||
.idea/
|
.idea/
|
||||||
.vscode/
|
.vscode/
|
||||||
.cache/
|
.cache/
|
||||||
|
|
||||||
# Phoebus installer appliance build output and base ISO
|
|
||||||
installer/live/build/
|
|
||||||
installer/live/*.iso
|
|
||||||
installer/live/*.iso.sha256
|
|
||||||
|
|
|
||||||
|
|
@ -20,7 +20,6 @@ exact implementation/verification matrix and known limitations.
|
||||||
```
|
```
|
||||||
AGENTS.md entry point for AI/human contributors (read first)
|
AGENTS.md entry point for AI/human contributors (read first)
|
||||||
docs/ objectives, roadmap, status, architecture, process
|
docs/ objectives, roadmap, status, architecture, process
|
||||||
installer/live/ Debian-Live installer appliance ISO recipe
|
|
||||||
installer/tests/vm/ disposable UEFI VM harness (static Rust binary)
|
installer/tests/vm/ disposable UEFI VM harness (static Rust binary)
|
||||||
installer-rs/ production Rust installer (crates/ workspace)
|
installer-rs/ production Rust installer (crates/ workspace)
|
||||||
scripts/ git/dev tooling (hooks, publish, agent-commit)
|
scripts/ git/dev tooling (hooks, publish, agent-commit)
|
||||||
|
|
|
||||||
|
|
@ -8,11 +8,6 @@ Format: Keep a Changelog. Dates are UTC.
|
||||||
## Unreleased
|
## Unreleased
|
||||||
|
|
||||||
### Added
|
### Added
|
||||||
- **Debian-Live installer appliance** (`installer/live/build.sh`, no root): a
|
|
||||||
bootable Phoebus installer ISO built by overlaying the static installer, the
|
|
||||||
OpenCode manifest and the Debian tools the live image lacks onto a Debian-Live
|
|
||||||
stable base, with a serial-visible auto-booting grub config. The target stays
|
|
||||||
Gentoo. See `docs/PLAN-DEBIAN-LIVE.md` and ADR 0005.
|
|
||||||
- Git workflow: committed hooks (`.githooks/`), `scripts/check-secrets.sh`,
|
- Git workflow: committed hooks (`.githooks/`), `scripts/check-secrets.sh`,
|
||||||
`scripts/agent-commit.sh`, `scripts/publish.sh`, `scripts/setup-hooks.sh`.
|
`scripts/agent-commit.sh`, `scripts/publish.sh`, `scripts/setup-hooks.sh`.
|
||||||
- Documentation set: `docs/OBJECTIVES.md`, `ROADMAP.md`, `STATUS.md`,
|
- Documentation set: `docs/OBJECTIVES.md`, `ROADMAP.md`, `STATUS.md`,
|
||||||
|
|
|
||||||
|
|
@ -1,271 +0,0 @@
|
||||||
# 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**
|
|
||||||
|
|
||||||
```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.
|
|
||||||
|
|
@ -282,47 +282,6 @@ binhost URI from the selected profile when it is not set. Signature
|
||||||
verification remains enabled. Publishing a matching systemd/desktop binhost is
|
verification remains enabled. Publishing a matching systemd/desktop binhost is
|
||||||
the remaining step; no time estimate is claimed beyond the recorded ~26 min.
|
the remaining step; no time estimate is claimed beyond the recorded ~26 min.
|
||||||
|
|
||||||
## Debian-Live installer appliance (actual ISO)
|
|
||||||
|
|
||||||
An appliance ISO was built **without root** by `installer/live/build.sh`
|
|
||||||
(Debian-Live 13.7 standard base + `/phoebus` overlay), SHA-256
|
|
||||||
`c0105bc9a282fddcbefab42baa577ea99843060f00fa45a75bcbc8358186bfd5`.
|
|
||||||
|
|
||||||
Firmware boot (UEFI/OVMF, no `-kernel`; the ISO's own grub chain):
|
|
||||||
|
|
||||||
- auto-boots the live system on the serial console;
|
|
||||||
- login `user` / `live` (passwordless sudo);
|
|
||||||
- the overlaid tools run: `cryptsetup 2.7.5`, `sgdisk 1.0.10`,
|
|
||||||
`partprobe 3.6`, `mkfs.btrfs 6.14`, `mkfs.fat`.
|
|
||||||
|
|
||||||
Full install to a fresh 24 GiB qcow2 driven from the appliance:
|
|
||||||
|
|
||||||
- `INSTALL_RC=0`, all stages, `NO_SECRET_LEAK`.
|
|
||||||
|
|
||||||
Detached boot of the installed disk (ISO removed):
|
|
||||||
|
|
||||||
- systemd-boot -> LUKS2 unlock -> `phoebus` login;
|
|
||||||
- `systemctl is-system-running` -> `running`; `0 loaded units listed`;
|
|
||||||
- **Gentoo-only**: `Gentoo Base System release 2.18`, Portage 3.0.82.2,
|
|
||||||
`no-apt`; systemd PID 1;
|
|
||||||
- `cryptroot` Btrfs mounted at `/`, `/home`, `/var`, `/.snapshots`, `/swap`,
|
|
||||||
ESP `/efi`.
|
|
||||||
|
|
||||||
This is Bash-free and Gentoo-target-only: the appliance contributes tooling,
|
|
||||||
never configuration.
|
|
||||||
|
|
||||||
### Open items found in this run
|
|
||||||
|
|
||||||
- The target came up with the default `gentoo` hostname (empty
|
|
||||||
`/etc/hostname`) even though the plan/config specified `phoebus`, unlike the
|
|
||||||
earlier Gentoo-appliance installs. Needs a focused look (possible stage3 or
|
|
||||||
ordering difference).
|
|
||||||
- The first detached boot reported `enp0s2 DOWN`; DHCP timing was not
|
|
||||||
re-checked. The earlier Gentoo-appliance boot had `enp0s2 UP 10.0.2.15/24`.
|
|
||||||
|
|
||||||
Neither affects the proven Gentoo-appliance boot path; both are recorded rather
|
|
||||||
than hidden.
|
|
||||||
|
|
||||||
## Known remaining work
|
## Known remaining work
|
||||||
|
|
||||||
- The graphical session was verified with the **headless** wlroots backend
|
- The graphical session was verified with the **headless** wlroots backend
|
||||||
|
|
|
||||||
|
|
@ -1,50 +0,0 @@
|
||||||
# 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.
|
|
||||||
|
|
@ -1,68 +0,0 @@
|
||||||
# Phoebus installer appliance (Debian-Live base)
|
|
||||||
|
|
||||||
Builds the bootable Phoebus installer ISO. The **appliance is Debian**, the
|
|
||||||
**installed system is Gentoo**: the live medium only partitions, encrypts and
|
|
||||||
formats the target, downloads a verified Gentoo stage3, and drives Portage
|
|
||||||
inside a `chroot`. Nothing from the appliance is installed; it disappears at
|
|
||||||
reboot.
|
|
||||||
|
|
||||||
Design decisions: `docs/PLAN-DEBIAN-LIVE.md` and `docs/adr/0005-debian-live-appliance.md`.
|
|
||||||
|
|
||||||
## No-root remaster
|
|
||||||
|
|
||||||
The script does **not** repack the live squashfs (that would destroy ownership
|
|
||||||
and setuid bits without root). Instead it leaves the Debian-Live filesystem
|
|
||||||
untouched and overlays a `/phoebus` directory onto the ISO:
|
|
||||||
|
|
||||||
```
|
|
||||||
/phoebus/
|
|
||||||
bin/phoebus-installer static Rust installer
|
|
||||||
bin/sys static typed system broker
|
|
||||||
bin/phoebus launcher: stages to /tmp, sets PATH/LD_LIBRARY_PATH
|
|
||||||
tools/ Debian packages the live image lacks
|
|
||||||
(cryptsetup, btrfs-progs, gdisk, dosfstools,
|
|
||||||
parted, util-linux-extra)
|
|
||||||
opencode.manifest
|
|
||||||
README
|
|
||||||
```
|
|
||||||
|
|
||||||
The launcher copies `/phoebus` to `/tmp/phoebus-payload` and prepends the
|
|
||||||
bundled `usr/sbin`/`usr/bin` to `PATH`, so the installer finds `cryptsetup`,
|
|
||||||
`sgdisk`, `partprobe`, `mkfs.fat` and `mkfs.btrfs`. Only the libraries the live
|
|
||||||
image lacks are bundled (never libc), so the live system's own tools are not
|
|
||||||
shadowed.
|
|
||||||
|
|
||||||
## Build
|
|
||||||
|
|
||||||
Prerequisites: `xorriso`, `mksquashfs`, `curl`, `dpkg-deb`, and the static
|
|
||||||
installer built first:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cd installer-rs
|
|
||||||
RUSTFLAGS="-C target-feature=+crt-static" \
|
|
||||||
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
|
|
||||||
```
|
|
||||||
|
|
||||||
Then:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
installer/live/build.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Output: `installer/live/phoebus-installer-amd64.iso` (+ `.sha256`). The base
|
|
||||||
Debian-Live ISO is downloaded to the repo root if absent and verified against
|
|
||||||
`base.sha256`. These artifacts are gitignored.
|
|
||||||
|
|
||||||
## Use
|
|
||||||
|
|
||||||
Boot the ISO (UEFI or BIOS). It auto-boots a serial-visible live system; log in
|
|
||||||
as `user` / `live` (passwordless sudo). Then:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
/run/live/medium/phoebus/bin/phoebus --help
|
|
||||||
sudo /run/live/medium/phoebus/bin/phoebus --config FILE --install --yes \
|
|
||||||
--luks-passphrase-file /secure/luks.pw --user-password-file /secure/user.pw
|
|
||||||
```
|
|
||||||
|
|
||||||
Secrets are only ever supplied as 0600 files. The live user's `/tmp` is the
|
|
||||||
staging area; the medium itself is read-only.
|
|
||||||
|
|
@ -1 +0,0 @@
|
||||||
040a44f35186321eb6cdaab52a8a2d06224fe6b77f6fbb9f1861ad89c14e17ec debian-live-13.7.0-amd64-standard.iso
|
|
||||||
|
|
@ -1,128 +0,0 @@
|
||||||
#!/usr/bin/env bash
|
|
||||||
# Build the Phoebus installer appliance ISO on a Debian-Live base.
|
|
||||||
#
|
|
||||||
# The live squashfs is left untouched (repacking it without root would destroy
|
|
||||||
# ownership and setuid bits). Instead the installer and the tools the live
|
|
||||||
# image lacks are overlaid as /phoebus, and the boot config is made
|
|
||||||
# serial-friendly. See README.md and docs/PLAN-DEBIAN-LIVE.md.
|
|
||||||
#
|
|
||||||
# Requirements: xorriso, curl, dpkg-deb, and a static installer build.
|
|
||||||
# No root.
|
|
||||||
set -euo pipefail
|
|
||||||
|
|
||||||
here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
root="$(cd "$here/../.." && pwd)"
|
|
||||||
work="${WORKDIR:-$here/build}"
|
|
||||||
out="${OUT:-$here/phoebus-installer-amd64.iso}"
|
|
||||||
base="${BASE_ISO:-$root/debian-live-standard.iso}"
|
|
||||||
|
|
||||||
base_url="https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-13.7.0-amd64-standard.iso"
|
|
||||||
base_sha="$(awk '{print $1}' "$here/base.sha256")"
|
|
||||||
target="x86_64-unknown-linux-gnu"
|
|
||||||
release_dir="$root/installer-rs/target/$target/release"
|
|
||||||
|
|
||||||
tools=()
|
|
||||||
while IFS= read -r line; do
|
|
||||||
[[ -z "$line" || "$line" == \#* ]] && continue
|
|
||||||
tools+=("$line")
|
|
||||||
done < "$here/tools.list"
|
|
||||||
|
|
||||||
say() { printf '\n== %s ==\n' "$*"; }
|
|
||||||
|
|
||||||
say "preflight"
|
|
||||||
for c in xorriso curl dpkg-deb; do
|
|
||||||
command -v "$c" >/dev/null || { echo "missing tool: $c" >&2; exit 1; }
|
|
||||||
done
|
|
||||||
for b in phoebus-installer sys; do
|
|
||||||
[[ -x "$release_dir/$b" ]] || {
|
|
||||||
echo "missing $release_dir/$b; build it first:" >&2
|
|
||||||
echo " cd installer-rs && RUSTFLAGS=\"-C target-feature=+crt-static\" \\" >&2
|
|
||||||
echo " cargo build --release -p phoebus-installer --target $target" >&2
|
|
||||||
exit 1
|
|
||||||
}
|
|
||||||
done
|
|
||||||
|
|
||||||
say "base ISO"
|
|
||||||
if [[ ! -f "$base" ]]; then
|
|
||||||
echo "downloading $base_url"
|
|
||||||
curl -fL --retry 3 -o "$base" "$base_url"
|
|
||||||
fi
|
|
||||||
echo "$base_sha $base" | sha256sum -c - >/dev/null || { echo "base ISO checksum mismatch" >&2; exit 1; }
|
|
||||||
echo "base OK: $base"
|
|
||||||
|
|
||||||
say "fetch Debian tool packages"
|
|
||||||
apt_dir="$work/apt"
|
|
||||||
debs="$work/debs"
|
|
||||||
payload="$work/payload"
|
|
||||||
rm -rf "$work"
|
|
||||||
mkdir -p "$apt_dir"/{etc/apt/sources.list.d,var/lib/apt/lists/partial,var/cache/apt/archives/partial,var/lib/dpkg} \
|
|
||||||
"$debs" "$payload/bin" "$payload/tools"
|
|
||||||
: > "$apt_dir/var/lib/dpkg/status"
|
|
||||||
printf 'deb http://deb.debian.org/debian trixie main\n' > "$apt_dir/etc/apt/sources.list"
|
|
||||||
|
|
||||||
keyring_deb="$work/debian-archive-keyring.deb"
|
|
||||||
curl -fsS -o "$keyring_deb" \
|
|
||||||
"https://deb.debian.org/debian/pool/main/d/debian-archive-keyring/debian-archive-keyring_2025.1_all.deb"
|
|
||||||
dpkg-deb -x "$keyring_deb" "$work/keyring"
|
|
||||||
key="$work/keyring/usr/share/keyrings/debian-archive-keyring.gpg"
|
|
||||||
apt-get -o Dir="$apt_dir" -o Dir::Etc::trusted="$key" -o APT::Get::List-Cleanup=0 \
|
|
||||||
-o Acquire::Languages=none update >/dev/null
|
|
||||||
( cd "$debs" && apt-get -o Dir="$apt_dir" -o Dir::Etc::trusted="$key" \
|
|
||||||
-o Dir::Cache::archives="$debs" -y --no-install-recommends --download-only \
|
|
||||||
install "${tools[@]}" >/dev/null )
|
|
||||||
echo "fetched $(ls "$debs"/*.deb | wc -l) packages"
|
|
||||||
|
|
||||||
say "assemble payload"
|
|
||||||
cp "$here/payload/README" "$payload/README"
|
|
||||||
install -m 0755 "$here/payload/bin/phoebus" "$payload/bin/phoebus"
|
|
||||||
install -m 0755 "$here/payload/bin/phoebus-sys" "$payload/bin/phoebus-sys"
|
|
||||||
install -m 0755 "$release_dir/phoebus-installer" "$payload/bin/phoebus-installer"
|
|
||||||
install -m 0755 "$release_dir/sys" "$payload/bin/sys"
|
|
||||||
cp "$root/installer-rs/crates/phoebus-installer/resources/opencode.manifest" "$payload/opencode.manifest"
|
|
||||||
for d in "$debs"/*.deb; do dpkg-deb -x "$d" "$payload/tools"; done
|
|
||||||
chmod -R u+rwX "$payload/tools" 2>/dev/null || true
|
|
||||||
|
|
||||||
# Keep only libraries the live image lacks. Bundling libc would shadow the
|
|
||||||
# live system's own libc (and break its tools) via LD_LIBRARY_PATH.
|
|
||||||
libdir="$payload/tools/usr/lib/x86_64-linux-gnu"
|
|
||||||
if [[ -d "$libdir" ]]; then
|
|
||||||
( cd "$libdir" && for f in *; do
|
|
||||||
case "$f" in
|
|
||||||
libcryptsetup.so.12*|libparted.so.2*|liblzo2.so.2*|libaudit.so.1*|libreiserfscore.so.0*) : ;;
|
|
||||||
engines-3|ossl-modules) : ;;
|
|
||||||
*) rm -rf "$f" ;;
|
|
||||||
esac
|
|
||||||
done )
|
|
||||||
fi
|
|
||||||
for t in cryptsetup sgdisk partprobe mkfs.fat mkfs.btrfs btrfs; do
|
|
||||||
find "$payload/tools" -type f -name "$t" | grep -q . || { echo "payload missing $t" >&2; exit 1; }
|
|
||||||
done
|
|
||||||
echo "payload ready"
|
|
||||||
|
|
||||||
say "patch boot config for serial console"
|
|
||||||
bootcfg="$work/bootcfg"; mkdir -p "$bootcfg"
|
|
||||||
xorriso -osirrox on -indev "$base" \
|
|
||||||
-extract /boot/grub/grub.cfg "$bootcfg/grub.cfg" \
|
|
||||||
-extract /boot/grub/config.cfg "$bootcfg/config.cfg" >/dev/null 2>&1
|
|
||||||
chmod u+w "$bootcfg/grub.cfg" "$bootcfg/config.cfg"
|
|
||||||
sed -i 's#boot=live components quiet splash findiso=#boot=live components console=ttyS0,115200 findiso=#' "$bootcfg/grub.cfg"
|
|
||||||
python3 - "$bootcfg/config.cfg" <<'PY'
|
|
||||||
import sys
|
|
||||||
p = sys.argv[1]
|
|
||||||
t = open(p).read()
|
|
||||||
t = t.replace("set default=0\n",
|
|
||||||
"set default=0\nset timeout=5\nserial --unit=0 --speed=115200\n"
|
|
||||||
"terminal_input console serial\nterminal_output console serial\n", 1)
|
|
||||||
t = t.replace("terminal_output gfxterm", "terminal_output gfxterm serial")
|
|
||||||
open(p, "w").write(t)
|
|
||||||
PY
|
|
||||||
|
|
||||||
say "assemble ISO"
|
|
||||||
rm -f "$out"
|
|
||||||
xorriso -indev "$base" -outdev "$out" \
|
|
||||||
-map "$payload" /phoebus \
|
|
||||||
-map "$bootcfg/grub.cfg" /boot/grub/grub.cfg \
|
|
||||||
-map "$bootcfg/config.cfg" /boot/grub/config.cfg \
|
|
||||||
-boot_image any keep >/dev/null
|
|
||||||
sha256sum "$out" | tee "$out.sha256"
|
|
||||||
ls -lh "$out"
|
|
||||||
|
|
@ -1,14 +0,0 @@
|
||||||
Phoebus installer appliance (Debian-Live based, Gentoo target)
|
|
||||||
|
|
||||||
Run the installer with:
|
|
||||||
/run/live/medium/phoebus/bin/phoebus --help
|
|
||||||
|
|
||||||
The launcher stages the payload to /tmp and puts the bundled disk,
|
|
||||||
encryption and filesystem tools (cryptsetup, btrfs-progs, gdisk,
|
|
||||||
dosfstools, parted) on PATH. The installed system is Gentoo; this live
|
|
||||||
medium is only the installer appliance and disappears at reboot.
|
|
||||||
|
|
||||||
Secrets are supplied as 0600 files:
|
|
||||||
phoebus --config FILE --install --yes \
|
|
||||||
--luks-passphrase-file /secure/luks.pw \
|
|
||||||
--user-password-file /secure/user.pw
|
|
||||||
|
|
@ -1,15 +0,0 @@
|
||||||
#!/bin/sh
|
|
||||||
# Phoebus installer launcher (Debian-Live appliance).
|
|
||||||
#
|
|
||||||
# Stages the payload to a writable, executable location, puts the bundled
|
|
||||||
# disk/encryption/filesystem tools on PATH, and runs the static installer.
|
|
||||||
set -eu
|
|
||||||
here="$(cd "$(dirname "$0")/.." && pwd)"
|
|
||||||
stage="${TMPDIR:-/tmp}/phoebus-payload"
|
|
||||||
if [ ! -x "$stage/bin/phoebus-installer" ]; then
|
|
||||||
mkdir -p "$stage"
|
|
||||||
cp -a "$here/." "$stage/"
|
|
||||||
fi
|
|
||||||
export PATH="$stage/tools/usr/sbin:$stage/tools/usr/bin:$stage/bin:$PATH"
|
|
||||||
export LD_LIBRARY_PATH="$stage/tools/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
|
|
||||||
exec "$stage/bin/phoebus-installer" "$@"
|
|
||||||
|
|
@ -1,12 +0,0 @@
|
||||||
#!/bin/sh
|
|
||||||
# Phoebus `sys` launcher (Debian-Live appliance).
|
|
||||||
set -eu
|
|
||||||
here="$(cd "$(dirname "$0")/.." && pwd)"
|
|
||||||
stage="${TMPDIR:-/tmp}/phoebus-payload"
|
|
||||||
if [ ! -x "$stage/bin/sys" ]; then
|
|
||||||
mkdir -p "$stage"
|
|
||||||
cp -a "$here/." "$stage/"
|
|
||||||
fi
|
|
||||||
export PATH="$stage/tools/usr/sbin:$stage/tools/usr/bin:$stage/bin:$PATH"
|
|
||||||
export LD_LIBRARY_PATH="$stage/tools/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
|
|
||||||
exec "$stage/bin/sys" "$@"
|
|
||||||
|
|
@ -1,10 +0,0 @@
|
||||||
# Debian tools the live appliance needs but the standard image lacks.
|
|
||||||
# The installer only invokes these host-side; everything target-side
|
|
||||||
# (emerge, bootctl, kernel-install, systemctl, getuto) comes from the
|
|
||||||
# Gentoo stage3 inside the chroot.
|
|
||||||
cryptsetup
|
|
||||||
btrfs-progs
|
|
||||||
gdisk
|
|
||||||
dosfstools
|
|
||||||
parted
|
|
||||||
util-linux-extra
|
|
||||||
Loading…
Add table
Reference in a new issue