docs: add UTM VM setup guide for macOS developers #42
Conversation
Add instructions and scripts for running Hypeman in a UTM virtual machine with nested KVM virtualization on Apple Silicon Macs (M3+ required). - Add scripts/utm/README.md with step-by-step UTM VM setup guide - Add scripts/utm/download-iso.sh to download Ubuntu Server ARM64 ISO - Add scripts/utm/setup-vm.sh to provision VM with Hypeman dependencies - Update DEVELOPMENT.md with note directing macOS users to UTM guide - Add .gitignore entry for downloaded ISO files - Minor markdown formatting improvements in DEVELOPMENT.md
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
|
|
||
| # Install Go | ||
| echo "[4/10] Installing Go..." | ||
| if go version 2>/dev/null | grep -q "go1.2"; then |
There was a problem hiding this comment.
Go version check accepts older incompatible versions
The version check grep -q "go1.2" is too permissive. It matches any Go version containing "go1.2" as a substring (1.20, 1.21, 1.22, 1.23, 1.24, 1.25), so if a developer has Go 1.20-1.24 installed, the script will skip installation and report success, leaving them with a Go version that doesn't meet the project's 1.25.4+ requirement from go.mod. This would cause confusing build failures.
| @@ -0,0 +1,137 @@ | |||
| #!/bin/bash | |||
| # | |||
| # Provision the VM with Hypeman dependencies | |||
There was a problem hiding this comment.
recommend name script to disambiguate it's a VM for developing or running hypeman (versus running a VM inside hypeman or something else)
| # Configure KVM access | ||
| echo "[7/10] Configuring KVM..." | ||
| sudo chmod 666 /dev/kvm 2>/dev/null || true | ||
| sudo usermod -aG kvm "$(whoami)" 2>/dev/null || true |
There was a problem hiding this comment.
I see it's not running the install script because it ends with "make dev". While reading I was wondering if this would be a nice way to check the installer script works without a special host touch before running (e.g. if forget to include a setup step like enable kernel routing in installer script, would be easy to notice without always deploying a fresh VM and try it)
There was a problem hiding this comment.
also I guess a lot of the installer script is duplicated in this file, so we have to keep adding here and in the installer script for future host setup items
There was a problem hiding this comment.
yeah this is more "set up a hypeman dev env" script which could probably share stuff with the install script but i dunno... seems fine to keep them separate for now vs. trying to make an option on the install script to make it also serve the purpose of setting up a dev machine
Clarifies that this script sets up a dev environment for working on Hypeman, not a VM running inside Hypeman.
Summary
Add instructions and scripts for running Hypeman in a UTM virtual machine with nested KVM virtualization on Apple Silicon Macs.
Changes
scripts/utm/README.md- Step-by-step guide for setting up a UTM VM with Ubuntu Server and nested KVMscripts/utm/download-iso.sh- Helper script to download Ubuntu Server ARM64 ISOscripts/utm/setup-vm.sh- Provisioning script that installs Go, erofs-utils, dnsmasq, and clones onkernel reposDEVELOPMENT.md- Added callout note in Prerequisites directing macOS users to the UTM guide.gitignore- Ignore downloaded ISO filesRequirements
Testing
Tested the full setup flow on an M3 MacBook Pro running macOS Sequoia.
Note
Adds UTM-based macOS development setup docs and scripts, updates DEVELOPMENT.md with clarifications and telemetry setup tweaks, and ignores downloaded ISOs.
Adds a complete UTM-based macOS dev environment.
scripts/utm/README.mdwith step-by-step UTM VM setup; helperdownload-iso.sh; provisioningbootstrap-dev-environment.sh(installs deps, configures KVM/IP forwarding, clones repos).DEVELOPMENT.md: macOS callout; reformatted env var table; clarified uplink discovery; improved LGTM setup with bind/YOLO options; minor wording/formatting fixes.scripts/utm/images/(downloaded ISOs).Written by Cursor Bugbot for commit d8074b8. This will update automatically on new commits. Configure here.