---
name: build-iso
description: Build a new Archipelago auto-installer ISO image (bundled or unbundled)
disable-model-invocation: true
allowed-tools: Bash, Read
---

Build a new Archipelago auto-installer ISO.

## Pre-build checklist

1. Latest code deployed to server (`/deploy` first)
2. System configs synced (`/sync-configs` first)
3. Everything tested and working on live server
4. Sync build scripts to server before building:
   ```bash
   rsync -avz -e "ssh -i ~/.ssh/archipelago-deploy" \
     /Users/dorian/Projects/archy/image-recipe/build-auto-installer-iso.sh \
     /Users/dorian/Projects/archy/image-recipe/build-unbundled-iso.sh \
     archipelago@192.168.1.228:~/archy/image-recipe/
   ```

## Build variants

### Unbundled ISO (recommended for distribution — ~3GB)
No pre-bundled container images. Apps install on-demand from Marketplace (requires internet).

```bash
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  'cd ~/archy/image-recipe && sudo ./build-unbundled-iso.sh'
```

Output: `results/archipelago-installer-unbundled-x86_64.iso`

### Full bundled ISO (~11GB)
All container images pre-bundled for offline install.

```bash
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  'cd ~/archy/image-recipe && sudo ./build-auto-installer-iso.sh'
```

Output: `results/archipelago-installer-x86_64.iso`

## Post-build: ALWAYS publish to FileBrowser

After EVERY successful build, copy the ISO to the FileBrowser `Builds` folder so it's downloadable from the web UI. This is mandatory — do not skip.

**FileBrowser data root**: `/var/lib/archipelago/filebrowser/`

```bash
# For unbundled:
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  'sudo mkdir -p /var/lib/archipelago/filebrowser/Builds && \
   sudo cp ~/archy/image-recipe/results/archipelago-installer-unbundled-x86_64.iso /var/lib/archipelago/filebrowser/Builds/ && \
   sudo chown 1000:1000 /var/lib/archipelago/filebrowser/Builds/archipelago-installer-unbundled-x86_64.iso'

# For bundled:
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  'sudo mkdir -p /var/lib/archipelago/filebrowser/Builds && \
   sudo cp ~/archy/image-recipe/results/archipelago-installer-x86_64.iso /var/lib/archipelago/filebrowser/Builds/ && \
   sudo chown 1000:1000 /var/lib/archipelago/filebrowser/Builds/archipelago-installer-x86_64.iso'
```

## Post-build: Download to Mac (optional)

```bash
# Unbundled:
scp -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228:~/archy/image-recipe/results/archipelago-installer-unbundled-x86_64.iso ~/Downloads/

# Bundled:
scp -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228:~/archy/image-recipe/results/archipelago-installer-x86_64.iso ~/Downloads/
```

## Key paths on server

- Build scripts: `~/archy/image-recipe/build-auto-installer-iso.sh`, `build-unbundled-iso.sh`
- Build output: `~/archy/image-recipe/results/`
- Build cache (rootfs, base ISO): `~/archy/image-recipe/build/auto-installer/`
- FileBrowser Builds: `/var/lib/archipelago/filebrowser/Builds/`

## Notes

- Use `--rebuild` flag to force rootfs rebuild (otherwise uses cached)
- FileBrowser container mounts `/var/lib/archipelago/filebrowser` → `/srv`
- Always `chown 1000:1000` files in FileBrowser so the app can serve them
- **IMPORTANT**: Use `build-auto-installer-iso.sh` (or `build-unbundled-iso.sh`) only. The deprecated `build-debian-iso.sh` causes boot-to-prompt issues.