Skip to content

feat: test and document the native Server installer from one end-to-end run #448

Open
1 of 4 issues completed
Open

Description

@castrojo

Goal

One end-to-end invocation exercises the real Bluefin Server systemd-sysinstall / systemd-repart installer in QEMU/KVM on a GitHub-hosted runner. The same passing run supplies verified instructions and actual screenshots for root INSTALLATION.md, regenerated on schedule and proposed with its screenshots in one PR. Test content lives in projectbluefin/testsuite; Server retains its existing QEMU orchestration and documentation publication. This is an open design/implementation tracking issue, not authorization to implement unverified branches.

Approved scope and decisions

  • Shipped USB installer and documented diskless sysinstall path; every exposed installer screen/choice, all three Server installer profiles, install-time provisioning, first-boot password and login behavior.
  • Exclude other Bluefin installers, generic systemd-boot utility controls, Homelab cluster readiness and add-on rollouts. Homelab profile installation/provisioning remains required; stopping after its message is not sufficient proof.
  • New testsuite native-console suite and Server consumer split approved, satisfying testsuite's human gate for creating a suite/changing a consumer interface. Existing desktop e2e.yml interfaces are not redesigned.
  • A separately scoped USB-only userspace wait-online correction is approved and should land independently before the screenshot work.
  • A declared disposable installer copy with upstream-supported secure-boot-enroll manual is approved for reaching the Setup Mode branch. Signed native binaries stay unchanged; ordinary cases use the unmodified matching artifact.
  • No installer stand-in, shell partition/install replacement, GUI injection, screenshot rewriting, runtime LLM prose generation, silent skipped coverage or direct commits to main.

Source-grounded starting point

Investigated Server commit: 9cf777e2bab2b3c9fbdc9cc9462afa77d7070ec8. AGENTS.md owns the image layout; its hard rules require native sysinstall/repart. The FSDK pin resolves to systemd 261.2 (4925d9f07fc697efccd98a93046ff535b8832445), not latest manual version 262.

  • Existing native console harness: DOGFOOD_INSTALL=console, QEMU sendkey, virtual-console text mirror, firmware enrollment, installation, first boot and login. Reuse/extend it rather than copy VM orchestration.
  • Diskless operator procedure: mount the payload ESP and invoke native sysinstall with its disk UKI and repart definitions. Existing dogfood-install.sh instead runs unattended sysinstall from a probe and suppresses its questions. Establish interactive entry on the diskless guest before promising that coverage.
  • USB behavior and prompts, shipped helpers/drop-in and UKI profiles enumerate the Server choices. USB fixes erase/firmware registration and initializes locale/timezone/keymap; do not invent those USB menus.
  • Testsuite QEMU screenshot helper captures the actual framebuffer and converts PPM to PNG using stdlib. Dogtail's desktop AT-SPI driver does not see a Linux VT. Testsuite's current installer suite is fisherman/bootc post-boot coverage, not this installer.
  • Upstream sysinstall 261.2, repart, firstboot and loader.conf: use real native partition validation/install, first-boot root setup, and file/socket-loaded sensitive credentials.

Coverage and evidence contract

One invocation may run multiple fresh disposable VM cases. Enumerate accepted/default/invalid/cancel choices from pinned source and skills, not click exploration or screenshots. Cover boot-profile selection; Secure Boot gates and approved enrollment fixture; candidate disks/one-disk default/multiple-disk selection/refusal; native welcome/summary/confirmation/progress; completion countdown/Enter; Homelab passphrase/template/credential provisioning; root-password visibility, empty/mismatch/success and login; direct diskless device/keep-erase/registration prompts; existing A/B update continuation. Successful paths prove installed results; cancellations prove no target writes and unselected disks unchanged. Source changes require reviewed inventory reconciliation; source-text hashing alone is not semantic coverage proof.

Screenshot sequence has one controller: assert current prompt, capture/complete/release monitor access, send keys, verify transition. Reuse one monitor endpoint, not a second controller or observer. Use terminal text and system/disk state for assertions; PNGs illustrate the verified checkpoints. No secrets in published captures. Keep UNIX socket paths below the observed 108-byte limit.

A complete passing result with every required inventory case present and passed supplies ordered authored prose/checkpoint/image associations. Reuse Behave JSON and results-directory conventions. Do not use testsuite's generic is_success as publication approval: it accepts skipped scenarios. Missing, skipped, cancelled or truncated required results block docs publication.

Server checks out testsuite separately at a literal reviewed full commit SHA containing the new suite, with the existing SHA-pinned checkout action and persist-credentials: false. Never float main and merely record what arrived. Match Server harness/source to the tested image and record Server/testsuite revisions, image version/digests, firmware checksum, QEMU version and run URL.

Scheduled documentation and release policy

