archy/image-recipe/README-HARDWARE-BUILDS.md

Building Archipelago for Specific Hardware

Archipelago supports building optimized OS images for specific hardware targets. Each build includes hardware-specific optimizations, drivers, and configurations.

Supported Hardware

🖥️ Start9 Server Pure

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

Specifications:

• CPU: Intel Core i7-10710U (6 cores, 12 threads)
• RAM: 32GB or 64GB DDR4-3200
• Storage: 2TB or 4TB NVMe SSD
• Network: 1x Gigabit Ethernet
• Graphics: Intel UHD Graphics
• Ports: 4x USB 3.0, 2x USB 2.0, 1x USB-C 3.1, HDMI, DisplayPort

Optimizations:

• Intel microcode updates
• Intel graphics acceleration
• NVMe SSD optimizations
• Power management tuning

🖥️ HP ProDesk 400 G4 DM

./build-for-hardware.sh hp-prodesk iso

Specifications:

• CPU: Various Intel processors
• RAM: 8GB+ DDR4
• Storage: 128GB+ SATA/NVMe SSD
• Network: 1x Gigabit Ethernet
• Form Factor: Desktop Mini

Optimizations:

• Intel graphics drivers
• SATA/NVMe detection and optimization
• HP-specific firmware support

🖥️ Dell OptiPlex

./build-for-hardware.sh dell-optiplex iso

Specifications:

• CPU: Various Intel processors
• RAM: 8GB+ DDR4
• Storage: 128GB+ SATA/NVMe SSD
• Network: 1x Gigabit Ethernet
• Models: 3050, 7050, 9020, etc.

Optimizations:

• Intel graphics drivers
• Dell firmware support
• Multi-model compatibility

🖥️ Generic x86_64

./build-for-hardware.sh generic iso

Specifications:

• CPU: Any x86_64 processor (Intel/AMD)
• RAM: 8GB+ recommended
• Storage: 128GB+ HDD/SSD
• Network: Any Ethernet adapter

Optimizations:

• Broad hardware compatibility
• Generic drivers for maximum coverage
• Both Intel and AMD support

Build Process

Quick Start

1. Choose your hardware target:

   cd image-recipe
   ./build-for-hardware.sh <target> iso
   

2. Wait for build to complete (30-60 minutes first time)

3. Find your ISO:

   ls results/archipelago-*-<target>-*.iso
   

Build Types

ISO Image (Recommended)

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

• Bootable from USB drive
• Live system or installation
• Easy to flash with tools

Disk Image

./build-for-hardware.sh start9-pure disk

• Raw disk image
• For direct disk flashing
• Advanced users only

Hardware-Specific Features

Start9 Server Pure

• Coreboot Support: Optimized for Start9's Coreboot firmware
• No Intel ME: Respects disabled Intel Management Engine
• NVMe Performance: Tuned for high-speed NVMe SSDs
• Professional Grade: Enterprise-level reliability

HP ProDesk 400 G4 DM

• Compact Form Factor: Optimized for small desktop
• Business Features: Enterprise management support
• Low Power: Efficient power management
• Silent Operation: Thermal optimizations

Dell OptiPlex

• Wide Model Support: Works across many OptiPlex models
• Legacy Support: Compatible with older hardware
• Enterprise Ready: Business-class features
• Proven Reliability: Battle-tested hardware

Generic Build

• Maximum Compatibility: Works on most x86_64 hardware
• Fallback Option: When specific profile unavailable
• DIY Builds: Perfect for custom hardware
• Virtual Machines: Works in VirtualBox, VMware, etc.

What Gets Customized

Each hardware build includes:

1. Hardware Detection

Automatically detects and optimizes for:

• CPU vendor and model
• Available RAM
• Storage type (NVMe, SATA SSD, HDD)
• Network interfaces
• Graphics hardware
• USB controllers

2. Kernel Modules

Includes specific drivers for:

• Storage controllers
• Network adapters
• Graphics cards
• USB devices
• Audio hardware

3. Firmware

Loads appropriate firmware for:

• CPU microcode (Intel/AMD)
• Network adapters
• Graphics cards
• Wireless (if applicable)

4. Performance Tuning

Optimizes:

• I/O scheduler (NVMe vs SATA)
• CPU governor (performance vs power)
• Memory management
• Network buffers
• Disk caching

5. System Configuration

Sets defaults for:

• Boot parameters
• Service startup order
• Power management
• Thermal management
• Network configuration

