Thales Maciel
8029b2e1bc
Lead the README with `banger vm run` (one command, auto-pull default image + kernel from the catalogs), move `image register` / `image build` / OCI-pull to a "power-user flows" section. Golden-image content from customize.sh moves to the golden-image Dockerfile story. New `docs/image-catalog.md` mirrors `docs/kernel-catalog.md` — the bundle format, content-addressed filenames, publish flow, trust model, R2 hosting. Cross-links with oci-import.md. `docs/oci-import.md` refactored to document the OCI-pull path as the fallthrough for arbitrary registry refs (it's the secondary path now that the catalog covers the headline debian-bookworm case). Phase A caveats removed — ownership fixup, agent injection, and first-boot sshd install all landed. AGENTS.md: promotes `vm run` as the smoke-test primitive, notes the default-image auto-pull behaviour, and points at both catalog docs. README shrinks 330 → 198 lines, mostly by removing the experimental void/alpine sections (those flows still work as advanced scripts but the README no longer advertises them). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
# Repository Guidelines
|
|
|
|
Always run `make build` before commit.
|
|
|
|
## Project Structure
|
|
|
|
- `cmd/banger` and `cmd/bangerd` are the main user entrypoints.
|
|
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and the experimental web UI.
|
|
- `internal/daemon/` is the composition root; pure helpers live in its subpackages (`opstate`, `dmsnap`, `fcproc`, `imagemgr`, `session`, `workspace`). See `internal/daemon/ARCHITECTURE.md`.
|
|
- `internal/imagecat/` and `internal/kernelcat/` embed the image + kernel catalogs.
|
|
- `images/golden/` is the Dockerfile for the `debian-bookworm` catalog entry.
|
|
- `scripts/` contains manual helper workflows for rootfs, kernel, and bundle 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 ./...`.
|
|
- `make lint` runs `gofmt -l`, `go vet ./...`, and `shellcheck --severity=error` on `scripts/*.sh`. Run before commits.
|
|
- `./build/bin/banger doctor` checks host readiness.
|
|
- `./build/bin/banger vm run` is the primary user-facing entry point — auto-pulls the default image + kernel from the catalogs if missing.
|
|
- `./build/bin/banger image pull <name>` uses the bundle catalog (fast) when `<name>` is a catalog entry, or falls through to the OCI path for arbitrary registry refs. See `docs/image-catalog.md` and `docs/oci-import.md`.
|
|
- `./build/bin/banger image register ...` registers an unmanaged host-side image stack.
|
|
- `./build/bin/banger image build --from-image <image>` builds a managed image from an existing one.
|
|
- `./build/bin/banger image promote <image>` copies an unmanaged image into daemon-owned managed artifacts.
|
|
- `scripts/make-generic-kernel.sh` builds a Firecracker-optimized vmlinux from upstream sources. `scripts/publish-kernel.sh <name>` publishes it to the kernel catalog.
|
|
- `scripts/publish-golden-image.sh` rebuilds + publishes the golden image bundle and patches the image catalog.
|
|
|
|
## Image Model
|
|
|
|
- Managed images own the full boot set: rootfs, optional work-seed, kernel, optional initrd, and optional modules.
|
|
- The image catalog ships pre-built bundles. `vm run` auto-pulls the default catalog entry; `image pull <name>` can be invoked explicitly.
|
|
- `default_image_name` defaults to `debian-bookworm`. On miss, the daemon auto-pulls from `imagecat` before surfacing "not found".
|
|
- Kernel references follow the same auto-pull pattern against `kernelcat`.
|
|
|
|
## 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.
|
|
- When a CLI accepts either an inline string or a file input, always prefer the file-based form.
|
|
- For shell commands and AI/LLM tooling, prefer passing files as input whenever the CLI allows it.
|
|
- Create temporary files as needed to follow the file-first rule.
|
|
- Examples: use `git commit -F <file>` instead of `git commit -m <message>`, and use prompt files instead of inline prompt strings when invoking LLM CLIs.
|
|
|
|
## Testing Guidance
|
|
|
|
- Primary automated coverage is `go test ./...`.
|
|
- For lifecycle changes, smoke-test with `vm run` end-to-end (covers create + start + boot + ssh).
|
|
- If guest provisioning changes, document whether existing images must be rebuilt or recreated.
|
|
|
|
## Security
|
|
|
|
- Do not commit secrets.
|
|
- VM workflows require `sudo` and `/dev/kvm`.
|
|
- The default SSH key is local configuration, not a checked-in runtime artifact.
|