reanimator/bee
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
f91bce86612e1b622b9360ffd0430cd37c00bd01
bee/bible-local/architecture/system-overview.md
Michael Chus 004cc4910d feat(webui): replace TUI with full web UI + local openbox desktop 
- Remove audit/internal/tui/ (~3000 LOC, bubbletea/lipgloss/reanimator deps)
- Add /api/* REST+SSE endpoints: audit, SAT (nvidia/memory/storage/cpu),
  services, network, export, tools, live metrics stream
- Add async job manager with SSE streaming for long-running operations
- Add platform.SampleLiveMetrics() for live fan/temp/power/GPU polling
- Add multi-page web UI (vanilla JS): Dashboard, Metrics charts, Tests,
  Burn-in, Network, Services, Export, Tools
- Add bee-desktop.service: openbox + Xorg + Chromium opening http://localhost/
- Add openbox/tint2/xorg/xinit/xterm/chromium to ISO package list
- Update .profile, bee.sh, and bible-local docs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-27 19:21:14 +03:00

5.8 KiB
Raw Blame History

System Overview — bee

What it does

Hardware audit LiveCD. Boots on a server via BMC virtual media or USB. Collects hardware inventory at OS level (not through BMC/Redfish). Produces HardwareIngestRequest JSON compatible with the contract in bible-local/docs/hardware-ingest-contract.md.

Why it exists

Fills gaps where Redfish/logpile is blind:

  • NVMe serials and SMART data
  • DIMM serials and slot layout
  • GPU serials and VBIOS versions
  • Physical disks behind RAID controllers
  • Full SMART wear telemetry
  • NIC firmware versions

In scope

  • Read-only hardware inventory: board, CPU, memory, storage, PCIe, PSU, GPU, NIC, RAID
  • Machine-readable health summary derived from collector verdicts
  • Operator-triggered acceptance tests for NVIDIA, memory, and storage
  • NVIDIA SAT includes both diagnostic collection and mixed-precision GPU stress via bee-gpu-stress
  • bee-gpu-stress should exercise tensor/inference paths (fp16, fp32/TF32, fp8, fp4 when supported by the GPU/userspace stack) and fall back to Driver API PTX burn only if cuBLASLt is unavailable
  • Automatic boot audit with operator-facing local console and SSH access
  • NVIDIA proprietary driver loaded at boot for GPU enrichment via nvidia-smi
  • SSH access (OpenSSH) always available for inspection and debugging
  • Full web UI via bee web on port 80: interactive control panel with live metrics, SAT tests, network config, service management, export, and tools
  • Local operator desktop: openbox + Xorg + Chromium auto-opening http://localhost/
  • Local tty1 operator UX: bee autologin, openbox desktop auto-starts with Chromium on http://localhost/

Network isolation — CRITICAL

The live CD runs in an isolated network segment with no internet access.

  • All tools, drivers, and binaries MUST be pre-baked into the ISO at build time
  • No package installation at boot — packages are installed during ISO creation, not at runtime
  • No downloads at boot — NVIDIA modules, vendor tools, and all binaries come from the ISO overlay
  • DHCP is used only for LAN access (SSH from operator laptop); internet is NOT assumed
  • Any feature requiring network downloads cannot be added to the live CD

Out of scope

  • Any writes to the server being audited
  • Network configuration changes (persistent)
  • BMC/IPMI configuration
  • Anything requiring persistent storage on the audited machine
  • Windows support
  • Any functionality requiring internet access at boot
  • Component lifecycle/history across multiple snapshots
  • Status transition history (status_history, status_changed_at) derived from previous exports
  • Replacement detection between two or more audit runs

Contract boundary

  • bee is responsible for the current hardware snapshot only.
  • bee should populate current component state, hardware inventory, telemetry, and status_checked_at.
  • Historical status transitions and component replacement logic belong to the centralized ingest/lifecycle system, not to bee.
  • Contract fields that have no honest local source on a generic Linux host may remain empty.

Tech stack

Component Technology
Audit binary Go, static, CGO_ENABLED=0
Live ISO Debian 12 (bookworm), amd64 live-build image
ISO build Debian live-build + overlay sync into config/includes.chroot/
Init system systemd
SSH OpenSSH server
NVIDIA driver Proprietary .run installer, built against Debian kernel headers
NVIDIA modules Loaded via insmod from /usr/local/lib/nvidia/
GPU stress backend bee-gpu-stress + cuBLASLt/cuBLAS/cudart mixed-precision GEMM, with Driver API PTX fallback
Builder Debian 12 host/VM or Debian 12 container image

Operator UX

  • On the live ISO, tty1 autologins as bee
  • bee-desktop.service starts X11 + openbox + Chromium on display :0
  • Chromium opens http://localhost/ — the full web UI
  • SSH remains available independently of the local console path
  • Remote operators can open http://<ip>/ in any browser on the same LAN
  • VM-oriented builds also include qemu-guest-agent and serial console support for debugging
  • The ISO boots with toram, so loss of the original USB/BMC virtual media after boot should not break already-installed runtime binaries

Runtime split

  • The main Go application must run both on a normal Linux host and inside the live ISO
  • Live-ISO-only responsibilities stay in iso/ integration code
  • Live ISO launches the Go CLI with --runtime livecd
  • Local/manual runs use --runtime auto or --runtime local
  • Live ISO targets must have enough RAM for the full compressed live medium plus runtime working set because the boot medium is copied into memory at startup

Key paths

Path Purpose
audit/cmd/bee/ Main CLI entry point
audit/internal/collector/ Per-subsystem collectors
audit/internal/schema/ HardwareIngestRequest types
iso/builder/ ISO build scripts and live-build profile
iso/overlay/ Source overlay copied into a staged build overlay
iso/vendor/ Optional pre-built vendor binaries (storcli64, sas2ircu, sas3ircu, arcconf, ssacli, …)
internal/chart/ Git submodule with reanimator/chart, embedded into bee web
iso/builder/VERSIONS Pinned versions: Debian, Go, NVIDIA driver, kernel ABI
iso/builder/smoketest.sh Post-boot smoke test — run via SSH to verify live ISO
iso/overlay/etc/profile.d/bee.sh tty1 welcome message with web UI URLs
iso/overlay/home/bee/.profile bee shell profile (PATH only)
iso/overlay/etc/systemd/system/bee-desktop.service starts X11 + openbox + chromium
iso/overlay/usr/local/bin/bee-desktop startx wrapper for bee-desktop.service
iso/overlay/usr/local/bin/bee-openbox-session xinitrc: tint2 + chromium + openbox
dist/ Build outputs (gitignored)
iso/out/ Downloaded ISO files (gitignored)
Reference in New Issue View Git Blame Copy Permalink