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
```bash
./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
```bash
./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
```bash
./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
```bash
./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:**
   ```bash
   cd image-recipe
   ./build-for-hardware.sh <target> iso
   ```

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

3. **Find your ISO:**
   ```bash
   ls results/archipelago-*-<target>-*.iso
   ```

### Build Types

#### ISO Image (Recommended)
```bash
./build-for-hardware.sh start9-pure iso
```
- Bootable from USB drive
- Live system or installation
- Easy to flash with tools

#### Disk Image
```bash
./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:**
```bash
# 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:**
```bash
# 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](https://www.balena.io/etcher/) (macOS/Linux/Windows)
- [Rufus](https://rufus.ie/) (Windows)
- [Raspberry Pi Imager](https://www.raspberrypi.com/software/) (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:

```bash
# 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
```bash
# 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:
```bash
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:
```bash
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:
   ```bash
   cp -r alpine-profile/overlay alpine-profile/overlay-myserver
   ```

2. Edit hardware config:
   ```bash
   vim alpine-profile/overlay-myserver/etc/archipelago/hardware.toml
   ```

3. Build with custom profile:
   ```bash
   HARDWARE_TARGET=myserver ./build-for-hardware.sh myserver iso
   ```

### Build All Targets

Build for all supported hardware:
```bash
#!/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:
```bash
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:

```bash
# 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!