Mikhail ChusavitinandClaude Sonnet 5
b8c45d54c1
Booting via BMC virtual CD reads the ~2.8 GB filesystem squashfs sequentially during the live-boot toram copy; a mid-read drop of the redirected medium loses the whole copy and fails the boot (v14). Split the rootfs into self-contained semantic layers so a retry re-reads at most one ~500-700 MiB layer, not everything. This is a resilience / reduced-re-read mechanism, not a fix for the virtual-media instability. NVIDIA variants now ship 7 layers (00-base, 05-firmware, 08-desktop, 10-nvidia-driver, 20-nvidia-platform, 30-nvidia-cuda-libs, 40-nvidia-dcgm-cuda) plus an explicit live/filesystem.module that fixes their OverlayFS order; amd/nogpu keep a single squashfs. - lib/squashfs-layers.sh: deterministic classifier (dpkg file ownership plus explicit rules for build.sh-injected files, never a path substring), per-layer mksquashfs, 800 MiB hard ceiling, unsquashfs -s plus strict extraction of every layer, merged-rootfs bootability check. - build.sh: split the monolith after the full lb build, verify and merge, write the module file, delete the monolith only then; abort before ISO assembly on any failure. Runs the builder test suites up front. - fast-path: force a full build for a multi-layer medium; fast_path_repack_squashfs hard-refuses (it would drop layers). - iso-validation.sh: validate_iso_squashfs_layers (module vs layer set match, size ceiling, no lone giant squashfs) and validate_iso_media_integrity (xorriso -check_media). - bee-install: honour filesystem.module order, abort on any layer failure. - 9013-toram-retry: record the real rsync exit code (it printed a false rc=0) and correct the "resumes the tail" comment (rsync without --partial keeps only fully-copied layers). No unsafe partial resume. - tests: test-squashfs-layers.sh plus a multi-layer guard in test-build-libs.sh; both run at the top of every build. - docs: bible-local architecture and decision, iso/README, iso-build-rules. Verified by a full nvidia build: 7 layers 622/199/256/466/37/567/562 MiB, every validator passes, xorriso -check_media good, merged rootfs bootable. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# 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/`.
|