Remove runtime-bundle image dependencies
Hard-cut banger away from source-checkout runtime bundles as an implicit source of\nimage and host defaults. Managed images now own their full boot set,\nimage build starts from an existing registered image, and daemon startup\nno longer synthesizes a default image from host paths.\n\nResolve Firecracker from PATH or firecracker_bin, make SSH keys config-owned\nwith an auto-managed XDG default, replace the external name generator and\npackage manifests with Go code, and keep the vsock helper as a companion\nbinary instead of a user-managed runtime asset.\n\nUpdate the manual scripts, web/CLI forms, config surface, and docs around\nthe new build/manual flow and explicit image registration semantics.\n\nValidation: GOCACHE=/tmp/banger-gocache go test ./..., bash -n scripts/*.sh,\nand make build.
This commit is contained in:
parent
01c7cb5e65
commit
572bf32424
44 changed files with 1194 additions and 3456 deletions
86
AGENTS.md
86
AGENTS.md
|
|
@ -1,55 +1,49 @@
|
|||
# Repository Guidelines
|
||||
|
||||
## Project Structure & Module Organization
|
||||
- `cmd/banger` and `cmd/bangerd` are the primary user-facing entrypoints.
|
||||
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker, and system integration code.
|
||||
- The VM lifecycle is now organized around daemon capabilities plus a structured guest-config builder. New host-integrated VM features should plug into that Go path instead of adding more one-off branches through `internal/daemon/vm.go`.
|
||||
- `scripts/customize.sh`, `scripts/make-rootfs.sh`, and `scripts/interactive.sh` remain as manual rootfs/customization helpers; normal VM lifecycle, NAT, `.vm` DNS, and daemon-driven image builds are handled by the Go control plane.
|
||||
- Source checkouts use a generated `./build/runtime/` bundle for Firecracker, kernels, modules, rootfs images, and helper copies. Bundle defaults come from `./build/runtime/bundle.json` when present. Those runtime artifacts are not meant to be tracked directly in Git.
|
||||
- The daemon keeps state under XDG directories rather than the old repo-local `state/` layout.
|
||||
## Project Structure
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
- `make build` builds `./build/bin/banger`, `./build/bin/bangerd`, and the bundled `./build/runtime/banger-vsock-agent` guest helper.
|
||||
- `make bench-create` benchmarks `vm create` and first-SSH readiness on the current host.
|
||||
- `make runtime-bundle` bootstraps `./build/runtime/` from the archive referenced by `RUNTIME_MANIFEST`; the checked-in `config/runtime-bundle.toml` is only a template.
|
||||
- `make void-kernel` downloads and stages a Void `linux6.12` kernel under `./build/runtime/void-kernel`, including extracted `vmlinux`, raw `vmlinuz`, a matching generated `initramfs`, config, and matching modules.
|
||||
- `make rootfs-void` builds an experimental local-only `x86_64-glibc` Void rootfs plus work-seed under `./build/runtime/`; it prefers staged `./build/runtime/void-kernel` modules when present, but does not replace the default Debian path or teach `banger image build` about Void.
|
||||
- `make verify-void` registers `void-exp` and runs the normal smoke test against that image.
|
||||
- `banger` validates required host tools per command and reports actionable missing-tool errors; do not assume one workstation's package set.
|
||||
- `./build/bin/banger vm create --name testbox` creates and starts a VM.
|
||||
- `./build/bin/banger vm create` now blocks until the guest reaches the daemon's default readiness checks and shows live progress stages on TTY stderr while it waits.
|
||||
- `./build/bin/banger vm ssh testbox` connects to a running guest using the runtime bundle SSH key and reminds the user if the VM is still running when the session exits.
|
||||
- `./build/bin/banger vm stop testbox` stops a VM while preserving its disks.
|
||||
- `./build/bin/banger vm stop vm-a vm-b vm-c` and `./build/bin/banger vm set --nat web-1 web-2` are supported; multi-VM lifecycle and `set` actions fan out concurrently through the CLI.
|
||||
- `./build/bin/banger doctor` reports runtime bundle, host tool, feature, and image-build readiness from the same Go checks used by the daemon.
|
||||
- `./build/bin/banger image register --name local --rootfs /abs/path/rootfs.ext4` creates or updates an unmanaged image record without changing the default image config; use it for experimental guest iteration paths such as Void.
|
||||
- `bangerd` now also serves a localhost web UI on `http://127.0.0.1:7777` by default unless `web_listen_addr = ""` disables it; the UI uses server-rendered templates, polls async VM/image operations, and keeps image path selection on the host via a server-side file picker.
|
||||
- `cmd/banger` and `cmd/bangerd` are the main user entrypoints.
|
||||
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and web UI.
|
||||
- `scripts/` contains explicit manual helper workflows for rootfs and kernel preparation.
|
||||
- `build/bin/` is the canonical source-checkout build output.
|
||||
- `build/manual/` is the canonical source-checkout location for manual rootfs/kernel artifacts.
|
||||
|
||||
## Build and Test
|
||||
|
||||
- `make build` builds `./build/bin/banger`, `./build/bin/bangerd`, and `./build/bin/banger-vsock-agent`.
|
||||
- `make test` runs `go test ./...`.
|
||||
- `./scripts/verify.sh` runs the smoke test for the Go VM workflow.
|
||||
- `./build/bin/banger doctor` checks host readiness.
|
||||
- `./build/bin/banger image build --from-image <image>` builds a managed image from an existing registered image.
|
||||
- `./build/bin/banger image register ...` registers an unmanaged host-side image stack.
|
||||
- `./build/bin/banger image promote <image>` copies an unmanaged image into daemon-owned managed artifacts.
|
||||
- `make void-kernel`, `make rootfs-void`, and `make void-register` drive the experimental Void flow under `./build/manual`.
|
||||
|
||||
## Coding Style & Naming Conventions
|
||||
- Go code should stay small, direct, and standard-library-first unless there is a clear reason otherwise.
|
||||
- Shell helpers use Bash with `set -euo pipefail`; keep remaining shell scripts strict and explicit.
|
||||
- Prefer lowercase filenames with short descriptive names.
|
||||
- Use `gofmt` for Go formatting; no extra formatter is configured for shell files.
|
||||
## Image Model
|
||||
|
||||
- Managed images own the full boot set: rootfs, optional work-seed, kernel, optional initrd, and optional modules.
|
||||
- There is no runtime bundle and no auto-registered default image from disk paths.
|
||||
- `default_image_name` selects a registered image only.
|
||||
|
||||
## Config
|
||||
|
||||
- Config lives at `~/.config/banger/config.toml`.
|
||||
- Firecracker comes from `PATH` by default, or `firecracker_bin`.
|
||||
- SSH uses `ssh_key_path` or an auto-managed default key at `~/.config/banger/ssh/id_ed25519`.
|
||||
|
||||
## Coding Style
|
||||
|
||||
- Prefer small, direct Go code and standard library solutions.
|
||||
- Keep shell scripts strict with `set -euo pipefail`.
|
||||
- Use `gofmt` for Go formatting.
|
||||
|
||||
## Testing Guidance
|
||||
|
||||
## Testing Guidelines
|
||||
- Primary automated coverage is `go test ./...`.
|
||||
- Manual verification for VM lifecycle changes: `./build/bin/banger vm create`, confirm SSH access, then stop/delete the VM.
|
||||
- For host-integration changes, run `./build/bin/banger doctor` as a quick readiness check before the live VM smoke.
|
||||
- The web UI follows the same sudo model as the CLI path: bangerd stays unprivileged and privileged writes only work when `sudo -v` is already warm or sudo is passwordless.
|
||||
- Rebuilt images now include `mise`, `opencode`, a host-reachable default `opencode` server service on guest TCP port `4096`, `tmux-resurrect`/`tmux-continuum` defaults for `root`, and the `banger-vsock-agent` service used by the SSH reminder and guest health-check path; if you change guest provisioning, document whether users need to rebuild `./build/runtime/rootfs-docker.ext4` or another base image to pick it up.
|
||||
- The experimental Void rootfs path now includes the repo's basic dev baseline plus Docker and Compose, alongside boot, SSH, a guest network bootstrap sourced from the kernel `ip=` cmdline, the vsock HTTP health agent, pinned `mise` plus `opencode` for `root`, the default host-reachable `opencode` server service on guest TCP port `4096`, a `bash` root shell while leaving `/bin/sh` alone, and the `/root` work-seed. When `./build/runtime/void-kernel/` exists, the Void image registration path expects a complete staged Void kernel, initramfs, and modules tree and points `void-exp` at it. Keep further baked-in tooling deliberate and user-driven.
|
||||
- Rebuilt images also emit a `work-seed.ext4` sidecar used to speed up future VM creates. Older managed images may take one slower create to refresh seeded SSH access before they rejoin the fast path. If you touch `/root` provisioning, verify both the rootfs and the work-seed output.
|
||||
- The daemon may keep idle TAP devices in a pool for faster creates. Smoke tests should treat `tap-pool-*` devices as reusable capacity, not cleanup leaks.
|
||||
- If you add a new operational workflow, document how to exercise it in `README.md`.
|
||||
- For NAT changes, verify both guest outbound access and host rule cleanup, for example with `./scripts/verify.sh --nat`.
|
||||
- For lifecycle changes, smoke-test with `vm create`, `vm ssh`, `vm stop`, and `vm delete`.
|
||||
- If guest provisioning changes, document whether existing images must be rebuilt or recreated.
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
- Git history uses short, imperative subjects.
|
||||
- Prefer a real commit body when the change affects lifecycle behavior, storage semantics, or host integration.
|
||||
- PRs should call out runtime requirements, migration impact, and any host-side verification performed.
|
||||
## Security
|
||||
|
||||
## Security & Configuration Tips
|
||||
- The VM workflow requires `sudo` and `/dev/kvm` access; do not commit secrets.
|
||||
- `id_ed25519` lives inside the runtime bundle; rotate or replace it before publishing a shared bundle.
|
||||
- Do not commit secrets.
|
||||
- VM workflows require `sudo` and `/dev/kvm`.
|
||||
- The default SSH key is local configuration, not a checked-in runtime artifact.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue