docs: add bible-local with architecture and decisions, fix PLAN.md versions
- bible-local/architecture/system-overview.md: scope, tech stack, key paths - bible-local/architecture/runtime-flows.md: boot sequence, ISO build, collector flow - bible-local/decisions/2026-03-05-nvidia-proprietary-driver.md - PLAN.md: update KERNEL_VERSION 6.6→6.12, NVIDIA 550.54.15→590.48.01 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
58
bible-local/architecture/system-overview.md
Normal file
58
bible-local/architecture/system-overview.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# 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 core/reanimator.
|
||||
|
||||
## 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
|
||||
- Unattended operation — no user interaction at any stage
|
||||
- NVIDIA proprietary driver loaded at boot for GPU enrichment
|
||||
- SSH access in debug ISO for development and testing
|
||||
- Auto-update of audit binary from Gitea releases (production ISO)
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Any writes to the server being audited
|
||||
- Network configuration changes
|
||||
- BMC/IPMI configuration
|
||||
- Anything requiring persistent storage on the audited machine
|
||||
- Windows support
|
||||
|
||||
## Tech stack
|
||||
|
||||
| Component | Technology |
|
||||
|---|---|
|
||||
| Audit binary | Go, static, `CGO_ENABLED=0` |
|
||||
| LiveCD | Alpine Linux 3.21, linux-lts 6.12.x |
|
||||
| ISO build | Alpine mkimage + apkovl overlay |
|
||||
| Init system | OpenRC |
|
||||
| SSH (debug) | Dropbear |
|
||||
| NVIDIA driver | Proprietary `.run` installer, built against linux-lts headers |
|
||||
| Builder VM | Alpine 3.21, 172.27.0.4 |
|
||||
|
||||
## Key paths
|
||||
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `audit/cmd/audit/` | CLI entry point |
|
||||
| `audit/internal/collector/` | Per-subsystem collectors |
|
||||
| `audit/internal/schema/` | HardwareIngestRequest types |
|
||||
| `iso/builder/` | ISO build scripts and mkimage profile |
|
||||
| `iso/overlay-debug/` | Files injected into debug ISO via apkovl |
|
||||
| `iso/builder/VERSIONS` | Pinned versions: Alpine, Go, NVIDIA driver |
|
||||
| `dist/` | Build outputs (gitignored) |
|
||||
| `iso/out/` | Downloaded ISO files (gitignored) |
|
||||
Reference in New Issue
Block a user