Build Output

After successful build, you'll get:

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_<target>.txt

Each ISO includes:

• Hardware-specific optimizations
• Appropriate drivers and firmware
• Custom boot configuration
• Installation scripts
• Hardware detection tools

Installation

1. Flash ISO to USB

macOS:

# Find USB device
diskutil list

# Unmount
diskutil unmountDisk /dev/diskX

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

Linux:

# Find USB device
lsblk

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

GUI Tools:

• balenaEtcher (macOS/Linux/Windows)
• Rufus (Windows)
• Raspberry Pi Imager (All platforms)

2. Boot from USB

1. Insert USB drive into target hardware
2. Power on and enter boot menu:
   • Start9 Pure: Press F12 during boot
   • HP ProDesk: Press F9 during boot
   • Dell OptiPlex: Press F12 during boot
3. Select USB drive from boot menu
4. Follow installation prompts

3. First Boot

After installation:

1. Remove USB drive
2. Reboot system
3. Hardware detection runs automatically
4. Services start automatically
5. Access UI at http://<device-ip>:8100

Verification

After flashing, verify the build:

# Check ISO integrity
sha256sum results/archipelago-0.1.0-start9-pure-x86_64.iso

# View build manifest
cat results/BUILD_MANIFEST_start9-pure.txt

# Mount ISO to inspect (Linux)
sudo mount -o loop archipelago-0.1.0-start9-pure-x86_64.iso /mnt
ls -la /mnt
cat /mnt/etc/archipelago/hardware.toml
sudo umount /mnt

Troubleshooting

Build Fails

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

# Try again
./build-for-hardware.sh start9-pure iso

Wrong Hardware Detected

Check hardware profile after boot:

cat /etc/archipelago/hardware.toml
cat /var/log/archipelago-hardware.log

Boot Issues

• Verify ISO checksum
• Try different USB port
• Check BIOS/UEFI settings:
  • Enable UEFI boot
  • Disable Secure Boot (for now)
  • Enable USB boot
  • Set boot order

Performance Issues

View hardware optimization log:

cat /var/log/archipelago-hardware.log
dmesg | grep -i archipelago
journalctl -u archipelago

Advanced Usage

Custom Hardware Profile

Create custom profile for your hardware:

1. Copy generic profile:

   cp -r alpine-profile/overlay alpine-profile/overlay-myserver
   

2. Edit hardware config:

   vim alpine-profile/overlay-myserver/etc/archipelago/hardware.toml
   

3. Build with custom profile:

   HARDWARE_TARGET=myserver ./build-for-hardware.sh myserver iso
   

Build All Targets

Build for all supported hardware:

#!/bin/bash
for target in start9-pure hp-prodesk dell-optiplex generic; do
    echo "Building for $target..."
    ./build-for-hardware.sh $target iso
done

Automated Testing

Test ISO in QEMU:

qemu-system-x86_64 \
    -m 4G \
    -smp 2 \
    -boot d \
    -cdrom results/archipelago-0.1.0-start9-pure-x86_64.iso \
    -enable-kvm

Hardware Requirements

Minimum Requirements

• CPU: 64-bit x86_64 processor
• RAM: 4GB (8GB recommended)
• Storage: 64GB (128GB recommended)
• Network: Ethernet adapter
• Boot: UEFI or Legacy BIOS

Recommended Requirements

• CPU: Intel i5/i7 or AMD Ryzen 5/7
• RAM: 16GB+
• Storage: 256GB+ SSD (NVMe preferred)
• Network: Gigabit Ethernet
• Boot: UEFI with GPT

Start9 Server Pure (Optimal)

• CPU: Intel i7-10710U (6 cores, 12 threads)
• RAM: 32GB or 64GB
• Storage: 2TB or 4TB NVMe SSD
• Network: Gigabit Ethernet
• Ports: Multiple USB 3.0, USB-C

Next Steps

After installation:

1. Access web UI: http://<device-ip>:8100
2. Complete setup wizard
3. Install Bitcoin Core
4. Add Lightning Network (LND or CLN)
5. Install additional apps
6. Configure backups
7. Secure your node

Support

Need help?

• Documentation: docs/
• Issues: GitHub Issues
• Community: Discord (coming soon)
• Hardware-Specific: Check BUILD_MANIFEST_<target>.txt

Building Multiple Targets

To build for all your hardware:

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

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

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

# You'll get separate ISOs optimized for each

Each ISO is independent and optimized for its target hardware!