thaloco/banger
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Switch to fetched runtime bundles

Browse source 
Stop treating Firecracker, kernels, modules, and guest images as tracked source files. Source checkouts now resolve runtime assets from ./runtime, while installed binaries keep using ../lib/banger.

Add a small runtimebundle helper plus runtime-bundle.toml so make can bootstrap, package, and install a runtime bundle with checksum validation. Update the shell helpers and daemon path hints to fail clearly when the bundle is missing instead of assuming repo-root artifacts.

This removes the tracked runtime blobs from HEAD in favor of an ignored local runtime/ tree. Verified with go test ./..., make build, bash -n on the shell helpers, make -n install, and a temporary package/fetch smoke test. The manifest URL/SHA still need a published bundle before fresh clones can bootstrap, and history rewrite remains a separate rollout step.
This commit is contained in:
Thales Maciel 2026-03-16 15:05:10 -03:00
parent ce1be52047
commit 238bb8a020
No known key found for this signature in database
GPG key ID: 33112E6833C34679
6512 changed files with 1019 additions and 65372 deletions
Download patch file Download diff file Expand all files Collapse all files

46
AGENTS.md
View file

@ -1,33 +1,39 @@
# Repository Guidelines
## Project Structure & Module Organization
- `run.sh` is the primary launcher script; it builds the per-VM state and configures Firecracker over the local API socket.
- `firecracker`, `vmlinux`, and `rootfs.ext4` are runtime artifacts required to boot the guest.
- `state/` is created at runtime to store per-VM sockets, logs, and metadata (safe to delete when no VMs are running).
- `firecracker.log` is produced by Firecracker; additional per-VM logs live under `state/vm-*/`.
- `cmd/banger` and `cmd/bangerd` are the primary user-facing entrypoints.
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker, and system integration code.
- `customize.sh`, `make-rootfs.sh`, and `interactive.sh` remain as image-build/customization helpers; normal VM lifecycle and NAT management are handled by the Go control plane.
- Source checkouts use a generated `./runtime/` bundle for Firecracker, kernels, modules, rootfs images, and helper copies. 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.
## Build, Test, and Development Commands
- `./run.sh` launches a VM using Firecracker, sets up a bridge/TAP device, and prints the guest IP plus SSH command.
- `ssh -i "./id_ed25519" root@<guest_ip>` connects to the guest once it boots.
- `reboot` (inside the guest) shuts down the VM.
- There is no build step in this repo; binaries and images are checked in.
- `make build` builds `./banger` and `./bangerd`.
- `make runtime-bundle` bootstraps `./runtime/` from `runtime-bundle.toml`.
- `./banger vm create --name testbox` creates and starts a VM.
- `./banger vm ssh testbox` connects to a running guest.
- `./banger vm stop testbox` stops a VM while preserving its disks.
- `./banger tui` launches the terminal UI.
- `make test` runs `go test ./...`.
- `./verify.sh` runs the smoke test for the Go VM workflow.
## Coding Style & Naming Conventions
- Shell scripts use Bash with `set -euo pipefail`; keep new scripts strict and explicit.
- Indentation is two spaces in `run.sh`; match existing formatting and quoting style.
- Filenames are short and descriptive (e.g., `run.sh`, `rootfs.ext4`). Prefer lowercase with dashes or dots.
- No formatter or linter is configured; keep changes small and readable.
- 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.
## Testing Guidelines
- No automated test framework is present.
- Manual verification: run `./run.sh`, confirm the guest boots, and verify SSH access.
- If adding tests, document how to run them in this file and keep them self-contained.
- Primary automated coverage is `go test ./...`.
- Manual verification for VM lifecycle changes: `./banger vm create`, confirm SSH access, then stop/delete the VM.
- 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 `./verify.sh --nat`.
## Commit & Pull Request Guidelines
- Git history uses short, informal commit summaries (e.g., "ignore", "Document expected log noise").
- Prefer imperative, single-line subjects; keep them under ~50 characters when possible.
- PRs should describe the change, list any new runtime requirements, and include logs or screenshots if behavior changes.
- 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 & Configuration Tips
- The script requires `sudo` and `/dev/kvm` access; avoid committing secrets or private keys.
- `id_ed25519` is a local SSH key for the guest; rotate or replace it if sharing the repository.
- 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.