Initial public import of the proven Bash installer (installer/) and the production Rust workspace (installer-rs/). The reference ISO, build output and local agent transcripts are gitignored. Verified: installer/tests/run_tests.sh and cargo test --workspace both pass.
124 lines
4.5 KiB
Markdown
124 lines
4.5 KiB
Markdown
# Phoebus OS installer
|
|
|
|
A deterministic, text-mode installer for Phoebus OS, inspired by
|
|
`void-installer`. It is usable entirely without an LLM; AI only augments it.
|
|
|
|
## Goals
|
|
|
|
- Simple keyboard-driven TUI.
|
|
- Logical, revisitable configuration stages.
|
|
- A complete installation plan and explicit confirmation before anything
|
|
destructive happens.
|
|
- Logs for every backend operation.
|
|
- No magical hidden disk modifications.
|
|
|
|
## Two layers
|
|
|
|
```
|
|
tui/ front-end: menus, dialogs, screens
|
|
menu.sh main loop, review and install flow
|
|
screens.sh one function per configuration stage
|
|
ui.sh dialog/whiptail abstraction
|
|
|
|
lib/ deterministic backend (usable without the TUI)
|
|
state.sh structured configuration state
|
|
logging.sh logging + run_cmd + dry-run
|
|
confirm.sh destructive-operation authorization gates
|
|
hardware.sh read-only hardware probing
|
|
disks.sh read-only disk discovery and protection rules
|
|
partitions.sh GPT partitioning
|
|
filesystem.sh mkfs, mount, fstab/crypttab generation
|
|
encryption.sh LUKS2
|
|
btrfs.sh subvolume layout
|
|
network.sh live networking + target hostname
|
|
portage.sh Portage configuration and stage3
|
|
pkgpolicy.sh compile-vs-binary policy
|
|
kernel.sh kernel profile and installation
|
|
boot.sh systemd-boot (BLS entries) + dracut initramfs
|
|
users.sh accounts, passwords, sudo
|
|
desktop.sh desktop profiles
|
|
ai.sh assistant and structured proposals
|
|
opencode.sh pinned, checksum-verified OpenCode
|
|
plan.sh installation plan generation
|
|
validation.sh configuration validation
|
|
install.sh staged orchestration
|
|
|
|
config/
|
|
defaults.conf all defaults
|
|
opencode.manifest pinned OpenCode release + SHA-256
|
|
|
|
tests/ unit tests, no root or disks required
|
|
```
|
|
|
|
## Running in a Gentoo Live environment
|
|
|
|
The LiveGUI reference (or any Gentoo live medium with `dialog`, Portage and the
|
|
disk tools listed in `doc/FINDINGS.md`) can run the installer directly:
|
|
|
|
```sh
|
|
sudo /path/to/installer/bin/ai-installer
|
|
```
|
|
|
|
Useful non-interactive modes (the backend works without the TUI):
|
|
|
|
```sh
|
|
# Print the generated installation plan and validate the configuration
|
|
ai-installer --plan
|
|
|
|
# Load a saved configuration
|
|
ai-installer --config /root/phoebus-install.conf
|
|
|
|
# Dry run: every command is logged, nothing is executed
|
|
ai-installer --dry-run
|
|
|
|
# Run the backend without a TUI (still requires explicit ERASE confirmation)
|
|
ai-installer --config /root/phoebus-install.conf --install
|
|
|
|
# Fetch and verify the pinned OpenCode release
|
|
ai-installer --bootstrap-opencode
|
|
```
|
|
|
|
### Typical flow
|
|
|
|
1. Network (connect Wi-Fi if needed).
|
|
2. Keyboard, hostname, locale, timezone, user.
|
|
3. Disk: pick a target (protected devices are never offered).
|
|
4. Filesystem / encryption: LUKS2 is the default; set a passphrase.
|
|
5. Boot / kernel / packages / desktop as desired.
|
|
6. Review configuration -> inspect the plan.
|
|
7. Install -> read the destructive summary, type `ERASE`, confirm again.
|
|
|
|
## Safety model
|
|
|
|
- Detection never modifies a disk.
|
|
- The target disk must be explicitly selected from candidates.
|
|
- Disks that are mounted, read-only, optical/loop, or back the live medium are
|
|
marked **PROTECTED** and cannot be selected.
|
|
- All destructive commands go through `run_destructive`, which refuses to run
|
|
unless `PHOEBUS_DESTRUCTIVE_AUTHORIZED=yes`. Only `install.sh` grants this,
|
|
only after the plan is approved.
|
|
- Whole-disk erase additionally requires typing `ERASE`.
|
|
- Dry-run mode redirects all file writes to a temporary sandbox and runs no
|
|
commands.
|
|
- Passwords, passphrases and API keys are never written to the config or logs.
|
|
|
|
## Package policy
|
|
|
|
`lib/pkgpolicy.sh` implements the rule "compile when cheap or beneficial, use a
|
|
binary when expensive and the benefit is negligible". It is deterministic and
|
|
uses a curated table plus optional historical compile times
|
|
(`$STATE_DIR/compile-times.tsv`). No model is consulted to guess performance.
|
|
|
|
## AI policy
|
|
|
|
- The normal install path is fully deterministic and LLM-free.
|
|
- The AI assistant explains hardware, disks, filesystems, kernel and package
|
|
choices, and can translate a natural-language request into a **structured
|
|
proposal** (flat JSON with a fixed key whitelist).
|
|
- Every proposed field is validated by `lib/validation.sh`. The LLM never
|
|
receives secrets, never touches a disk and never runs a command.
|
|
- Proposal flow: request -> proposal -> validation -> preview -> confirmation ->
|
|
backend.
|
|
|
|
See `doc/FINDINGS.md` for environment findings and `doc/TESTING.md` for safe
|
|
testing instructions.
|