Skip to content

Commit 00f2be9

Browse files
nathsudinathsudi
authored
Merge branch 'main' into nathsudi/ci
2 parents 991455c + 2edf13e commit 00f2be9

4 files changed

Lines changed: 242 additions & 2 deletions

File tree

‎.github/workflows/post-merge.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
security-events: write
2323
id-token: write
2424
actions: read
25-
uses: open-edge-platform/orch-ci/.github/workflows/post-merge.yml@db3a4eb9966dd1cba2061c16a94d769b7fccf243 # 2026.1.3
25+
uses: open-edge-platform/orch-ci/.github/workflows/post-merge.yml@af6d3ab68ed04ec1b3111392ec0844e8e1ac83a5 # 2026.1.3
2626
with:
2727
run_build: false
2828
run_version_check: true

‎.github/workflows/security-scan-on-tag.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ jobs:
1919
security-events: write
2020
id-token: write
2121
actions: read
22-
uses: open-edge-platform/orch-ci/.github/workflows/post-merge.yml@db3a4eb9966dd1cba2061c16a94d769b7fccf243
22+
uses: open-edge-platform/orch-ci/.github/workflows/post-merge.yml@af6d3ab68ed04ec1b3111392ec0844e8e1ac83a5
2323
with:
2424
run_build: false
2525
run_version_tag: false

