archy/image-recipe/QUICK-REFERENCE.md

Archipelago Hardware Build System - Quick Reference

🚀 Quick Start

Build for Start9 Server Pure

cd image-recipe
./build-for-hardware.sh start9-pure iso

Build for HP ProDesk

cd image-recipe
./build-for-hardware.sh hp-prodesk iso

Build for Dell OptiPlex

cd image-recipe
./build-for-hardware.sh dell-optiplex iso

Build for All Hardware

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

./build-for-hardware.sh <target> [iso|disk]

Examples:

# 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

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

# 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

# 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

# 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

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:

# 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

# Clean everything
rm -rf results/ build/ apks/ aports/

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

Docker Issues (macOS)

# Start Docker Desktop
open -a Docker

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

Out of Disk Space

# 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

export ARCHIPELAGO_VERSION="1.0.0"
./build-for-hardware.sh start9-pure iso

Build test images for all hardware

export ARCHIPELAGO_VERSION="dev"
./build-all-hardware.sh iso

Build for your specific hardware

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