archy/MULTI_HARDWARE_BUILD_SYSTEM.md

# Archipelago Multi-Hardware Build System

## Overview

Archipelago now supports building optimized OS images for multiple hardware targets, including **Start9 Server Pure**, while maintaining support for HP ProDesk and Dell OptiPlex.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                  Archipelago Build System                    │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌────────────────┐    ┌──────────────┐
│  Source Code  │    │  Build Scripts │    │   Hardware   │
│               │    │                │    │   Profiles   │
│ - Rust Core   │    │ - Backend      │    │              │
│ - Vue.js UI   │    │ - Frontend     │    │ start9-pure  │
│ - Apps        │    │ - Alpine ISO   │    │ hp-prodesk   │
│ - Manifests   │    │ - APK Package  │    │ dell-optiplex│
└───────────────┘    └────────────────┘    │ generic      │
                                            └──────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌────────────────┐    ┌──────────────┐
│  Start9 Pure  │    │   HP ProDesk   │    │    Dell      │
│               │    │                │    │  OptiPlex    │
│ i7-10710U     │    │ Various Intel  │    │ Various Intel│
│ 32-64GB RAM   │    │ 8GB+ RAM       │    │ 8GB+ RAM     │
│ 2-4TB NVMe    │    │ 128GB+ SSD     │    │ 128GB+ SSD   │
│               │    │                │    │              │
│ ✓ Intel ucode │    │ ✓ Generic Intel│    │ ✓ Dell FW    │
│ ✓ NVMe optim  │    │ ✓ SATA/NVMe    │    │ ✓ Multi-model│
│ ✓ UHD Graphics│    │ ✓ Compact FF   │    │ ✓ Business   │
└───────────────┘    └────────────────┘    └──────────────┘
```

## Hardware Targets

### 1. Start9 Server Pure (NEW)

**Specifications:**
- CPU: Intel Core i7-10710U (6C/12T)
- 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

**Optimizations:**
```
- Intel microcode (i7-10710U specific)
- Intel UHD Graphics drivers and acceleration
- NVMe SSD I/O scheduler (none/noop)
- Power management tuning
- Coreboot firmware support
- Intel ME disabled (respected)
```

**Build Command:**
```bash
./build-for-hardware.sh start9-pure iso
```

**Output:**
```
archipelago-0.1.0-start9-pure-x86_64.iso
BUILD_MANIFEST_start9-pure.txt
```

### 2. HP ProDesk 400 G4 DM (EXISTING)

**Specifications:**
- CPU: Various Intel processors
- RAM: 8GB+ DDR4
- Storage: 128GB+ SATA/NVMe SSD
- Form Factor: Desktop Mini
- Network: Gigabit Ethernet

**Optimizations:**
```
- Generic Intel microcode
- Intel graphics support
- SATA/NVMe auto-detection
- HP firmware compatibility
- Compact form factor tuning
```

**Build Command:**
```bash
./build-for-hardware.sh hp-prodesk iso
```

**Output:**
```
archipelago-0.1.0-hp-prodesk-x86_64.iso
BUILD_MANIFEST_hp-prodesk.txt
```

### 3. Dell OptiPlex (EXISTING)

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

**Optimizations:**
```
- Generic Intel microcode
- Intel/AMD graphics support
- Multi-model compatibility
- Dell firmware support
- Business-class features
```

**Build Command:**
```bash
./build-for-hardware.sh dell-optiplex iso
```

**Output:**
```
archipelago-0.1.0-dell-optiplex-x86_64.iso
BUILD_MANIFEST_dell-optiplex.txt
```

### 4. Generic x86_64 (FALLBACK)

**Specifications:**
- CPU: Any x86_64 (Intel/AMD)
- RAM: 8GB+ recommended
- Storage: 128GB+ HDD/SSD
- Network: Any Ethernet

**Optimizations:**
```
- Universal drivers
- Intel and AMD support
- Maximum compatibility
- Generic firmware
```

**Build Command:**
```bash
./build-for-hardware.sh generic iso
```

## Build System Features

### Hardware Detection
Each image includes automatic hardware detection on first boot:

```bash
/etc/archipelago/hardware-info.sh
```

This script detects:
- CPU vendor, model, cores
- Available RAM
- Storage devices (NVMe, SATA SSD, HDD)
- Network interfaces
- Graphics hardware
- USB controllers

### Hardware-Specific Files

Each build creates:

```
/etc/archipelago/
├── hardware.toml           # Hardware profile config
├── hardware-info.sh        # Detection script
└── system-info.txt         # Runtime info (created on boot)

/var/log/
└── archipelago-hardware.log  # Detection results
```

### Optimization Scripts

Hardware-specific optimizations run on boot:

```bash
# Intel CPU microcode
modprobe intel_rapl_common
modprobe intel_powerclamp

# Intel Graphics acceleration
modprobe i915

# NVMe optimization (Start9 Pure)
echo none > /sys/block/nvme0n1/queue/scheduler

