# Archipelago Hardware Build System - Quick Reference

## 🚀 Quick Start

### Build for Start9 Server Pure
```bash
cd image-recipe
./build-for-hardware.sh start9-pure iso
```

### Build for HP ProDesk
```bash
cd image-recipe
./build-for-hardware.sh hp-prodesk iso
```

### Build for Dell OptiPlex
```bash
cd image-recipe
./build-for-hardware.sh dell-optiplex iso
```

### Build for All Hardware
```bash
cd image-recipe
./build-all-hardware.sh iso
```

## 📋 Supported Hardware

| Hardware | Target Name | CPU | RAM | Storage |
|----------|-------------|-----|-----|---------|
| Start9 Server Pure | `start9-pure` | Intel i7-10710U | 32-64GB | 2-4TB NVMe |
| HP ProDesk 400 G4 DM | `hp-prodesk` | Intel varies | 8GB+ | 128GB+ SSD |
| Dell OptiPlex | `dell-optiplex` | Intel varies | 8GB+ | 128GB+ SSD |
| Generic x86_64 | `generic` | Any x86_64 | 8GB+ | 128GB+ |

## 🔧 Build Commands

### Single Hardware Target
```bash
./build-for-hardware.sh <target> [iso|disk]
```

**Examples:**
```bash
# ISO image (recommended)
./build-for-hardware.sh start9-pure iso

# Disk image (advanced)
./build-for-hardware.sh start9-pure disk

# Default is ISO
./build-for-hardware.sh hp-prodesk
```

### All Hardware Targets
```bash
./build-all-hardware.sh [iso|disk]
```

Builds optimized images for all supported hardware in one command.

## 📦 Output Files

After build completes:

```
results/
├── archipelago-0.1.0-start9-pure-x86_64.iso
├── archipelago-0.1.0-hp-prodesk-x86_64.iso
├── archipelago-0.1.0-dell-optiplex-x86_64.iso
├── archipelago-0.1.0-generic-x86_64.iso
├── BUILD_MANIFEST_start9-pure.txt
├── BUILD_MANIFEST_hp-prodesk.txt
├── BUILD_MANIFEST_dell-optiplex.txt
└── BUILD_MANIFEST_generic.txt
```

## 🔍 What's Different Per Hardware?

Each build includes **hardware-specific optimizations**:

### Start9 Server Pure
- ✅ Intel i7-10710U microcode
- ✅ Intel UHD Graphics drivers
- ✅ NVMe SSD optimizations
- ✅ Coreboot firmware support
- ✅ IME-disabled configurations
- ✅ High-performance tuning

### HP ProDesk 400 G4 DM
- ✅ Intel graphics support
- ✅ HP firmware compatibility
- ✅ SATA/NVMe detection
- ✅ Compact form factor optimizations
- ✅ Low-power configurations

### Dell OptiPlex
- ✅ Multi-model support
- ✅ Dell firmware compatibility
- ✅ Legacy hardware support
- ✅ Business-class features

### Generic
- ✅ Broad hardware compatibility
- ✅ Intel & AMD CPU support
- ✅ Generic drivers
- ✅ Maximum portability

## 💾 Flash to USB Drive

### macOS
```bash
# Find device
diskutil list

# Unmount
diskutil unmountDisk /dev/diskX

# Flash
sudo dd if=results/archipelago-0.1.0-start9-pure-x86_64.iso \
        of=/dev/rdiskX bs=1m status=progress
```

### Linux
```bash
# Find device
lsblk

# Flash
sudo dd if=results/archipelago-0.1.0-start9-pure-x86_64.iso \
        of=/dev/sdX bs=1M status=progress
```

### GUI Tools
- **balenaEtcher** (Recommended): https://www.balena.io/etcher/
- **Rufus** (Windows): https://rufus.ie/

## 🎯 Installation Steps

1. **Flash ISO to USB** (see above)
2. **Insert USB into target hardware**
3. **Boot from USB**:
   - Start9 Pure: Press F12
   - HP ProDesk: Press F9
   - Dell OptiPlex: Press F12
4. **Follow installation prompts**
5. **Remove USB and reboot**
6. **Access UI**: http://device-ip:8100

## 🔬 Verification

