Thales Maciel
38d7eac430
New VMs should come up with tmux session persistence ready instead of requiring per-VM plugin setup, and rebuilt images should stop carrying stale Docker installer scraps. Configure both image build paths to install TPM, tmux-resurrect, and tmux-continuum for root, manage a marked /root/.tmux.conf block with autosave enabled and restore left manual, and remove legacy get-docker helper files during provisioning. Update the README and repo guidance to document the rebuilt-image behavior. Verified with bash -n customize.sh, GOCACHE=/tmp/banger-gocache go test ./internal/daemon -run TestBuildProvisionScriptInstallsDefaultTools, and GOCACHE=/tmp/banger-gocache make build.
42 lines
3.1 KiB
Markdown
42 lines
3.1 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.
|
|
- `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` and `./bangerd`.
|
|
- `make runtime-bundle` bootstraps `./runtime/` from the archive referenced by `RUNTIME_MANIFEST`; the checked-in `runtime-bundle.toml` is only a template.
|
|
- `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 ssh testbox` connects to a running guest.
|
|
- `./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 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
|
|
- 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.
|
|
- Rebuilt images now include `mise`, `opencode`, and `tmux-resurrect`/`tmux-continuum` defaults for `root`; if you change guest provisioning, document whether users need to rebuild `./runtime/rootfs-docker.ext4` or another base image to pick it up.
|
|
- 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.
|