Reuse the existing nightly image/update artifacts and schedule; no duplicate image build only for docs. Render ordinary prose/numbered instructions without emojis, decorative formatting or raw test syntax. Output root INSTALLATION.md plus docs/installation/*.png (both follow the existing docs-only build classifier). Explicitly add the guide to the existing docs validator. Update only the matching Server usb-installer.md skill and avoid duplicating its walkthrough.

Open/update one coherent documentation PR using existing propose-pr.sh and mergeraptor App authentication, after untrusted execution, with read-only test jobs. Separate approval remains required for new secrets/environment access or expanded permissions. Keep last-known-good docs on failure and expose refresh failures and 'verified, publication pending' state; unmerged docs are not current.

Release policy is not changed by this issue. Existing release gates remain. Whether the expanded matrix or documentation publication should become release-blocking is an explicit unapproved maintainer decision, especially while firmware/diskless branches remain feasibility-gated. Scheduled docs publication must fail closed independently; docs lag is reported rather than silently blocking releases or claiming zero drift.

Verified runtime evidence and remaining prerequisites

  • Matching release v26.10.1094 passed signature/checksum verification; existing unmodified native console scenario passed its full four-boot verdict locally in 75.15 seconds with exit code 0. Actual native confirmation PNG captured and visually inspected; a separate concurrent capture/pause attempt failed and is not passing E2E evidence.
  • Hosted nightly 2026-10-11: native console step passed in 76 seconds; boot-test passed in 28m41s under its existing 90-minute job timeout. 2026-10-10: console step passed in 82 seconds; boot-test passed in 31m20s. Existing hosted KVM/console operation is demonstrated; expanded-matrix resources, durations and screenshot stability are not.
  • Userspace wait-online starts on the offline stick and failed near 127s in a retained paused run, inserting status/failure lines into the confirmation. Only the initrd is masked today.
  • Manual enrollment needs the approved declared copy because if-safe auto-enrolls in QEMU. The pinned RPM includes OVMF_VARS.secboot.fd, but foreign enforcing firmware may reject the installer before its warning; prove actual state/reachability, not mocked efivarfs.
  • Boot-menu capture/selection happens before the Linux /dev/vcs mirror exists. Establish a real firmware/serial/framebuffer readiness signal and navigation strategy within the shipped three-second menu window.
  • Diskless interactive sysinstall needs a real console-attached launch/authentication path; the existing no-TTY unattended probe is not proof.

Acceptance criteria

  • The approved source-derived inventory has a runnable native testsuite entry point using existing Server orchestration, with no silent omissions or skips.
  • USB-only offline correction has separate before/after proof and does not change netboot/disk behavior.
  • Successful paths install/provision/boot real Server; refusal paths leave disks unchanged.
  • Every generated instruction and required screenshot comes from the same complete passing run.
  • Tested revision/image/firmware provenance is consistent and immutable; unexpected UI/source changes demand inventory reconciliation.
  • Hosted expanded-matrix and repeated screenshot feasibility checks are exercised; unresolved branches block an exhaustive docs verdict.
  • Missing/failed/skipped/truncated evidence demonstrably prevents generation/publication, preserves old docs and visibly reports staleness/publication lag.
  • Relevant Server changes pass just validate, full pytest+Bats via just test-unit, docs checks and workflow lint; testsuite changes pass its matching full modules, Behave dry-run and repo gates.
  • Subissues preserve ownership boundaries; no release-policy expansion without separate approval.

Subissues and dependency order

Activity

  1. added theissue type on Oct 11, 2026
  2. mrbobbytables commented on Oct 11, 2026

    @mrbobbytables
    Contributor

    This tracking issue coordinates testing and documenting the native Server installer from one end-to-end run. It is blocked on external implementation work across its constituent sub-issues that must land first:

    Once the sub-issues land and testsuite#975 merges its native suite, the end-to-end verification and documentation pipeline can be completed.

    — hive: backend=copilot model=gemini-3.8-flash


    🐝 Hive Agent: contributor | SHA: 9428435

  3. added
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    on Oct 11, 2026
  4. removed
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    on Oct 21, 2026
  5. hivecommons-hive commented on Oct 21, 2026

    @hivecommons-hive
    Contributor

    Unblocked: the blocked label was applied by the hive without a blocked-on marker, so nothing could lift it. This issue is actionable again.

  6. added
    epicMulti-issue initiative tracked on the Bluefin planning board
    on Oct 27, 2026
  7. Danathar commented on Oct 27, 2026

    @Danathar
    Contributor

    Marking this as a tracker (epic), as its own text says ("an open design/implementation tracking issue, not authorization to implement"). The concrete work is #451 (accepted) and projectbluefin/testsuite#975 (accepted). Epics aren't offered to agents or contributors.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    epicMulti-issue initiative tracked on the Bluefin planning boardstage/010-actionableTriaged; eligible for the hive to pick up

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions