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:

# 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:

# Find your USB device
diskutil list

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

Build Options

./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

# 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)
• Node.js 18+ installed (nodejs.org)
• xorriso for ISO creation (brew install xorriso on macOS)
• Admin/sudo access for ISO creation

Troubleshooting

Backend Build Fails

# Check Rust installation
cargo --version

# Update Rust
rustup update

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

Frontend Build Fails

# 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

# 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

# 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

# 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

# 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

# Edit both, then full rebuild:
./build-iso-complete.sh --remote archipelago@192.168.1.228

Testing Changes Without ISO Build

# 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:

# 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