archy/.claude/skills/build-iso/SKILL.md

---
name: build-iso
description: Build Archipelago auto-installer ISOs. Custom debootstrap base (no Debian Live dependency), live-boot for squashfs root, hybrid BIOS+UEFI boot, Archipelago branding. Use when user says "build ISO", "build image", "create installer", or needs to work on the ISO build pipeline.
allowed-tools: Bash, Read, Edit, Write, Grep, Glob, Agent
---

# Build Archipelago ISO

## Architecture (dev-iso branch)

Custom debootstrap-based installer. NO Debian Live ISO download.

| Component | Source | Size |
|-----------|--------|------|
| Installer squashfs | debootstrap --variant=minbase + live-boot | ~180MB |
| Target rootfs | Docker build (Debian bookworm, full stack) | ~1.5GB compressed |
| Kernel + initramfs | From debootstrap, with live-boot hooks | ~50MB |
| GRUB + ISOLINUX | Built from packages during Step 2 | ~1MB |
| **Total ISO** | **Unbundled** | **~2.2GB** |

## Build Pipeline (6 Steps)

**Step 1** (lines ~200-430): Build target rootfs via Docker
- Debian bookworm + all runtime packages (podman, nginx, tor, chromium, etc.)
- `--no-install-recommends` for size reduction
- Strips docs/man/locales
- Output: `archipelago-rootfs.tar` (~1.5GB)

**Step 2** (lines ~430-710): Build installer environment via debootstrap
- `debootstrap --variant=minbase` inside a container
- Installs live-boot via chroot (NOT --include — minbase can't resolve it)
- Custom initramfs with live-boot hooks
- Builds GRUB EFI image with grub-mkimage
- Creates ISOLINUX files, EFI boot image
- Installs GRUB theme + background
- Output: vmlinuz, initrd.img, filesystem.squashfs, BOOTX64.EFI, efi.img, isolinux.bin

**Step 3** (lines ~710-850): Add Archipelago components
- Backend binary, web UI, rootfs.tar, scripts, Plymouth theme

**Step 3b** (lines ~850-1230): Bundle container images (skipped if UNBUNDLED=1)

**Step 4** (lines ~1230-2380): Generate auto-install.sh
- Embedded installer script (~1100 lines)
- Disk detection, partitioning, LUKS encryption, GRUB install
- Installs GRUB + Plymouth theme on target

**Step 5** (lines ~2380-2460): Configure boot loaders
- Write GRUB config (boot=live components)
- Write ISOLINUX config
- Both reference kernel at /live/vmlinuz

**Step 6** (lines ~2460-2540): Create final ISO
- xorriso with hybrid BIOS+UEFI boot
- Uses proven MBR from `branding/isohdpfx.bin`
- `-partition_offset 16` for UEFI compatibility

## CI Workflow

**Branch**: `dev-iso` → `.gitea/workflows/build-iso-dev.yml`
**Branch**: `main` → `.gitea/workflows/build-iso.yml`

Dev CI includes a smoke test step that verifies:
- All critical files present in ISO
- Initrd contains live-boot scripts
- grub.cfg has boot=live
- Fails build before copying to Builds if any check fails

## Critical Rules

1. **MBR**: Always use `branding/isohdpfx.bin` (Debian Live MBR, starts with `4552`). The ISOLINUX generic MBR (`33ed`) doesn't boot on all hardware.

2. **live-boot**: Must be installed via `chroot /installer apt-get install` AFTER debootstrap completes. The `--include` flag silently fails for live-boot.

3. **Initramfs**: `update-initramfs` needs `/proc`, `/sys`, `/dev` bind-mounted in the chroot. Without them, the initramfs is broken.

4. **scripts/live is a FILE**: Verify with `[ -e ]` not `[ -d ]`.

5. **Kernel params**: Must include `boot=live components`. Without `boot=live`, live-boot hooks never activate.

6. **partition_offset 16**: Required in xorriso for UEFI firmware to recognize the USB.

7. **Never push during a running CI build**: The gitea-runner kills in-progress builds when a new commit arrives on the same branch.

## Quick Commands

```bash
# Build locally (on .228):
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228
cd ~/archy/image-recipe
sudo UNBUNDLED=1 DEV_SERVER=localhost BUILD_FROM_SOURCE=0 ./build-auto-installer-iso.sh

# Check build status:
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  "ps aux | grep build-auto | grep -v grep"

# Check latest ISO:
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  "ls -lt /var/lib/archipelago/filebrowser/Builds/archipelago-dev-*.iso | head -3"

# Verify ISO:
# See /iso-debug skill for the full verification checklist

# Iterate on branding without rebuilding:
./image-recipe/dev-branding.sh [path-to-iso]
# Or: ./scripts/dev-start.sh → option 0
```

## Key Files

| File | Role |
|------|------|
| `image-recipe/build-auto-installer-iso.sh` | Main build script (~2600 lines) |
| `image-recipe/build-unbundled-iso.sh` | Wrapper: sets UNBUNDLED=1 |
| `image-recipe/branding/isohdpfx.bin` | Proven MBR (432 bytes) |
| `image-recipe/branding/grub-theme/` | GRUB theme + background |
| `image-recipe/branding/plymouth-theme/` | Plymouth boot splash |
| `scripts/image-versions.sh` | Pinned container image versions |
| `.gitea/workflows/build-iso-dev.yml` | CI for dev-iso branch |
| `image-recipe/test-iso-qemu.sh` | QEMU test script |
| `image-recipe/dev-branding.sh` | Quick branding iteration |