‎docs/user-guide/how-to/build-on-macos-x86.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
<!--
2+
SPDX-FileCopyrightText: (C) 2026 Intel Corporation
3+
SPDX-License-Identifier: Apache-2.0
4+
-->
5+
6+
# Build Artifacts on macOS (x86 VM)
7+
8+
This guide walks you through running the Phase 1 build on a **macOS** machine (any chip)
9+
using a Ubuntu 24.04 x86_64 virtual machine in UTM.
10+
11+
> The build scripts require Linux. macOS is not directly supported.
12+
> This guide uses UTM (free) with Ubuntu 24.04 Desktop x86_64 as the build environment.
13+
14+
> **Performance note:** On Apple Silicon Macs, UTM runs x86_64 VMs via QEMU software
15+
> emulation (TCG) — there is no KVM hardware acceleration for x86 on ARM hosts.
16+
> The build will complete correctly but will be **3–5× slower** than on native x86
17+
> hardware. On Intel Macs, QEMU can use HVF acceleration and runs at near-native speed.
18+
19+
---
20+
21+
## Prerequisites
22+
23+
| What | Where |
24+
|------|-------|
25+
| macBook (any chip — Apple Silicon or Intel) | — |
26+
| macOS Ventura or later | — |
27+
| UTM (free VM app) | https://mac.getutm.app |
28+
| Ubuntu 24.04 **Server** amd64 ISO | https://releases.ubuntu.com/24.04/ |
29+
| 64 GB free disk space | For VM + build output |
30+
| 12 GB RAM free | 8 GB assigned to VM minimum |
31+
32+
---
33+
34+
## Step 1 — Install UTM
35+
36+
1. Go to **https://mac.getutm.app** and click **Download**.
37+
2. Open the downloaded `.dmg` and drag **UTM** to your Applications folder.
38+
3. Open UTM. If macOS blocks it: right-click → **Open** → **Open** again.
39+
40+
---
41+
42+
## Step 2 — Download Ubuntu 24.04 Server amd64
43+
44+
Download the **Server amd64 ISO** from the Ubuntu releases page:
45+
46+
```
47+
https://releases.ubuntu.com/noble/ubuntu-24.04.4-live-server-amd64.iso
48+
```
49+
50+
File: `ubuntu-24.04.4-live-server-amd64.iso` (3.2 GB)
51+
52+
> Use the **server** ISO — the build runs entirely in a terminal inside Docker
53+
> containers. No desktop environment is needed, and the server ISO is half the
54+
> size and installs in roughly a third of the time.
55+
56+
---
57+
58+
## Step 3 — Create the Ubuntu VM in UTM
59+
60+
1. Open UTM → click **Create a New Virtual Machine**.
61+
2. Select **Emulate** (not Virtualize — x86_64 emulation is required on Apple Silicon;
62+
on Intel Mac you may use Virtualize with HVF for better performance).
63+
3. Select **Linux**.
64+
4. Under **Boot ISO Image** → Browse → select the amd64 ISO you downloaded.
65+
5. Set:
66+
- **Architecture**: x86_64
67+
- **RAM**: 8192 MB
68+
- **CPU cores**: 12
69+
- **Storage**: 64 GB
70+
6. Click **Save**.
71+
72+
---
73+
74+
## Step 4 — Install Ubuntu in the VM
75+
76+
1. Click **▶ Play** in UTM to start the VM.
77+
2. Follow the text-based server installer — accept defaults for everything except:
78+
- Set a username and password you will remember.
79+
- On the storage screen confirm **Use entire disk**.
80+
- On the profile screen set your name, server name, username, and password.
81+
3. When prompted, select **Install OpenSSH server** (optional but useful).
82+
4. Let the install complete (~8–12 min under emulation) and reboot into the VM.
83+
5. Log in with your username and password at the terminal prompt.
84+
85+
---
86+
87+
## Step 5 — Install Prerequisites Inside the VM
88+
89+
Open a terminal inside the Ubuntu VM.
90+
91+
### Docker
92+
93+
```bash
94+
sudo apt update
95+
sudo apt install -y ca-certificates curl gnupg lsb-release
96+
97+
sudo install -m 0755 -d /etc/apt/keyrings
98+
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
99+
| sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
100+
101+
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] \
102+
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
103+
| sudo tee /etc/apt/sources.list.d/docker.list
104+
105+
sudo apt update
106+
sudo apt install -y docker-ce docker-ce-cli containerd.io \
107+
docker-buildx-plugin docker-compose-plugin
108+
109+
# Allow your user to run docker without sudo
110+
sudo usermod -aG docker $USER
111+
newgrp docker
112+
```
113+
114+
Verify:
115+
116+
```bash
117+
docker run --rm hello-world
118+
```
119+
120+
### Make and Git
121+
122+
```bash
123+
sudo apt install -y make git
124+
```
125+
126+
---
127+
128+
## Step 6 — Clone the Repository
129+
130+
```bash
131+
git clone https://github.com/open-edge-platform/edge-node-infrastructure-blueprint.git
132+
cd edge-node-infrastructure-blueprint
133+
```
134+
135+
---
136+
137+
## Step 7 — Configure Proxy (corporate networks only)
138+
139+
If your network requires a proxy, edit `proxy.env` in the repo root:
140+
141+
```bash
142+
nano proxy.env
143+
```
144+
145+
Fill in:
146+
147+
```
148+
HTTP_PROXY="http://proxy.mycompany.com:8080"
149+
HTTPS_PROXY="http://proxy.mycompany.com:8080"
150+
NO_PROXY="localhost,127.0.0.0/8"
151+
http_proxy="http://proxy.mycompany.com:8080"
152+
https_proxy="http://proxy.mycompany.com:8080"
153+
no_proxy="localhost,127.0.0.0/8"
154+
```
155+
156+
On a home or open network, leave all values empty — the build will prompt and
157+
you can confirm to proceed without a proxy.
158+
159+
---
160+
161+
## Step 8 — Build the USB Artifacts
162+
163+
Run from the repository root inside the VM:
164+
165+
```bash
166+
make build
167+
```
168+
169+
This is equivalent to `make build MODE=standard-image`. No extra flags are required —
170+
the VM is native x86_64 so all Docker images build and run correctly without any
171+
cross-compilation or QEMU user-static setup.
172+
173+
The first build downloads base images, installs packages, and assembles the USB
174+
artifacts. Expected duration:
175+
176+
| Mac type | Estimated build time |
177+
|---|---|
178+
| Apple Silicon (QEMU TCG emulation) | 2–3 hours |
179+
| Intel Mac (HVF acceleration) | 15–30 minutes |
180+
181+
> **Total end-to-end time on Apple Silicon** (UTM setup + Ubuntu install + build):
182+
> approximately **2–3 hours** for a first-time run after the VM is already set up,
183+
> or **4–5 hours** including VM creation and Ubuntu installation.
184+
185+
Build output appears at:
186+
187+
```
188+
infrastructure/build-artifacts/out/usb-installation-files.tar.gz
189+
```
190+
191+
---
192+
193+
## Step 9 — Prepare the Bootable USB
194+
195+
Plug your USB drive into the Mac. In UTM, pass it through to the VM:
196+
197+
1. With the VM running, click the **USB icon** in the UTM toolbar.
198+
2. Select your USB drive from the list to pass it through to the VM.
199+
200+
Inside the VM, identify the USB device:
201+
202+
```bash
203+
lsblk
204+
```
205+
206+
Look for a device like `/dev/sda` or `/dev/sdb` with the USB's capacity.
207+
208+
Extract the build output and run the USB preparation script:
209+
210+
```bash
211+
cd infrastructure/build-artifacts/out
212+
213+
sudo tar -xzf usb-installation-files.tar.gz
214+
215+
# Replace /dev/sdX with your actual USB device from lsblk
216+
sudo ./bootable-usb-prepare.sh /dev/sdX usb-bootable-files.tar.gz config-file
217+
```
218+
219+
> **Double-check the device path** — this will erase the target device.
220+
221+
After the script completes:
222+
223+
1. In UTM, click the USB icon and disconnect the drive from the VM.
224+
2. Safely eject it from macOS.
225+
3. Connect the USB to the target edge node.
226+
4. Enter the BIOS/UEFI boot menu and boot from the USB.
227+
228+
---
229+
230+
## Troubleshooting
231+
232+
| Symptom | Cause | Fix |
233+
|---|---|---|
234+
| `Cannot run docker without sudo` | User not in `docker` group | `sudo usermod -aG docker $USER && newgrp docker` |
235+
| `docker pull` fails / timeout | Proxy not configured | Fill in `proxy.env` before running `make build` |
236+
| VM very slow / unresponsive | QEMU TCG on Apple Silicon | Reduce VM RAM to free host memory; close other apps; increase VM CPU cores |
237+
| UTM VM freezes during Docker build | Insufficient disk | Ensure VM disk is ≥ 64 GB; delete old Docker images with `docker system prune` |
238+
| USB device not visible in VM | Not passed through UTM | Click USB icon in UTM toolbar → select the drive |
239+
| 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 |

‎docs/user-guide/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ IoT processing, and real-time applications at the network edge.
3737
3838
Get Started <get-started.md>
3939
Advanced Image Customization <how-to/advanced-image-customization.md>
40+
Build on macOS (x86 VM) <how-to/build-on-macos-x86.md>
4041
Container Device Interface Guide <how-to/configure-cdi.md>
4142
GPU and NPU Device Plugins <how-to/configure-device-plugins.md>
4243
DL Streamer Pipelines Guide <how-to/build-dlstreamer-pipelines.md>

0 commit comments

Comments
 (0)