archy/BUILD-GUIDE.md

# Quick Build Guide - Archipelago Beta Release

## Prerequisites

Make sure you have:
- Docker or Podman installed
- `xorriso` installed (for ISO creation)
- Access to dev server: archipelago@192.168.1.228

**Note**: When building on the target server with `sudo`, the script will automatically install missing dependencies (`xorriso`, `podman`).

## Build Auto-Installer ISO

### Option 1: Build on Target Server (Recommended)

```bash
# SSH to target server
ssh archipelago@192.168.1.228

# Navigate to project
cd ~/archy/image-recipe

# Run build (auto-installs missing deps)
sudo ./build-auto-installer-iso.sh

# Copy ISO back to your Mac
# On your Mac:
scp archipelago@192.168.1.228:~/archy/image-recipe/results/archipelago-auto-installer-*.iso .
```

### Option 2: Build from Mac (requires Docker)

**Important**: This requires Docker Desktop installed on macOS.

```bash
cd /Users/dorian/Projects/archy/image-recipe

# Capture current live server state
DEV_SERVER=archipelago@192.168.1.228 ./build-auto-installer-iso.sh

# ISO will be created in: results/archipelago-auto-installer-*.iso
```

## What the ISO Includes

✅ Complete Debian 13 root filesystem  
✅ Pre-built Archipelago backend  
✅ Pre-built frontend (web UI)  
✅ **Prepackaged container images** (Bitcoin Knots, LND, UIs, and other bundled apps), loaded on first boot  
✅ Nginx configuration (HTTPS ready)  
✅ Auto-installer that:
  - Detects internal disk
  - Creates partitions (EFI + root)
  - Extracts pre-built system
  - Installs bootloader
  - Reboots to working system

## What Users Need to Do Post-Install

1. **Start apps from the Web UI** – Container images are prepackaged and loaded on first boot. Bitcoin Knots + UI, LND + UI, and other bundled apps are ready to start from the Web UI without manual `podman run`. No need to pull or deploy core containers.

2. **Access Web UI** – Navigate to `http://[server-ip]`

## Testing the ISO

```bash
# Use VirtualBox, QEMU, or real hardware
qemu-system-x86_64 \
  -m 4G \
  -cdrom results/archipelago-auto-installer-*.iso \
  -hda archipelago-test.qcow2 \
  -boot d
```

## Important Notes

⚠️ **The auto-installer will ERASE the target disk!**  
⚠️ Make sure to test on a non-production machine first  
⚠️ Minimum 20GB disk space required (500GB+ recommended for Bitcoin)

## Build from Source (Alternative)

If you want to build everything from scratch instead of capturing the live server:

```bash
BUILD_FROM_SOURCE=1 ./build-auto-installer-iso.sh
```

This will:
- Build backend from Rust source
- Build frontend with `npm run build`
- Create fresh SSL certificates
- Generate default configs

## Troubleshooting

**ISO won't boot:**
- Ensure UEFI mode is enabled
- Try disabling Secure Boot

**Installer hangs:**
- Check the auto-start script fix is applied (see DEPLOYMENT.md)

**Backend doesn't detect containers:**
- Verify `/etc/sudoers.d/archipelago-podman` exists
- Check backend can run `sudo podman ps`

## Version Naming

ISOs are automatically named with timestamp:
```
archipelago-auto-installer-YYYYMMDD-HHMMSS.iso
```

For releases, rename to:
```
archipelago-v0.1.0-beta.1.iso
```

## Next Steps After Building

1. Test the ISO on VM
2. Verify web UI loads
3. Test container deployment
4. Document any issues
5. Tag the release in git
6. Upload ISO to distribution point