### Check ISO
```bash
# View build manifest
cat results/BUILD_MANIFEST_start9-pure.txt

# Check file size
ls -lh results/*.iso

# Verify checksum
sha256sum results/archipelago-0.1.0-start9-pure-x86_64.iso
```

### Test in VM
```bash
qemu-system-x86_64 \
    -m 4G \
    -smp 2 \
    -boot d \
    -cdrom results/archipelago-0.1.0-start9-pure-x86_64.iso \
    -enable-kvm
```

## 🛠️ Environment Variables

Customize builds:

```bash
# Set version
export ARCHIPELAGO_VERSION="0.2.0"

# Set Alpine version
export ALPINE_VERSION="3.19"

# Build with custom settings
./build-for-hardware.sh start9-pure iso
```

## 📂 Directory Structure

```
image-recipe/
├── build-for-hardware.sh       # Main build script
├── build-all-hardware.sh       # Build all targets
├── alpine-profile/
│   ├── overlay/                # Base system files
│   ├── overlay-start9-pure/    # Start9-specific
│   ├── overlay-hp-prodesk/     # HP-specific
│   ├── overlay-dell-optiplex/  # Dell-specific
│   └── overlay-merged/         # Final merged (auto)
├── scripts/
│   ├── build-backend.sh
│   ├── build-frontend.sh
│   └── install-archipelago.sh
└── results/                    # Build output
```

## 🐛 Troubleshooting

### Build Fails
```bash
# Clean everything
rm -rf results/ build/ apks/ aports/

# Rebuild
./build-for-hardware.sh start9-pure iso
```

### Docker Issues (macOS)
```bash
# Start Docker Desktop
open -a Docker

# Wait for Docker to start, then retry
./build-for-hardware.sh start9-pure iso
```

### Out of Disk Space
```bash
# Clean Docker (macOS)
docker system prune -a

# Clean build artifacts
rm -rf build/ results/ apks/
```

## 📖 Full Documentation

For detailed information:
- **Hardware Builds**: `README-HARDWARE-BUILDS.md`
- **OS Images**: `docs/building-os-images.md`
- **Architecture**: `docs/architecture.md`

## 🎯 Common Use Cases

### Build for production Start9 Server Pure
```bash
export ARCHIPELAGO_VERSION="1.0.0"
./build-for-hardware.sh start9-pure iso
```

### Build test images for all hardware
```bash
export ARCHIPELAGO_VERSION="dev"
./build-all-hardware.sh iso
```

### Build for your specific hardware
```bash
# Start9 Server Pure users
./build-for-hardware.sh start9-pure iso

# HP ProDesk users
./build-for-hardware.sh hp-prodesk iso

# Dell OptiPlex users
./build-for-hardware.sh dell-optiplex iso

# Other x86_64 hardware
./build-for-hardware.sh generic iso
```

## ⏱️ Build Times

Approximate build times (first build):

| Hardware | macOS (Docker) | Linux (Native) |
|----------|---------------|----------------|
| Start9 Pure | 45-60 min | 30-45 min |
| HP ProDesk | 45-60 min | 30-45 min |
| Dell OptiPlex | 45-60 min | 30-45 min |
| Generic | 45-60 min | 30-45 min |
| All Targets | 3-4 hours | 2-3 hours |

Subsequent builds are much faster (~10-15 minutes) due to caching.

## 💡 Tips

- **First build is slow**: Docker needs to download Alpine base, build tools, etc.
- **Use SSD**: Dramatically speeds up builds
- **Close apps**: Free up RAM and CPU for faster builds
- **Build overnight**: For all-hardware builds, run overnight
- **Check logs**: Build output shows progress and any issues

## 🚀 Next Steps

After building:
1. Flash ISO to USB drive
2. Boot your hardware from USB
3. Install Archipelago
4. Access UI at http://device-ip:8100
5. Install Bitcoin Core and apps
6. Enjoy your sovereign server!

## 📞 Support

Need help?
- **Issues**: Open GitHub issue
- **Docs**: Check `docs/` folder
- **Community**: Discord (coming soon)

---

**Remember**: Keep your ProDesk and OptiPlex builds! The system supports all hardware targets simultaneously.