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)

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

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

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

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