docs: specify Gentoo image builder and guarded installer
This commit is contained in:
Codex
@@ -0,0 +1,73 @@
|
|||||||
|
# HydraOS Gentoo Image Implementation Plan
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans. Checkboxes track implementation.
|
||||||
|
|
||||||
|
**Goal:** Produce and boot-test an installable Gentoo-based HydraOS ISO.
|
||||||
|
|
||||||
|
**Architecture:** Verified stage3 and pinned Portage feed an isolated builder. A prepared rootfs provides both live image and installer payload. Dracut/SquashFS/GRUB make the ISO; a guarded installer applies it only to explicitly selected disks.
|
||||||
|
|
||||||
|
**Tech Stack:** Gentoo systemd amd64 stage3, Portage/binhost, Podman rootless, dracut, GRUB EFI, SquashFS, Python3, shell.
|
||||||
|
|
||||||
|
**Spec:** ../specs/2026-10-13-gentoo-image-design.md
|
||||||
|
|
||||||
|
## Global Constraints
|
||||||
|
|
||||||
|
- First target ASUS FX517ZC, UEFI, SecureBoot disabled.
|
||||||
|
- No changes to current hostconfig, existing Ubuntu or userVM disks.
|
||||||
|
- Dedicated builder store under ignored build/, no global prune.
|
||||||
|
- Stage3 signature primaryfingerprint 13EBBDBEDE7A12775DFDB1BABB572E0E2D182910.
|
||||||
|
- Sources pinned; preserve Portage, package inventory and normal update hooks.
|
||||||
|
- Build jobs4, emerge jobs1 initially; do not stop userVMs for resources.
|
||||||
|
- Installer defaults to dry-run; no default disk or universal installed password.
|
||||||
|
- Physical installation not part of autonomous test execution.
|
||||||
|
|
||||||
|
## Review Focus
|
||||||
|
|
||||||
|
- Cache corruption or wrong signingkey: Task1 verification must reject before import.
|
||||||
|
- Builder retries must preserve unrelated stores/data: Task1 exact scoped paths/names.
|
||||||
|
- Installer target is parent of live/root/mountedpartition: Task3 topology rejection.
|
||||||
|
- Partial format/copy failure: Task3 fail-fast, no subsequent bootloader stage.
|
||||||
|
- Hardware-only behavior: Task4 records unverified physical checks explicitly.
|
||||||
|
|
||||||
|
### Task 1: Reproducible build inputs and isolated builder
|
||||||
|
|
||||||
|
**Files:** `image/sources.json`, `image/packages`, `image/portage/`, `scripts/hydra-build`, `hydra/build.py`, `tests/test_build.py`.
|
||||||
|
**Interfaces:** `hydra-build fetch|prepare|packages|rootfs|iso|status`, `--work PATH`, `--cache PATH`, optional `--podman PATH`. Each step resumable and validates prerequisite manifests. Outputs WORK/rootfs payload or dedicated builder container, WORK/artifacts/, build manifest. No host root required.
|
||||||
|
|
||||||
|
- [ ] Test pinned download hash mismatch, required signaturefingerprint, safe workpath/refusal of root, resume state vs missingactualartifact, scoped Podman argv.
|
||||||
|
- [ ] Observe RED; implement verifiedfetch and isolatedimport/container naming. Use stage3 20261011T170049Z SHA256 50634e8cb87384b94a6dbf78cd2707766c45a5a98f3823e7287d114ee998970b and Portage4696089e782c20b5f0c04952f6698d6a8cc1acb4 archiveSHA256 d24b2056f7ae26506193374b0d9f25c82d4bf547e0ee17279940169418bd3bca.
|
||||||
|
- [ ] Configure officialbinhost signaturechecking, selective ~amd64 for labwc/wlroots, QEMU x86_64 only, required SPICE/GL/USB flags. Preserve licenses and installed packageDB.
|
||||||
|
- [ ] Run actual dependency resolution and package install; record exact versions/USE and any selective sourcebuild decisions. No claim of bit-identical build.
|
||||||
|
- [ ] Run tests and commit builder inputs/scripts.
|
||||||
|
|
||||||
|
### Task 2: Host rootfs and bootable image
|
||||||
|
|
||||||
|
**Files:** `image/rootfs/`, `image/grub.cfg`, `image/dracut.conf`, `image/configure-rootfs.sh`, `tests/test_image.py`.
|
||||||
|
**Interfaces:** Consumes builder and tested CLI/session from graphics plan. Produces labelled HYDRA_OS ISO with boot/vmlinuz, boot/initramfs-live.img, LiveOS/squashfs.img and package/buildmanifest.
|
||||||
|
|
||||||
|
- [ ] Test service/config generation, live-only overrides separation, exact kernelversion used for dracut, image label/cmdline agreement, networksubnet conflict handling.
|
||||||
|
- [ ] Implement rootfs overlay: greetd/minimalsession, recovery, localliveadministration, installedauth baseline, audio, NetworkManager, hydrabr0/DHCP/NAT and narrowlyscoped bridgehelper. Include laptopfirmware/bootdrivers and OVMF.
|
||||||
|
- [ ] Build genericliveinitramfs with dmsquash-live and OverlayFS; squashfspayload retains kernel/packageDB. Assemble UEFIISO with GRUB; save SHA256 and manifest.
|
||||||
|
- [ ] Run image checks and disposable OVMF/KVM liveboot; verify rootfilesystem ready and expected tools. Commit rootfs/imageconfig.
|
||||||
|
|
||||||
|
### Task 3: Explicit guarded installer
|
||||||
|
|
||||||
|
**Files:** `bin/hydra-install`, `hydra/installer.py`, `tests/test_installer.py`.
|
||||||
|
**Interfaces:** `hydra-install --disk DEVICE --user USER [--execute --confirm-erase DEVICE]`; without execute prints exactplan. Environment/default rootfs path points to live squashfs, never running root. Password via getpass/TTY, never CLI/log. Separate nonsecret dryrun from execution.
|
||||||
|
|
||||||
|
- [ ] Test missing/mismatched confirmation, disk mounted directly or through children/ancestors, root/live source backingdisk, invaliddevice, symlink resolution, invalidusername, failedcommands abort subsequentsteps.
|
||||||
|
- [ ] Observe RED; implement sysfs/lsblk topology validation, GPT1GiBESP/ext4, payload extraction, fstabUUIDs, user/password setup and liveoverridesremoval. Explicit target, no automaticdiscoveryselection.
|
||||||
|
- [ ] Install regularinitramfs and GRUBfallback --removable --no-nvram. Checked subprocessargv; handle failure diagnostics and mounts cleanup without deletingtargetdata.
|
||||||
|
- [ ] Test fakecommandfailure paths then complete actualinstallation inside fresh VM using disposable qcow2. Rootprivilege exists only in testguest.
|
||||||
|
- [ ] Commit installer and negative tests.
|
||||||
|
|
||||||
|
### Task 4: Installed-system validation and publication
|
||||||
|
|
||||||
|
**Files:** `dev/iso-smoke.py`, `docs/install.md`, `docs/verification.md`, `README.md`.
|
||||||
|
**Interfaces:** Consumes ISO and installer. Produces evidence from boot/install/reboot and releaseartifact checksum, plus pendinghardwarechecklist.
|
||||||
|
|
||||||
|
- [ ] Boot ISO under OVMF/KVM with fresh disk; install only there; write persistence sentinel.
|
||||||
|
- [ ] Remove ISO and boot installeddisk; verify sentinel, services, QEMUtools, network and shell/recovery. Check no liveoverlay/autologinadminoverride remains.
|
||||||
|
- [ ] Test nested guest VM if KVM nesting available; distinguish virtualgraphics from real laptopresults.
|
||||||
|
- [ ] Run full test suite and independent review. Correct material defects; document remaining physicalchecks without claiming them passed.
|
||||||
|
- [ ] Save ISO locally with checksum, push source/patches/manifests to suppliedrepo. BinaryISO only uploaded when suitable repository release/storage path exists; never commit ISO to Git.
|
||||||
@@ -0,0 +1,79 @@
|
|||||||
|
# HydraOS Gentoo image and installer
|
||||||
|
|
||||||
|
Approved overall scope: Gentoo, installableISO, first ASUS FX517ZC, full autonomous
|
||||||
|
development including dependency patches. This document fixes the bounded image
|
||||||
|
pipeline; it does not authorize overwriting the laptop disk.
|
||||||
|
|
||||||
|
## Build and update model
|
||||||
|
|
||||||
|
Use amd64 systemd stage3 20261011T170049Z, verified against Gentoo release key
|
||||||
|
13EBBDBEDE7A12775DFDB1BABB572E0E2D182910. Pin Portage snapshot
|
||||||
|
4696089e782c20b5f0c04952f6698d6a8cc1acb4 and all custom source/patch versions.
|
||||||
|
Official binpkgs with signature verification are preferred; only packages needing
|
||||||
|
changed flags or testing keywords build from source. Keep compiler concurrency4
|
||||||
|
and emerge job concurrency1 initially. Preserve Portage database/world/update
|
||||||
|
hooks in installed system. Record resulting package versions and build inputs;
|
||||||
|
do not promise bit-for-bit reproducibility of rolling binhost content.
|
||||||
|
|
||||||
|
Build in a dedicated rootless Podman store/container under ignored build state,
|
||||||
|
without host package installs or root access to host disks. Input archives and
|
||||||
|
repository are read-only mounts. Sources/cache/artifacts live under this project.
|
||||||
|
A failed build is resumable; no global image/container prune commands.
|
||||||
|
|
||||||
|
## System contents
|
||||||
|
|
||||||
|
QEMU/KVM, OVMF, labwc>=0.20.0, adapted virt-viewer, Python CLI, foot, greetd,
|
||||||
|
NetworkManager, dnsmasq/nftables, PipeWire/WirePlumber, sudo, distribution kernel,
|
||||||
|
linux-firmware, SOF and Intel microcode. IntelGPU is default; discreteGPU is not
|
||||||
|
assigned to a guest automatically. Generic initramfs covers virtio and ASUS
|
||||||
|
vmd/nvme/xhci/thunderbolt/i915. No preinstalled guestOS or cloud accounts.
|
||||||
|
|
||||||
|
Live session permits explicit local administration and network configuration;
|
||||||
|
no default network login service. Installed account is configured by installer,
|
||||||
|
with a password prompt; do not ship a universal installed-system password.
|
||||||
|
The minimal session contains fullscreen guests, recoveryterminal and concise
|
||||||
|
initial guidance when no VM exists. Default host session never shuts down guests.
|
||||||
|
Other desktop packages remain installable normally through Gentoo.
|
||||||
|
|
||||||
|
## Network
|
||||||
|
|
||||||
|
Fresh installed system creates hydrabr0, subnet10.203.0.0/24, host10.203.0.1,
|
||||||
|
DHCP/DNS for guests, forward/NAT Internet access. New profiles use this network;
|
||||||
|
VM↔VM and LAN→VM connections are not port-restricted by HydraOS. LAN router still
|
||||||
|
needs a route to the guest subnet unless the physical uplink is bridged, which
|
||||||
|
is not generally available over Wi-Fi. Detect conflicting existing subnet and
|
||||||
|
fail clearly instead of silently replacing external networkconfiguration.
|
||||||
|
QMP/SPICE remain private Unix sockets. Bridge permission is narrowly granted
|
||||||
|
to the HydraOS VM user; no blanket sudo command runner.
|
||||||
|
|
||||||
|
## Boot medium
|
||||||
|
|
||||||
|
UEFI x86_64, SecureBoot disabled initially; GRUB -> distribution kernel -> dracut
|
||||||
|
with dmsquash-live -> squashfs root plus volatile OverlayFS. Label HYDRA_OS,
|
||||||
|
cmdline root=live:CDLABEL=HYDRA_OS rd.live.image rd.live.overlay.overlayfs=1 ro.
|
||||||
|
Do not copy entire live image into RAM. Runtime changes in live session are
|
||||||
|
explicitly nonpersistent; persistent VM disks belong on installed storage.
|
||||||
|
|
||||||
|
## Installer
|
||||||
|
|
||||||
|
Text CLI hydra-install first. List disks and provide dry-run plan by default;
|
||||||
|
require explicit target and exact erase confirmation for mutation. Reject mounted
|
||||||
|
or root/live-medium devices and their parent disks. No disk selected by default.
|
||||||
|
Create GPT with1GiB FAT32ESP plus ext4root; unpack the prepared squashfs payload,
|
||||||
|
never copy live /proc,/dev,/run. Generate fstab using UUIDs; configure chosen user,
|
||||||
|
locale/timezone; remove live-only administration/autologin overrides. Generate
|
||||||
|
normal disk initramfs for installed kernel; GRUB fallback EFI/BOOT/BOOTX64.EFI,
|
||||||
|
without modifying host NVRAM during tests. Log operations without passwords.
|
||||||
|
Errors leave a diagnostic; never continue after partition/format/copy failure.
|
||||||
|
|
||||||
|
## Acceptance
|
||||||
|
|
||||||
|
Boot image in disposable OVMF/KVM VM; serial/graphical recovery available. Install
|
||||||
|
to a fresh qcow2, removeISO, boot installed system, verify persisted sentinel,
|
||||||
|
network and tools. Run installer negative tests for missing confirmation, mounted
|
||||||
|
disks, live-source parents and unexpected lsblk data. Nested virtualization tests
|
||||||
|
use their own disks; present laptop/VM disks never passed to testQEMU.
|
||||||
|
|
||||||
|
Before daily-use recommendation, laptop liveboot must validate Wi-Fi, touchpad,
|
||||||
|
audio, brightness, suspend/resume, USB selection, input capture and actualdisplay
|
||||||
|
refresh. Keep these as explicit pending hardware checks until observed.
|
||||||
Reference in New Issue
Block a user