Thales Maciel
8bcc767824
Refresh guest opencode auth from the host at VM start so guest opencode can reuse the local login without baking secrets into managed images. Reuse the existing work-disk preparation path to copy ~/.local/share/opencode/auth.json into /root/.local/share/opencode/auth.json with mode 0600, and warn and skip when the host file is missing or unreadable so any existing guest auth stays in place. Add daemon coverage for copy, replacement, and warn-and-skip cases, document the restart behavior in the README, and validate with go test ./... plus make build. Existing VMs pick the new auth up on their next restart.
238 lines
4.6 KiB
Markdown
238 lines
4.6 KiB
Markdown
# banger
|
|
|
|
`banger` manages Firecracker development VMs with a local daemon, managed image artifacts, and a localhost web UI.
|
|
|
|
## Requirements
|
|
|
|
- Linux with `/dev/kvm`
|
|
- `sudo`
|
|
- Firecracker installed on `PATH`, or `firecracker_bin` set in config
|
|
- The usual host tools checked by `./build/bin/banger doctor`
|
|
|
|
`banger` now owns complete managed image sets. A managed image includes:
|
|
|
|
- `rootfs`
|
|
- optional `work-seed`
|
|
- `kernel`
|
|
- optional `initrd`
|
|
- optional `modules`
|
|
|
|
There is no runtime bundle anymore.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
This writes:
|
|
|
|
- `./build/bin/banger`
|
|
- `./build/bin/bangerd`
|
|
- `./build/bin/banger-vsock-agent`
|
|
|
|
## Install
|
|
|
|
```bash
|
|
make install
|
|
```
|
|
|
|
That installs:
|
|
|
|
- `banger`
|
|
- `bangerd`
|
|
- the `banger-vsock-agent` companion helper under `../lib/banger/`
|
|
|
|
## Config
|
|
|
|
Config lives at `~/.config/banger/config.toml`.
|
|
|
|
Supported keys:
|
|
|
|
- `log_level`
|
|
- `web_listen_addr`
|
|
- `firecracker_bin`
|
|
- `ssh_key_path`
|
|
- `default_image_name`
|
|
- `auto_stop_stale_after`
|
|
- `stats_poll_interval`
|
|
- `metrics_poll_interval`
|
|
- `bridge_name`
|
|
- `bridge_ip`
|
|
- `cidr`
|
|
- `tap_pool_size`
|
|
- `default_dns`
|
|
|
|
If `ssh_key_path` is unset, banger creates and uses:
|
|
|
|
- `~/.config/banger/ssh/id_ed25519`
|
|
|
|
`default_image_name` now only means “use this registered image when `vm create` omits `--image`”. The daemon does not auto-register images from host paths.
|
|
|
|
## Core Workflow
|
|
|
|
Check the host:
|
|
|
|
```bash
|
|
./build/bin/banger doctor
|
|
```
|
|
|
|
Register an existing host-side image stack:
|
|
|
|
```bash
|
|
./build/bin/banger image register \
|
|
--name base \
|
|
--rootfs /abs/path/rootfs.ext4 \
|
|
--kernel /abs/path/vmlinux \
|
|
--initrd /abs/path/initrd.img \
|
|
--modules /abs/path/modules
|
|
```
|
|
|
|
Build a managed image from an existing registered image:
|
|
|
|
```bash
|
|
./build/bin/banger image build \
|
|
--name devbox \
|
|
--from-image base \
|
|
--docker
|
|
```
|
|
|
|
Promote an unmanaged image into daemon-owned managed artifacts:
|
|
|
|
```bash
|
|
./build/bin/banger image promote base
|
|
```
|
|
|
|
Create and use a VM:
|
|
|
|
```bash
|
|
./build/bin/banger vm create --image devbox --name testbox
|
|
./build/bin/banger vm ssh testbox
|
|
./build/bin/banger vm stop testbox
|
|
```
|
|
|
|
`vm create` stays synchronous by default, but on a TTY it now shows live progress until the VM is fully ready.
|
|
|
|
## Web UI
|
|
|
|
`bangerd` serves a local web UI by default at:
|
|
|
|
- `http://127.0.0.1:7777`
|
|
|
|
See the effective URL with:
|
|
|
|
```bash
|
|
./build/bin/banger daemon status
|
|
```
|
|
|
|
Disable it with:
|
|
|
|
```toml
|
|
web_listen_addr = ""
|
|
```
|
|
|
|
## Guest Services
|
|
|
|
Provisioned images include:
|
|
|
|
- `banger-vsock-agent`
|
|
- guest networking bootstrap
|
|
- `mise`
|
|
- `opencode`
|
|
- a default guest `opencode` service on `0.0.0.0:4096`
|
|
|
|
If host `~/.local/share/opencode/auth.json` exists, `banger` syncs it into the guest at `/root/.local/share/opencode/auth.json` on VM start. Changes on the host take effect after the VM is restarted.
|
|
|
|
From the host:
|
|
|
|
```bash
|
|
./build/bin/banger vm ports testbox
|
|
opencode attach http://<guest-ip>:4096
|
|
```
|
|
|
|
## Manual Helpers
|
|
|
|
The shell helpers are now explicit manual workflows under `./build/manual`.
|
|
|
|
Rebuild a Debian-style manual rootfs:
|
|
|
|
```bash
|
|
make rootfs ARGS='--base-rootfs /abs/path/rootfs.ext4 --kernel /abs/path/vmlinux --initrd /abs/path/initrd.img --modules /abs/path/modules'
|
|
```
|
|
|
|
The output lands in:
|
|
|
|
- `./build/manual/rootfs-docker.ext4`
|
|
- `./build/manual/rootfs-docker.work-seed.ext4`
|
|
|
|
## Experimental Void Flow
|
|
|
|
Stage a Void kernel:
|
|
|
|
```bash
|
|
make void-kernel
|
|
```
|
|
|
|
Build the experimental Void rootfs:
|
|
|
|
```bash
|
|
make rootfs-void
|
|
```
|
|
|
|
Register it:
|
|
|
|
```bash
|
|
make void-register
|
|
```
|
|
|
|
That flow uses:
|
|
|
|
- `./build/manual/void-kernel/`
|
|
- `./build/manual/rootfs-void.ext4`
|
|
- `./build/manual/rootfs-void.work-seed.ext4`
|
|
|
|
## Experimental Alpine Flow
|
|
|
|
Stage an Alpine virt kernel:
|
|
|
|
```bash
|
|
make alpine-kernel
|
|
```
|
|
|
|
Build the experimental Alpine rootfs:
|
|
|
|
```bash
|
|
make rootfs-alpine
|
|
```
|
|
|
|
Register it:
|
|
|
|
```bash
|
|
make alpine-register
|
|
```
|
|
|
|
Create a VM from it:
|
|
|
|
```bash
|
|
./build/bin/banger vm create --image alpine --name alpine-dev
|
|
```
|
|
|
|
That flow uses:
|
|
|
|
- `./build/manual/alpine-kernel/`
|
|
- `./build/manual/rootfs-alpine.ext4`
|
|
- `./build/manual/rootfs-alpine.work-seed.ext4`
|
|
|
|
The experimental Alpine flow stages a pinned Alpine release by default. Override
|
|
that pin with `ALPINE_RELEASE=...` when running the `make alpine-kernel` and
|
|
`make rootfs-alpine` helpers if you need a different patch release.
|
|
|
|
Alpine support currently applies to the explicit register-and-run flow above.
|
|
The generic `banger image build --from-image ...` path remains Debian/systemd-
|
|
oriented and should not be treated as an Alpine image builder.
|
|
|
|
## Notes
|
|
|
|
- Firecracker is resolved from `PATH` by default.
|
|
- Managed image delete removes the daemon-owned artifact dir.
|
|
- The companion vsock helper is internal to the install/build layout, not a user-configured runtime path.
|