docs: specify Gentoo image builder and guarded installer

2026-10-13 04:03:18 +03:00
parent 2408d56d14
commit e6bec555c4
2 changed files with 152 additions and 0 deletions
@@ -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.