# Getting Started: Building Your First Archipelago OS Image

## 🎯 Goal

Build a bootable Alpine Linux OS image that includes Archipelago Bitcoin Node OS, ready to flash to a Dell Optiplex or HP ProDesk 400 G4 DM.

## ✅ What's Ready

The complete build system is implemented and ready to use:

- ✅ Build scripts for macOS and Linux
- ✅ Docker support for cross-platform building
- ✅ Backend and frontend compilation
- ✅ Alpine profile with Archipelago integration
- ✅ ISO and disk image generation
- ✅ First boot automation

## 🚀 Quick Start (macOS)

```bash
# 1. Navigate to image recipe directory
cd image-recipe

# 2. Check dependencies
./scripts/check-dependencies.sh

# 3. Build the image
./build-macos.sh
```

**Expected time**: 30-60 minutes on first build (downloads Alpine aports)

**Output**: `results/archipelago-0.1.0-x86_64.iso`

## 🚀 Quick Start (Linux - HP ProDesk 400 G4 DM)

```bash
# 1. Navigate to image recipe directory
cd image-recipe

# 2. Build (auto-detects Alpine or Docker)
./build-linux.sh
```

**Expected time**: 20-40 minutes on Alpine, 30-60 minutes with Docker

**Output**: `results/archipelago-0.1.0-x86_64.iso`

## 📋 What Gets Built

1. **Backend Binary**: Rust backend compiled for x86_64
2. **Frontend**: Vue.js app built as static files
3. **APK Package**: Backend packaged as Alpine APK
4. **Alpine Image**: Base Alpine Linux with:
   - Podman container runtime
   - Systemd services
   - Network configuration
   - Archipelago backend and frontend

## 💾 Flashing the Image

### Option 1: ISO to USB (Recommended)

```bash
# macOS
sudo dd if=results/archipelago-0.1.0-x86_64.iso of=/dev/rdiskX bs=1m

# Linux
sudo dd if=results/archipelago-0.1.0-x86_64.iso of=/dev/sdX bs=1M
```

### Option 2: Disk Image Direct Flash

```bash
# Build disk image
BUILD_TYPE=disk ./build-macos.sh

# Flash directly
sudo dd if=results/archipelago-0.1.0-x86_64.img of=/dev/sdX bs=1M
```

⚠️ **WARNING**: Replace `X` with your actual device. Wrong device = data loss!

## 🎉 After Flashing

1. **Boot from USB/disk** on target device
2. **Wait for first boot** (automatic setup)
3. **Access web UI**: http://device-ip:8100
4. **Or API**: http://device-ip:5959

## 🔧 Troubleshooting

### Build Fails

- **Check dependencies**: `./scripts/check-dependencies.sh`
- **Check disk space**: Need 10GB+ free
- **Check Docker**: `docker info` should work (macOS)
- **Check logs**: Look for error messages in build output

### Image Doesn't Boot

- **Verify ISO**: `file results/*.iso` should show "ISO 9660"
- **Try different USB port**
- **Check BIOS/UEFI settings**
- **Verify architecture**: Must be x86_64

### Services Don't Start

- **Check logs**: `journalctl -u archipelago` (on device)
- **Check network**: `ip addr` (on device)
- **Check Podman**: `podman info` (on device)

## 📚 More Information

- [Building OS Images](../docs/building-os-images.md) - Full detailed guide
- [Build Status](BUILD_STATUS.md) - Implementation status
- [Summary](SUMMARY.md) - What's been implemented

## 🎯 Next Steps

1. **Test build** on your macOS machine
2. **Test build** on HP ProDesk 400 G4 DM
3. **Flash to USB** and test boot
4. **Flash to device** and verify functionality
5. **Customize** profile if needed

Happy building! 🚀