# 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.
- Target systems need enough RAM for the full compressed live medium plus normal runtime overhead, or boot may fail before reaching the TUI.
- The NVIDIA variant installs DCGM 4 packages matched to the CUDA user-mode driver major version. For driver branch `590` / 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/`.
