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:

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

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

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

./build-for-hardware.sh generic iso

Build System Features

Hardware Detection

Each image includes automatic hardware detection on first boot:

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

# 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

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

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

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

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

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

   my-hardware)
       HARDWARE_NAME="My Hardware Name"
       HARDWARE_PROFILE="my-hardware"
       CPU_VENDOR="intel"
       # ... other specs
       ;;
   

2. Create overlay directory:

   mkdir -p alpine-profile/overlay-my-hardware/etc/archipelago
   

3. Add hardware-specific configs:

   # Create hardware.toml, hardware-info.sh, etc.
   

4. Build:

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