# SATA SSD optimization (ProDesk/OptiPlex)
echo deadline > /sys/block/sda/queue/scheduler
```

## Build Workflow

### Single Hardware Build

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

**Process:**
1. Detect build environment (macOS/Linux)
2. Create hardware-specific overlay
3. Generate hardware detection scripts
4. Create hardware.toml config
5. Merge with base Alpine profile
6. Build Alpine ISO with mkimage
7. Package Archipelago backend (Rust)
8. Package Archipelago frontend (Vue.js)
9. Create installation scripts
10. Generate ISO with all components
11. Create build manifest

**Time:** ~45-60 minutes (first build)

### All Hardware Builds

```bash
cd image-recipe
./build-all-hardware.sh iso
```

**Process:**
- Builds for: start9-pure, hp-prodesk, dell-optiplex, generic
- Runs builds sequentially
- Creates separate ISO for each target
- Generates individual manifests

**Time:** ~3-4 hours (first build)

## File Structure

```
image-recipe/
├── build-for-hardware.sh           # Main hardware build script
├── build-all-hardware.sh           # Build all targets
├── build-macos.sh                  # macOS Docker build
├── build-alpine-native.sh          # Native Alpine build
│
├── alpine-profile/
│   ├── mkimg.archipelago.sh        # Alpine profile definition
│   ├── overlay/                    # Base system files (all hardware)
│   │   ├── etc/
│   │   │   ├── archipelago/
│   │   │   │   └── config.toml
│   │   │   ├── systemd/system/
│   │   │   │   └── archipelago.service
│   │   │   └── init.d/
│   │   │       └── archipelago
│   │   └── ...
│   │
│   ├── overlay-start9-pure/        # Start9-specific files
│   │   └── etc/archipelago/
│   │       ├── hardware.toml
│   │       └── hardware-info.sh
│   │
│   ├── overlay-hp-prodesk/         # HP-specific files
│   ├── overlay-dell-optiplex/      # Dell-specific files
│   ├── overlay-generic/            # Generic files
│   └── overlay-merged/             # Final merged (temporary)
│
├── scripts/
│   ├── build-backend.sh            # Compile Rust backend
│   ├── build-frontend.sh           # Build Vue.js UI
│   ├── create-backend-apk.sh       # Package as Alpine APK
│   ├── install-archipelago.sh      # Install into image
│   └── harden-alpine.sh            # Security hardening
│
├── build/                          # Build artifacts (temp)
│   ├── backend/
│   └── frontend/
│
├── apks/                           # Alpine packages (temp)
│   └── archipelago-backend-*.apk
│
└── results/                        # Final ISOs
    ├── 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
```

## Usage Examples

### Building for Start9 Server Pure

```bash
cd image-recipe

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

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

# Disk image instead of ISO
./build-for-hardware.sh start9-pure disk
```

### Installing on Start9 Server Pure

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

# 2. Insert USB into Start9 Server Pure

# 3. Boot from USB (Press F12 during boot)

# 4. Follow installation prompts

# 5. Access UI at http://device-ip:8100
```

### Verifying Hardware Detection

After installation, SSH into the device:

```bash
# View hardware profile
cat /etc/archipelago/hardware.toml

# View detection results
cat /var/log/archipelago-hardware.log

# View system info
cat /etc/archipelago/system-info.txt

# Check optimizations
dmesg | grep -i archipelago
```

## Benefits

### Hardware-Specific
- ✅ Optimized performance for each platform
- ✅ Correct drivers and firmware
- ✅ Platform-specific tuning
- ✅ Reduced image size (no unnecessary drivers)

### Development
- ✅ Easy to add new hardware targets
- ✅ Clean separation of profiles
- ✅ Reusable base components
- ✅ Automated build process

### Users
- ✅ Download correct image for their hardware
- ✅ Optimal out-of-box experience
- ✅ Clear documentation per platform
- ✅ Hardware verification on boot

## Adding New Hardware

To add a new hardware target:

1. **Create hardware profile** in `build-for-hardware.sh`:
   ```bash
   my-hardware)
       HARDWARE_NAME="My Hardware Name"
       HARDWARE_PROFILE="my-hardware"
       CPU_VENDOR="intel"
       # ... other specs
       ;;
   ```

2. **Create overlay directory**:
   ```bash
   mkdir -p alpine-profile/overlay-my-hardware/etc/archipelago
   ```

3. **Add hardware-specific configs**:
   ```bash
   # Create hardware.toml, hardware-info.sh, etc.
   ```

4. **Build**:
   ```bash
   ./build-for-hardware.sh my-hardware iso
   ```

## Next Steps

1. ✅ **Test Start9 Pure build** on actual hardware
2. ✅ **Verify hardware detection** scripts work correctly
3. ✅ **Document installation process** for Start9 users
4. ✅ **Create release ISOs** for all hardware targets
5. ✅ **Set up CI/CD** to build all targets automatically

## Documentation

- **Quick Reference**: `image-recipe/QUICK-REFERENCE.md`
- **Hardware Builds**: `image-recipe/README-HARDWARE-BUILDS.md`
- **OS Images**: `docs/building-os-images.md`
- **Architecture**: `docs/architecture.md`

## Support

For hardware-specific issues:
1. Check `BUILD_MANIFEST_<target>.txt`
2. Review `/var/log/archipelago-hardware.log` on device
3. Verify hardware matches target profile
4. Try generic build as fallback

---

**Built with ❤️ by the Archipelago team**

*Now supporting Start9 Server Pure, HP ProDesk, Dell OptiPlex, and more!*