fruix/docs/PLAN_INSTALLER.md

PLAN_INSTALLER

Summary

Yes: this paints a consistent picture.

The proposed Fruix installer direction is:

• FreeBSD-native underneath for disk, filesystem, boot, and target-system materialization.
• Fruix-native above for declaration generation, install metadata, identity/pinning, and long-lived product behavior.
• Guix-like installer structure for the interactive installer itself: a Scheme program, organized as explicit steps, with a small Newt TUI.
• Disko-like storage modeling as part of the base Fruix system model, not as an installer-only ad hoc script layer.

That yields a coherent split:

1. storage declarations are first-class Fruix objects
2. materialization uses native FreeBSD tools
3. the installer is a Fruix application
4. the installed result records both declaration identity and realized storage metadata
5. ordinary reconfigure / switch / rollback do not repartition disks

Current starting point

Already in place:

• canonical fruix repo/channel exists
• bootable installer image and installer ISO paths exist
• installer ISO boot path has been validated
• minimal scripted install flow exists
• installed nodes are already real Fruix nodes for build/reconfigure/build-base/deploy/switch/rollback

So this plan is not starting from zero. It starts from a validated non-interactive installer artifact pipeline and layers a first-class storage model plus an interactive installer UX on top.

Design principles

1. Storage layout belongs in base Fruix

Fruix should gain a first-class storage declaration layer that can be used by:

• installer TUI
• non-interactive fruix system install
• disk image generation
• installer image generation
• future remote install / install-on-deploy flows

This should not live only inside the installer.

2. Runtime config and install-time layout are related but distinct

Fruix should persist both:

• the declared storage intent
• the realized runtime mount/boot config
• the realized install metadata

But routine system generation operations should not automatically mutate partition tables.

3. Keep the execution substrate FreeBSD-native

Actual realization should shell out to native FreeBSD tools such as:

• gpart
• newfs
• mount
• swapon
• geli when encryption is added
• zpool / zfs when ZFS support is added
• mkimg / image tooling where applicable
• existing Fruix install/materialization helpers

4. Keep installer logic in canonical fruix

The installer TUI, step logic, declaration generation, and install semantics belong in canonical fruix, not fruix-bootstrap.

5. Prefer a simple network story first

Unlike Guix-on-Linux, Fruix-on-FreeBSD should not assume ConnMan.

First version should keep networking deliberately simple:

• optional networking
• wired-first
• DHCP-first
• manual static configuration only if needed
• no Wi-Fi manager requirement in v1
• no long-lived network-management daemon dependency for the installer UX

Non-goals for v1

The first interactive Fruix installer should not try to solve all storage and deployment problems.

Out of scope for the first version:

• automatic storage mutation during ordinary fruix system reconfigure
• post-install partition resizing/migration engine
• full multi-disk orchestration
• Wi-Fi-first installer UX
• exhaustive ZFS layout support on day one
• polished remote install orchestration from the installer itself
• replacing the existing validated scripted install path immediately

Target architecture

Layer 1: Fruix storage declaration model

Add a base Fruix storage model that represents:

• target disk(s)
• partition table type
• partitions
• labels
• filesystem type
• mount points
• swap
• optional boot partition details
• optional encryption layer
• later: ZFS/UFS specialization and multi-disk layouts

This should be declarative and serializable into metadata.

Suggested module direction:

• modules/fruix/system/storage/model.scm
• modules/fruix/system/storage/validate.scm
• modules/fruix/system/storage/render.scm
• modules/fruix/system/freebsd/storage.scm or equivalent backend module

Generic storage intent should stay separate from FreeBSD-specific realization.

Layer 2: FreeBSD materialization backend

Add a backend that turns storage declarations into explicit, ordered actions:

• probe disks
• validate target device selection
• create partition table
• create partitions
• make filesystems
• enable swap
• mount target tree
• render boot/runtime config files
• populate/install Fruix system closure
• install boot support

This should look more like Disko's “generate apply scripts from declarations” than like ad hoc shell embedded throughout the installer.

Important: the backend should support both:

• dry-run / plan rendering
• real application

Layer 3: Fruix installer application

Add an installer application in Scheme, structured more like Guix's installer:

• explicit installer state object
• ordered steps
• step-local validation
• generated final declaration
• final install/apply step

Suggested module direction:

