archy/BUILD-GUIDE.md

# Archipelago ISO Build System

Complete, robust build system for creating flashable Archipelago ISO images from source.

## Quick Start

### One-Command Build (Recommended)

Build everything and create a flashable ISO with a single command:

```bash
# Build on remote server (recommended for x86_64 target)
./build-iso-complete.sh --remote archipelago@192.168.1.228

# Or build locally (if you have Rust + Node.js)
./build-iso-complete.sh --local
```

### Flash to USB

After building:

```bash
# Find your USB device
diskutil list

# Flash (will prompt for confirmation)
./flash-to-usb.sh /dev/diskN
```

## Build Options

```bash
./build-iso-complete.sh [options]
```

### Options

- `--local` - Build everything on your local machine
- `--remote HOST` - Build on remote server (e.g., `archipelago@192.168.1.228`)
- `--skip-backend` - Skip backend compilation (use existing binary)
- `--skip-frontend` - Skip frontend build (use existing dist)
- `--clean` - Clean all build artifacts before building
- `--help` - Show help message

### Examples

```bash
# Full clean build on remote server
./build-iso-complete.sh --remote archipelago@192.168.1.228 --clean

# Quick rebuild with existing backend
./build-iso-complete.sh --remote archipelago@192.168.1.228 --skip-backend

# Local build (requires Rust + Node.js installed)
./build-iso-complete.sh --local

# Clean local build
./build-iso-complete.sh --local --clean
```

## What the Script Does

The build script automates the entire ISO creation process:

### 1. **Backend Build** (Rust)
   - Compiles `core/archipelago` to native binary
   - Can build locally or on remote server
   - Outputs to `image-recipe/build/backend/archipelago`

### 2. **Frontend Build** (Vue.js + Vite)
   - Builds `neode-ui` to static assets
   - Includes PWA manifest and service worker
   - Outputs to `image-recipe/build/frontend/`

### 3. **ISO Creation** (Debian Live)
   - Downloads base Debian 12 Live ISO
   - Integrates backend binary and frontend assets
   - Configures auto-start and services
   - Creates bootable ISO at `image-recipe/results/archipelago-debian-12-x86_64.iso`

### 4. **Verification**
   - Validates all build artifacts exist
   - Generates MD5 checksum
   - Reports file sizes

## Build Artifacts

```
image-recipe/
├── build/
│   ├── backend/
│   │   └── archipelago           # Compiled Rust binary
│   └── frontend/                 # Built Vue.js assets
│       ├── index.html
│       ├── assets/
│       └── ...
├── results/
│   └── archipelago-debian-12-x86_64.iso  # Final bootable ISO
└── iso-workdir/                  # Temporary ISO build files (auto-cleaned)
```

## Requirements

### For Remote Build (Recommended)
- SSH access to build server
- `rsync` installed locally
- Build server must have:
  - Rust/Cargo (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
  - Node.js/npm (`curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -`)
  - Build tools (`sudo apt install build-essential`)

### For Local Build
- macOS or Linux
- Rust/Cargo installed ([rustup.rs](https://rustup.rs))
- Node.js 18+ installed ([nodejs.org](https://nodejs.org))
- `xorriso` for ISO creation (`brew install xorriso` on macOS)
- Admin/sudo access for ISO creation

## Troubleshooting

### Backend Build Fails
```bash
# Check Rust installation
cargo --version

# Update Rust
rustup update

# Clean and rebuild
./build-iso-complete.sh --remote HOST --clean
```

### Frontend Build Fails
```bash
# Check Node.js version (need 18+)
node --version

# Clean node_modules
cd neode-ui
rm -rf node_modules package-lock.json
npm install
cd ..

# Rebuild
./build-iso-complete.sh --remote HOST --clean
```

### ISO Build Fails
```bash
# Check available disk space (needs ~2GB)
df -h

# Ensure build artifacts exist
ls -lh image-recipe/build/backend/
ls -lh image-recipe/build/frontend/

# Try with sudo
cd image-recipe
sudo bash build-debian-iso.sh
```

### Remote Connection Issues
```bash
# Test SSH connection
ssh archipelago@192.168.1.228

# Test rsync
rsync --version

# Use SSH key for passwordless access
ssh-copy-id archipelago@192.168.1.228
```

## Build Time Estimates

| Step | Time (First Build) | Time (Incremental) |
|------|-------------------|-------------------|
| Backend compile | 3-5 minutes | 30 seconds |
| Frontend build | 1-2 minutes | 20 seconds |
| ISO download | 5-10 minutes | 0 (cached) |
| ISO creation | 2-3 minutes | 2-3 minutes |
| **Total** | **11-20 minutes** | **3-4 minutes** |

## Development Workflow

### Making Changes to Backend
```bash
# Edit Rust code in core/archipelago/src/
# Then rebuild:
./build-iso-complete.sh --remote archipelago@192.168.1.228 --skip-frontend
```

### Making Changes to Frontend
```bash
# Edit Vue.js code in neode-ui/src/
# Then rebuild:
./build-iso-complete.sh --remote archipelago@192.168.1.228 --skip-backend
```

### Making Changes to Both
```bash
# Edit both, then full rebuild:
./build-iso-complete.sh --remote archipelago@192.168.1.228
```

### Testing Changes Without ISO Build
```bash
# Backend (on development server)
cd core/archipelago
cargo run

# Frontend (local development)
cd neode-ui
npm run dev
```

## CI/CD Integration

The build script is designed for automation:

```yaml
# Example GitHub Actions workflow
name: Build ISO
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build ISO
        run: ./build-iso-complete.sh --local
      - name: Upload ISO
        uses: actions/upload-artifact@v3
        with:
          name: archipelago-iso
          path: image-recipe/results/*.iso
```

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│  build-iso-complete.sh (Orchestrator)                   │
└─────────────────┬───────────────────────────────────────┘
                  │
        ┌─────────┼─────────┐
        │         │         │
   ┌────▼───┐ ┌──▼───┐ ┌───▼────────┐
   │Backend │ │Front │ │ISO Builder │
   │(Rust)  │ │(Vue) │ │(Debian)    │
   └────┬───┘ └──┬───┘ └───┬────────┘
        │        │         │
        └────────┼─────────┘
                 │
        ┌────────▼────────┐
        │ Bootable ISO    │
        │ (1.2 GB)        │
        └─────────────────┘
```

## Output

Successful build produces:

```
✅ ISO ready for flashing!

  📀 ISO:      /Users/dorian/Projects/archy/image-recipe/results/archipelago-debian-12-x86_64.iso
  📏 Size:     1.2G
  🔐 MD5:      a3f2d8c9e4b1...

Next steps:

  1. Insert USB drive
  2. Find device: diskutil list
  3. Flash ISO:

     cd image-recipe && ./write-usb-dd.sh /dev/diskN

  4. Boot from USB on target device
```

## Support

For issues or questions:
- Check the troubleshooting section above
- Review logs in `image-recipe/iso-workdir/build.log`
- Open an issue on GitHub

## License

Same as Archipelago project - see main LICENSE file