diff --git a/custom-recipes/buildernet/mkosi/README.md b/custom-recipes/buildernet/mkosi/README.md index 0637560..9d40180 100644 --- a/custom-recipes/buildernet/mkosi/README.md +++ b/custom-recipes/buildernet/mkosi/README.md @@ -8,10 +8,10 @@ Run a BuilderNet VM alongside builder-playground's L1 network. The playground ma - **Linux with KVM** (macOS is not supported) - **Docker** (for the L1 network stack) -- **QEMU** with KVM support (`qemu-system-x86_64`) +- **QEMU** with KVM support (`qemu-system-x86_64`, `qemu-utils`) - **UEFI firmware** (`edk2-ovmf` or equivalent) - **socat** (for VM console access) -- **jq**, **curl** +- **jq**, **curl**, **unzip** Verify KVM is available: @@ -29,39 +29,42 @@ curl -sSfL https://raw.githubusercontent.com/flashbots/builder-playground/main/i mkdir buildernet-dev && cd buildernet-dev builder-playground generate buildernet/mkosi -# 3. Point to the VM image binary -# - alternatively you can edit playground.yaml -# - you can point to local disk or URL -export BUILDERNET_IMAGE=flashbots-images/path/buildernet-playground.qcow2 +# 3. Point to the VM image +# - you can point to a local file or URL +# - alternatively you can set this in playground.yaml (see below) +export BUILDERNET_IMAGE=/path/to/buildernet-qemu.qcow2 -# 4. Start +# 4. Start (runs L1 Docker stack + VM in the background) builder-playground start playground.yaml --bind-external --detached -# 5. Verify by sending transaction +# 5. Wait for the VM to boot (~60-90s) then check readiness +./scripts/operator-api-health.sh # repeat until you see "OK" + +# 6. Verify by sending a transaction builder-playground test --rpc http://localhost:18645 --el-rpc http://localhost:8545 ``` -If the test transaction is included in a block, the full pipeline is working: transaction reaches rbuilder inside the VM, rbuilder builds a block, and it lands on the L1 chain. - -## Using Your Own Image +If the test transaction is included in a block and the Extra Data shows `Playground VM Builder`, the full pipeline is working: transaction reaches rbuilder inside the VM, rbuilder builds a block, and it lands on the L1 chain. -For developers working on [flashbots-images](https://github.com/flashbots/flashbots-images) who want to test VM changes against a local network. - -Build the image in your flashbots-images checkout using the **playground** mkosi profile, then point `BUILDERNET_IMAGE` to it: +You can also set `BUILDERNET_IMAGE` in `playground.yaml` instead of using an environment variable: ```yaml # In playground.yaml, under builder > env: env: - BUILDERNET_IMAGE: "/path/to/buildernet-qemu_latest.qcow2" + BUILDERNET_IMAGE: "/path/to/buildernet-qemu.qcow2" ``` -Or override via environment variable: +## Building Your Own Image + +For developers working on [flashbots-images](https://github.com/flashbots/flashbots-images) who want to test VM changes against a local network. + +Build the image in your flashbots-images checkout using the **playground** mkosi profile, then point `BUILDERNET_IMAGE` to the output: ```bash -export BUILDERNET_IMAGE=/path/to/buildernet-qemu_latest.qcow2 +export BUILDERNET_IMAGE=/path/to/flashbots-images/mkosi.output/buildernet-qemu_latest.qcow2 ``` -See the [flashbots-images](https://github.com/flashbots/flashbots-images) repository for build environment setup, available profiles, and customization options. +See the [flashbots-images](https://github.com/flashbots/flashbots-images) repository for build environment setup, available profiles, and customization options. You can also look at [`./scripts/build.sh`](scripts/build.sh) for a reference on how to clone and build the image. ## VM Management @@ -79,6 +82,22 @@ See the [flashbots-images](https://github.com/flashbots/flashbots-images) reposi ./scripts/console.sh # Serial console (exit: Ctrl+]) ``` +### Logs + +VM serial output (kernel, systemd, service logs) is captured to `.runtime/console.log`: + +```bash +tail -f .runtime/console.log +``` + +For operator-api event logs (rbuilder lifecycle, config fetches, etc.): + +```bash +./scripts/operator-api-logs.sh +``` + +For Docker service logs (Reth, Lighthouse, mev-boost-relay, etc.), use `builder-playground logs`. + ### Environment Variables | Variable | Default | Description | @@ -108,7 +127,7 @@ Available actions: `reboot`, `rbuilder_restart`, `rbuilder_stop`, `fetch_config` # Stop just the VM (Docker keeps running) ./scripts/stop.sh -# Stop everything +# Stop everything (use `builder-playground list` to find the session name) builder-playground stop # Full cleanup @@ -116,8 +135,6 @@ builder-playground clean ./scripts/clean.sh ``` -Use `builder-playground list` to find the session name. - ## Ports ### VM (QEMU host forwarding) diff --git a/custom-recipes/buildernet/mkosi/scripts/build.sh b/custom-recipes/buildernet/mkosi/scripts/build.sh index bfcd717..55f55bf 100755 --- a/custom-recipes/buildernet/mkosi/scripts/build.sh +++ b/custom-recipes/buildernet/mkosi/scripts/build.sh @@ -1,15 +1,32 @@ #!/usr/bin/env bash -# Build the BuilderNet VM image +# Clone flashbots-images (if needed) and build the BuilderNet VM image set -eu -o pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_DIR="${SCRIPT_DIR}/.." FLASHBOTS_IMAGES_DIR="${PROJECT_DIR}/.flashbots-images" +FLASHBOTS_IMAGES_REPO="https://github.com/flashbots/flashbots-images.git" +FLASHBOTS_IMAGES_BRANCH="${FLASHBOTS_IMAGES_BRANCH:-main}" if [[ ! -d "${FLASHBOTS_IMAGES_DIR}" ]]; then - echo "Error: flashbots-images not found. Run ./scripts/sync.sh first." - exit 1 + echo "Cloning flashbots-images (branch: ${FLASHBOTS_IMAGES_BRANCH})..." + git clone --branch "${FLASHBOTS_IMAGES_BRANCH}" "${FLASHBOTS_IMAGES_REPO}" "${FLASHBOTS_IMAGES_DIR}" fi -make -C "${FLASHBOTS_IMAGES_DIR}" build-playground +# Setup mkosi if needed +MKOSI_COMMIT=$(cat "${FLASHBOTS_IMAGES_DIR}/.mkosi_version") +VENV="${FLASHBOTS_IMAGES_DIR}/.venv" +MKOSI="${VENV}/bin/mkosi" + +if [[ ! -x "${MKOSI}" ]]; then + echo "Setting up mkosi (commit: ${MKOSI_COMMIT})..." + python3 -m venv "${VENV}" + "${VENV}/bin/pip" install -q --upgrade pip + "${VENV}/bin/pip" install -q "git+https://github.com/systemd/mkosi.git@${MKOSI_COMMIT}" + echo "Installed: $(${MKOSI} --version)" +fi + +echo "Building playground image..." +cd "${FLASHBOTS_IMAGES_DIR}" +${MKOSI} --force -I buildernet.conf --profile="devtools,playground" diff --git a/custom-recipes/buildernet/mkosi/scripts/sync.sh b/custom-recipes/buildernet/mkosi/scripts/sync.sh deleted file mode 100755 index 066ff65..0000000 --- a/custom-recipes/buildernet/mkosi/scripts/sync.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/usr/bin/env bash -# Clone or update flashbots-images repository -set -eu -o pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_DIR="${SCRIPT_DIR}/.." - -FLASHBOTS_IMAGES_DIR="${PROJECT_DIR}/.flashbots-images" -FLASHBOTS_IMAGES_BRANCH="fryd/mkosi-playground" -FLASHBOTS_IMAGES_REPO="https://github.com/flashbots/flashbots-images.git" - -if [[ ! -d "${FLASHBOTS_IMAGES_DIR}" ]]; then - git clone --branch "${FLASHBOTS_IMAGES_BRANCH}" "${FLASHBOTS_IMAGES_REPO}" "${FLASHBOTS_IMAGES_DIR}" -else - git -C "${FLASHBOTS_IMAGES_DIR}" fetch origin - git -C "${FLASHBOTS_IMAGES_DIR}" checkout "${FLASHBOTS_IMAGES_BRANCH}" - git -C "${FLASHBOTS_IMAGES_DIR}" pull origin "${FLASHBOTS_IMAGES_BRANCH}" -fi