Build Artifacts on macOS (x86 VM)#

This guide walks you through running the Phase 1 build on a macOS machine (any chip) using a Ubuntu 24.04 x86_64 virtual machine in UTM.

The build scripts require Linux. macOS is not directly supported. This guide uses UTM (free) with Ubuntu 24.04 Desktop x86_64 as the build environment.

Performance note: On Apple Silicon Macs, UTM runs x86_64 VMs via QEMU software emulation (TCG) — there is no KVM hardware acceleration for x86 on ARM hosts. The build will complete correctly but will be 3–5× slower than on native x86 hardware. On Intel Macs, QEMU can use HVF acceleration and runs at near-native speed.

Prerequisites#

What

Where

macBook (any chip — Apple Silicon or Intel)

—

macOS Ventura or later

—

UTM (free VM app)

https://mac.getutm.app

Ubuntu 24.04 Server amd64 ISO

https://releases.ubuntu.com/24.04/

64 GB free disk space

For VM + build output

12 GB RAM free

8 GB assigned to VM minimum

Step 1 — Install UTM#

  1. Go to https://mac.getutm.app and click Download.

  2. Open the downloaded .dmg and drag UTM to your Applications folder.

  3. Open UTM. If macOS blocks it: right-click → Open → Open again.

Step 2 — Download Ubuntu 24.04 Server amd64#

Download the Server amd64 ISO from the Ubuntu releases page:

https://releases.ubuntu.com/noble/ubuntu-24.04.4-live-server-amd64.iso

File: ubuntu-24.04.4-live-server-amd64.iso (3.2 GB)

Use the server ISO — the build runs entirely in a terminal inside Docker containers. No desktop environment is needed, and the server ISO is half the size and installs in roughly a third of the time.

Step 3 — Create the Ubuntu VM in UTM#

  1. Open UTM → click Create a New Virtual Machine.

  2. Select Emulate (not Virtualize — x86_64 emulation is required on Apple Silicon; on Intel Mac you may use Virtualize with HVF for better performance).

  3. Select Linux.

  4. Under Boot ISO Image → Browse → select the amd64 ISO you downloaded.

  5. Set:

    • Architecture: x86_64

    • RAM: 8192 MB

    • CPU cores: 12

    • Storage: 64 GB

  6. Click Save.

Step 4 — Install Ubuntu in the VM#

  1. Click ▶ Play in UTM to start the VM.

  2. Follow the text-based server installer — accept defaults for everything except:

    • Set a username and password you will remember.

    • On the storage screen confirm Use entire disk.

    • On the profile screen set your name, server name, username, and password.

  3. When prompted, select Install OpenSSH server (optional but useful).

  4. Let the install complete (~8–12 min under emulation) and reboot into the VM.

  5. Log in with your username and password at the terminal prompt.

Step 5 — Install Prerequisites Inside the VM#

Open a terminal inside the Ubuntu VM.

Docker#

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Allow your user to run docker without sudo
sudo usermod -aG docker $USER
newgrp docker

Verify:

docker run --rm hello-world

Make and Git#

sudo apt install -y make git

Step 6 — Clone the Repository#

git clone https://github.com/open-edge-platform/edge-node-infrastructure-blueprint.git
cd edge-node-infrastructure-blueprint

Step 7 — Configure Proxy (corporate networks only)#

If your network requires a proxy, edit proxy.env in the repo root:

nano proxy.env

Fill in:

HTTP_PROXY="http://proxy.mycompany.com:8080"
HTTPS_PROXY="http://proxy.mycompany.com:8080"
NO_PROXY="localhost,127.0.0.0/8"
http_proxy="http://proxy.mycompany.com:8080"
https_proxy="http://proxy.mycompany.com:8080"
no_proxy="localhost,127.0.0.0/8"

On a home or open network, leave all values empty — the build will prompt and you can confirm to proceed without a proxy.

Step 8 — Build the USB Artifacts#

Run from the repository root inside the VM:

make build

This is equivalent to make build MODE=standard-image. No extra flags are required — the VM is native x86_64 so all Docker images build and run correctly without any cross-compilation or QEMU user-static setup.

The first build downloads base images, installs packages, and assembles the USB artifacts. Expected duration:

Mac type

Estimated build time

Apple Silicon (QEMU TCG emulation)

2–3 hours

Intel Mac (HVF acceleration)

15–30 minutes

Total end-to-end time on Apple Silicon (UTM setup + Ubuntu install + build): approximately 2–3 hours for a first-time run after the VM is already set up, or 4–5 hours including VM creation and Ubuntu installation.

Build output appears at:

infrastructure/build-artifacts/out/usb-installation-files.tar.gz

Step 9 — Prepare the Bootable USB#

Plug your USB drive into the Mac. In UTM, pass it through to the VM:

  1. With the VM running, click the USB icon in the UTM toolbar.

  2. Select your USB drive from the list to pass it through to the VM.

Inside the VM, identify the USB device:

lsblk

Look for a device like /dev/sda or /dev/sdb with the USB’s capacity.

Extract the build output and run the USB preparation script:

cd infrastructure/build-artifacts/out

sudo tar -xzf usb-installation-files.tar.gz

# Replace /dev/sdX with your actual USB device from lsblk
sudo ./bootable-usb-prepare.sh /dev/sdX usb-bootable-files.tar.gz config-file

Double-check the device path — this will erase the target device.

After the script completes:

  1. In UTM, click the USB icon and disconnect the drive from the VM.

  2. Safely eject it from macOS.

  3. Connect the USB to the target edge node.

  4. Enter the BIOS/UEFI boot menu and boot from the USB.

Troubleshooting#

Symptom

Cause

Fix

Cannot run docker without sudo

User not in docker group

sudo usermod -aG docker $USER && newgrp docker

docker pull fails / timeout

Proxy not configured

Fill in proxy.env before running make build

VM very slow / unresponsive

QEMU TCG on Apple Silicon

Reduce VM RAM to free host memory; close other apps; increase VM CPU cores

UTM VM freezes during Docker build

Insufficient disk

Ensure VM disk is ≥ 64 GB; delete old Docker images with docker system prune

USB device not visible in VM

Not passed through UTM

Click USB icon in UTM toolbar → select the drive

Build fails on Intel Mac with KVM not available

HVF not enabled

In UTM VM settings → CPU → enable Force Multicore and set Architecture to x86_64