• modules/fruix/installer.scm
• modules/fruix/installer/state.scm
• modules/fruix/installer/steps.scm
• modules/fruix/installer/final.scm
• modules/fruix/installer/newt.scm
• modules/fruix/installer/newt/*.scm

Layer 4: Metadata and persistence

Persist:

• the selected/generated Fruix system declaration
• the selected/generated storage declaration
• realized disk/filesystem identifiers
• install target details
• Fruix channel identity / origin / revision where available
• installer version / plan version

Record this both:

• in closure metadata where appropriate
• in installed-system state under Fruix-managed metadata paths

Proposed commands and behavior

Near-term expected command surface:

• existing fruix system installer
• existing fruix system installer-iso
• existing fruix system install
• new internal or public storage application entrypoint
• installer TUI launched inside Fruix installer media

Possible later public storage commands:

• fruix system storage-plan ...
• fruix system storage-apply ...
• fruix system install --layout FILE ...

The exact CLI naming can be deferred. The important part is the architecture: a first-class storage layer reused by the installer and non-interactive install paths.

Step-by-step implementation plan

Step 1: Write down the storage semantics before coding

Define the product semantics for Fruix storage declarations.

Deliverables:

• document the distinction between:
  • declared storage intent
  • realized storage metadata
  • runtime mount/boot configuration
• document the safety boundary:
  • installer/install actions may partition/format
  • reconfigure / switch / rollback may not partition/format by default
• define v1 supported layouts

Recommended v1 supported layouts:

• single-disk GPT
• EFI system partition
• UFS root filesystem
• optional swap partition
• optional separate /var

Exit criteria:

• Fruix has a stable written storage model contract before implementation starts

Step 2: Add the base storage declaration model to canonical Fruix

Implement first-class storage records and constructors.

Deliverables:

• generic storage record types
• normalization and validation helpers
• deterministic metadata rendering
• support for embedding storage layout in or alongside operating-system declarations

Requirements:

• must be reusable by installer, image builder, and non-interactive install
• must not hard-code installer UI concerns into the model
• must preserve future room for ZFS/encryption/multi-disk extensions

Exit criteria:

• a declaration can represent a concrete install target layout without performing side effects

Step 3: Add a FreeBSD storage realization backend

Implement the backend that turns storage declarations into ordered materialization operations.

Deliverables:

• disk probing helpers
• validation of target devices
• plan generation
• dry-run text rendering
• actual apply path that shells out to FreeBSD tools

The backend should initially support:

• gpart create
• gpart add
• newfs_msdos or equivalent for EFI where needed
• newfs for UFS root
• swapon configuration
• mount tree creation
• target population handoff into existing Fruix install/materialization code

Prefer explicit, testable helper functions over one giant shell script.

Exit criteria:

• Fruix can take a storage declaration and non-interactively realize it onto a raw disk/image using native FreeBSD tooling

Step 4: Rework non-interactive install to use the storage layer

Refactor fruix system install so it consumes the new storage declaration layer rather than ad hoc installer-only disk logic.

Deliverables:

• fruix system install path routed through the shared storage backend
• existing installer image / installer ISO install path updated to use the same backend
• no duplication of partitioning logic between installer and CLI install path

Exit criteria:

• one shared storage/apply path is used by both scripted install and future TUI install

Step 5: Persist storage declaration and realized layout metadata

Add explicit metadata capture.

Deliverables:

• declared storage layout snapshot in system metadata
• realized partition/filesystem metadata snapshot after install
• linkage from installed system generation to install provenance
• clear versioning of metadata schema

Examples of useful recorded data:

• target device used at install time
• partition labels and filesystem types
• UUIDs / provider names discovered after creation
• boot partition details
• install timestamp
• Fruix declaration identity and source origin

Exit criteria:

• Fruix can answer both “what layout was intended?” and “what was actually installed?”

Step 6: Package and validate the Newt stack for Fruix on FreeBSD

Before building the real TUI, make the UI dependency story explicit.

Deliverables:

• package definition for newt if not already available through Fruix inputs
• package definition or integration path for Guile bindings to Newt
• builder/runtime validation on FreeBSD
• minimal proof-of-life TUI program in Fruix

Notes:

• target end state is a Guix-like Scheme + Newt installer structure
• if Guile bindings need bring-up work on FreeBSD, do that here
• avoid coupling installer design to bootstrap repo specifics

Exit criteria:

• Fruix can run a tiny Scheme/Newt UI inside a FreeBSD Fruix environment

Step 7: Build the installer state machine and step framework

Implement the Guix-like installer structure.

Deliverables:

• installer state object
• step descriptors
• step ordering and back/next flow
• step-local validation
• final rendering of generated declaration(s)

Suggested initial steps:

1. welcome
2. keyboard/console assumptions if needed
3. target disk selection
4. storage layout selection/edit
5. hostname
6. root/user setup
7. network choice (optional/simple)
8. summary/review
9. install/apply
10. completion/reboot/shell

Exit criteria:

• installer logic exists independently of the final widgets used for each step

Step 8: Implement the first small Newt TUI

Build the actual interactive UI on top of the step framework.

Deliverables:

• main installer entrypoint launched by Fruix installer media
• Newt forms/widgets for each initial step
• summary screen showing:
  • chosen Fruix system settings
  • chosen storage layout
  • clear destructive-action warnings
• failure screen with logs/shell escape path

Requirements:

• keep it small and reliable
• prefer clear text prompts over elaborate UI behaviors
• always provide a shell/log escape hatch during install

Exit criteria:

• a user can interactively choose a v1 layout and reach a final review screen

Step 9: Keep networking simple and explicit

Implement only a minimal network story for the installer.

Deliverables:

• detect interfaces
• optional “configure wired networking” step
• DHCP-first support via native FreeBSD tools
• optional manual static configuration if easy to support cleanly
• no ConnMan dependency
• network may be entirely skipped when installing from fully prebuilt local artifacts

Likely implementation approach:

• use ifconfig, dhclient, route, and resolver file updates as needed
• treat networking as a helper step, not as a central installer subsystem

Exit criteria:

• installer can fetch or validate network reachability when needed without adopting a heavy network-management stack

Step 10: Wire installer apply step to the shared backend

Connect the TUI's final “install” action to the already-implemented shared storage and install backend.

Deliverables:

• summary confirmation before destructive actions
• apply progress view
• disk layout realization
• target system population
• boot setup
• metadata persistence
• success/failure handling

Requirements:

• no TUI-specific partitioning logic
• all real disk mutation goes through the shared backend
• logs remain available for debugging and validation

Exit criteria:

• interactive and non-interactive installs are two frontends to the same Fruix install engine

Step 11: Update installer media to launch the new Fruix installer app

Promote the TUI from an internal component to the default installer UX.

Deliverables:

• installer image launches Fruix installer application by default
• shell remains available as an escape hatch
• installer ISO/test paths updated accordingly
• existing scripted fallback remains available during transition if needed

Exit criteria:

• booting the Fruix installer media starts the Fruix Newt installer by default

Step 12: Add end-to-end validation harnesses

Extend the existing validation style with real installer coverage.

Deliverables:

• syntax/unit validation for storage declarations and backend rendering
• non-interactive storage apply tests on raw disk images
• installer media boot test that reaches the TUI
• automated or semi-automated install test for the v1 layout
• real XCP-ng validation for the full install path
• regression coverage for installed-node boot/switch/rollback after installation

Suggested validation milestones:

• build storage declaration -> render plan -> apply to raw image
• installer image boots -> Newt UI launches
• interactive or scripted test chooses default v1 layout -> install completes
• installed system boots and behaves as a real Fruix node

Exit criteria:

• the installer is validated as a product workflow, not only as a boot artifact

Step 13: Expand storage capabilities after the v1 path is solid

Once the basic path is validated, add richer layouts incrementally.

Next candidates:

• ZFS root layouts
• encryption layer
• separate /home
• mirrored boot/root layouts
• multi-disk declarations
• image-builder reuse of the same storage declaration object

Rule:

• every new layout feature must extend the shared storage model/backend rather than adding installer-only special cases

Recommended implementation order by milestone

Milestone A: base storage model

• Step 1
• Step 2
• Step 3

Milestone B: shared install engine

• Step 4
• Step 5

Milestone C: UI substrate

• Step 6
• Step 7

Milestone D: first interactive installer

• Step 8
• Step 9
• Step 10
• Step 11

Milestone E: validation and expansion

• Step 12
• Step 13

Concrete v1 scope recommendation

To keep the first Fruix installer manageable, v1 should target exactly this workflow:

• boot Fruix installer ISO
• choose target disk
• choose default GPT layout
• create:
  • EFI partition
  • root UFS partition
  • optional swap
• enter hostname and initial credentials
• optionally bring up wired DHCP
• install prebuilt Fruix system artifact
• record Fruix declaration + storage metadata
• reboot into installed Fruix node

That is enough to prove the full architecture without getting stuck in storage-combinator explosion.

Consistency check

This plan is internally consistent with current Fruix direction because it keeps the existing product boundaries intact:

• canonical fruix remains the source of truth
• fruix-bootstrap remains only a builder-preparation layer
• installer logic becomes a Fruix feature, not a bootstrap feature
• storage layout becomes a reusable Fruix declaration, not a one-off install script
• FreeBSD-specific disk actions remain native and practical
• installed systems remain real Fruix nodes after boot

Immediate next action

The recommended next implementation task is:

1. write the v1 storage semantics document
2. add the first base storage declaration model to canonical Fruix
3. route existing non-interactive install paths through that shared model/backend before building the Newt UI

That sequencing prevents the TUI from hard-coding one-off install logic and keeps the installer aligned with long-lived Fruix system behavior.