# ISO Build

`bee` ISO is built inside a Debian 12 builder container via `iso/builder/build-in-container.sh`.

## Requirements

- Docker Desktop or another Docker-compatible container runtime
- Privileged containers enabled
- Enough free disk space for builder cache, Debian live-build artifacts, NVIDIA driver cache, and CUDA userspace packages

## Build On macOS

From the repository root:

```sh
sh iso/builder/build-in-container.sh
```

The script defaults to `linux/amd64` builder containers, so it works on:

- Intel Mac
- Apple Silicon (`M1` / `M2` / `M3` / `M4`) via Docker Desktop's Linux VM

You do not need to pass `--platform` manually for normal ISO builds.

## Useful Options

Build with explicit SSH keys baked into the ISO:

```sh
sh iso/builder/build-in-container.sh --authorized-keys ~/.ssh/id_ed25519.pub
```

Force a clean rebuild of the builder image and build caches:

```sh
sh iso/builder/build-in-container.sh --clean-build
```

Use a custom cache directory:

```sh
sh iso/builder/build-in-container.sh --cache-dir /path/to/cache
```

## Notes

- The builder image is automatically rebuilt if the local tag exists for the wrong architecture.
- The live ISO boots with Debian `live-boot` `toram`, so the read-only medium is copied into RAM during boot and the runtime no longer depends on the original USB/BMC virtual media staying present.
- The NVIDIA variants ship the root filesystem as several semantic SquashFS layers (`live/filesystem-v<ver>-NN-*.squashfs`) plus an explicit `live/filesystem.module` that fixes their OverlayFS order. This bounds the data a `toram` retry must re-read after a virtual-media drop; it is not a fix for virtual-media instability. `amd` / `nogpu` keep a single squashfs. See `bible-local/architecture/squashfs-layers.md`.
- The builder splits the layers deterministically after the full `lb build`, verifies each one, re-merges them into a bootable rootfs, and only then deletes the monolith. The fast path is disabled for a multi-layer medium (it forces a full build).
- Target systems require at least 16 GB of installed RAM for the full compressed live medium plus normal runtime overhead. On supported hardware, do not classify a mid-copy failure as low RAM without direct `ENOSPC`, OOM, or tmpfs-limit evidence.
- The NVIDIA variant installs DCGM 4 packages matched to the CUDA user-mode driver major version. For driver branch `580` / CUDA `13.x`, the package family is `datacenter-gpu-manager-4-cuda13` rather than legacy `datacenter-gpu-manager`.
- Override the container platform only if you know why:

```sh
BEE_BUILDER_PLATFORM=linux/amd64 sh iso/builder/build-in-container.sh
```

- The shipped ISO is still `amd64`.
- Output ISO artifacts are written under `dist/`.