docs + doctor: be honest about amd64-only support

The README sold the product as "Linux with /dev/kvm"; the deeper docs
admit that the Makefile pins companion builds to GOARCH=amd64, the
kernel catalog ships only x86_64 entries, and OCI import pulls
linux/amd64 layers. arm64 users who show up through the README only
discover that after install fails in non-obvious ways.

Two surface-level fixes:

- README requirements list leads with "x86_64 / amd64 Linux — arm64 is
  not supported today", with a short note on the three places that
  assumption lives so users understand it's not a last-mile gap.
- `banger doctor` now runs an architecture check that passes on amd64
  and FAILS (not warns) on anything else, referencing the three
  downstream assumptions. Hard-fail rather than warn so a user on an
  arm64 machine doesn't waste time chasing unrelated preflight items.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Thales Maciel 2026-04-20 13:03:50 -03:00
parent e69810610a
commit 58464ac28c
No known key found for this signature in database
GPG key ID: 33112E6833C34679
2 changed files with 25 additions and 1 deletions

View file

@ -3,6 +3,7 @@ package daemon
import (
"context"
"fmt"
"runtime"
"strings"
"banger/internal/config"
@ -38,6 +39,8 @@ func Doctor(ctx context.Context) (system.Report, error) {
func (d *Daemon) doctorReport(ctx context.Context, storeErr error) system.Report {
report := system.Report{}
addArchitectureCheck(&report)
if storeErr != nil {
report.AddFail(
"state store",
@ -57,6 +60,23 @@ func (d *Daemon) doctorReport(ctx context.Context, storeErr error) system.Report
return report
}
// addArchitectureCheck surfaces a hard-fail when banger is running on
// a non-amd64 host. Companion binaries are pinned to amd64 in the
// Makefile, the published kernel catalog ships only x86_64 images, and
// OCI import pulls linux/amd64 layers. Letting users discover this
// through cryptic downstream failures is worse than saying it up front.
func addArchitectureCheck(report *system.Report) {
if runtime.GOARCH == "amd64" {
report.AddPass("host architecture", "amd64")
return
}
report.AddFail(
"host architecture",
fmt.Sprintf("running on %s; banger today only supports amd64/x86_64 hosts", runtime.GOARCH),
"companion build, kernel catalog, and OCI import all assume linux/amd64",
)
}
// addVMDefaultsCheck surfaces the effective VM sizing that `vm run` /
// `vm create` will apply when the user omits the flags. Shown as a
// PASS check so it always renders, with per-field provenance