Thales Maciel
2362d0ae39
Add a localhost-only web console so VM and image management no longer depends on the CLI for every inspection and lifecycle action. Wire bangerd up to a configurable web listener, expose dashboard and async image-build state through the daemon, and serve CSRF-protected HTML pages with host-path picking, VM/image detail views, logs, ports, and progress polling for long-running operations. Keep the browser path aligned with the existing sudo and host-owned artifact model: surface sudo readiness, print the web URL in daemon status, and document the new workflow. Polish the UI with resource usage cards, clearer clickable affordances, cancel paths, confirmation prompts, image-name links, and HTTP port links. Validation: GOCACHE=/tmp/banger-gocache go test ./...
55 lines
6.4 KiB
Markdown
55 lines
6.4 KiB
Markdown
# 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`.
|
|
- `customize.sh`, `make-rootfs.sh`, and `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 `./runtime/` bundle for Firecracker, kernels, modules, rootfs images, and helper copies. Bundle defaults come from `./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.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `make build` builds `./banger`, `./bangerd`, and the bundled `./runtime/banger-vsock-agent` guest helper.
|
|
- `make bench-create` benchmarks `vm create` and first-SSH readiness on the current host.
|
|
- `make runtime-bundle` bootstraps `./runtime/` from the archive referenced by `RUNTIME_MANIFEST`; the checked-in `runtime-bundle.toml` is only a template.
|
|
- `make void-kernel` downloads and stages a Void `linux6.12` kernel under `./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 `./runtime/`; it prefers staged `./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.
|
|
- `./banger vm create --name testbox` creates and starts a VM.
|
|
- `./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.
|
|
- `./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.
|
|
- `./banger vm stop testbox` stops a VM while preserving its disks.
|
|
- `./banger vm stop vm-a vm-b vm-c` and `./banger vm set --nat web-1 web-2` are supported; multi-VM lifecycle and `set` actions fan out concurrently through the CLI.
|
|
- `./banger doctor` reports runtime bundle, host tool, feature, and image-build readiness from the same Go checks used by the daemon.
|
|
- `./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.
|
|
- `make test` runs `go test ./...`.
|
|
- `./verify.sh` runs the smoke test for the Go VM workflow.
|
|
|
|
## 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.
|
|
|
|
## Testing Guidelines
|
|
- Primary automated coverage is `go test ./...`.
|
|
- Manual verification for VM lifecycle changes: `./banger vm create`, confirm SSH access, then stop/delete the VM.
|
|
- For host-integration changes, run `./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 `./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 `./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 `./verify.sh --nat`.
|
|
|
|
## 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 & 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.
|