archy/docs/building-os-images.md

# Building Archipelago OS Images

This guide explains how to build bootable Alpine Linux OS images for Archipelago Bitcoin Node OS that can be flashed to x86_64 desktop computers (Dell Optiplex, HP ProDesk 400 G4 DM, etc.).

## Overview

The build system creates bootable ISO or disk images containing:
- Alpine Linux base system
- Podman container runtime
- Archipelago backend (Rust)
- Archipelago frontend (Vue.js)
- Systemd services
- Network configuration

## Prerequisites

### macOS

- **Docker Desktop**: [Install Docker Desktop](https://www.docker.com/products/docker-desktop)
- **Disk Space**: At least 10GB free
- **Memory**: 8GB+ recommended

### Linux (HP ProDesk 400 G4 DM)

- **Alpine Linux** (preferred) or any Linux with Docker
- **Build Tools**: See installation below
- **Disk Space**: At least 10GB free

## Quick Start

### On macOS

```bash
cd image-recipe
./build-macos.sh
```

This will:
1. Build Docker container with all tools
2. Compile backend and frontend
3. Create Alpine image with Archipelago
4. Output ISO to `results/` directory

### On Linux

```bash
cd image-recipe
./build-linux.sh
```

For native Alpine Linux:
```bash
cd image-recipe
./build-alpine-native.sh
```

## Build Process

### Step 1: Build Backend

The backend is compiled from Rust source:

```bash
./scripts/build-backend.sh
```

This creates:
- `build/backend/archipelago` - Compiled binary

### Step 2: Build Frontend

The frontend is built from Vue.js source:

```bash
./scripts/build-frontend.sh
```

This creates:
- `build/frontend/` - Static files

### Step 3: Create APK Package

Backend is packaged as Alpine APK:

```bash
./scripts/create-backend-apk.sh
```

This creates:
- `apks/archipelago-backend-*.apk`

### Step 4: Build OS Image

The main build script orchestrates everything:

```bash
./build-alpine-iso.sh
```

Or build specific type:

```bash
BUILD_TYPE=iso ./build-alpine-iso.sh
BUILD_TYPE=disk ./build-alpine-iso.sh
```

## Build Types

### ISO Image

Creates a bootable ISO file suitable for:
- Burning to DVD
- Writing to USB drive
- Booting in virtual machines

```bash
BUILD_TYPE=iso ./build-alpine-iso.sh
```

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

### Disk Image

Creates a raw disk image suitable for:
- Direct flashing to SSD/HDD
- Using with `dd` command
- Virtual machine disk

```bash
BUILD_TYPE=disk ./build-alpine-iso.sh
```

Output: `results/archipelago-0.1.0-x86_64.img`

## Flashing to Device

### Using ISO (USB Boot)

1. **Write ISO to USB**:
   ```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
   ```

2. **Boot from USB** on target device
3. **Install to disk** (if installer included) or run live

### Using Disk Image (Direct Flash)

1. **Connect target disk** to build machine
2. **Flash image**:
   ```bash
   # macOS
   sudo dd if=results/archipelago-0.1.0-x86_64.img of=/dev/rdiskX bs=1m
   
   # Linux
   sudo dd if=results/archipelago-0.1.0-x86_64.img of=/dev/sdX bs=1M
   ```

3. **Boot from disk** on target device

⚠️ **Warning**: Double-check the device path! Flashing to wrong device will destroy data.

## Customization

### Environment Variables

```bash
# Version
ARCHIPELAGO_VERSION=0.1.0

# Alpine version
ALPINE_VERSION=3.19

# Architecture
ARCH=x86_64

# Build type
BUILD_TYPE=iso  # or "disk"

# Output directory
OUTPUT_DIR=./results
```

### Custom Profile

Edit `alpine-profile/mkimg.archipelago.sh` to:
- Add/remove packages
- Change kernel options
- Modify boot configuration

### Overlay Files

Add files to `alpine-profile/overlay/` to include in image:
- Configuration files
- Scripts
- Service files

## Build Output

After successful build, you'll find:

```
results/
├── archipelago-0.1.0-x86_64.iso    # Bootable ISO
└── archipelago-0.1.0-x86_64.img    # Disk image (if disk build)
```

## Troubleshooting

### Docker Issues (macOS)

**Problem**: Docker daemon not running
```bash
# Start Docker Desktop application
open -a Docker
```

**Problem**: Out of disk space
```bash
# Clean Docker
docker system prune -a
```

### Build Failures

**Problem**: Backend build fails
```bash
# Check Rust installation
rustc --version

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

**Problem**: Frontend build fails
```bash
# Check Node.js
node --version  # Need 18+

# Install dependencies
cd neode-ui
npm install
```

**Problem**: Alpine aports clone fails
```bash
# Manual clone
cd image-recipe
git clone https://gitlab.alpinelinux.org/alpine/aports.git
```

### Image Boot Issues

**Problem**: Image doesn't boot
- Verify ISO/image integrity
- Check BIOS/UEFI settings
- Ensure correct architecture (x86_64)
- Try different boot mode (UEFI vs Legacy)

**Problem**: Services don't start
- Check logs: `journalctl -u archipelago`
- Verify network: `ip addr`
- Check Podman: `podman info`

## Advanced Usage

### Building on Remote Linux Machine

```bash
# On macOS, copy project
scp -r Archipelago user@linux-machine:/tmp/

# SSH to Linux machine
ssh user@linux-machine

# Build
cd /tmp/Archipelago/image-recipe
./build-linux.sh
```

### Cross-Compilation

For building on different architecture:

```bash
# Install cross-compilation tools
apk add cross-x86_64-linux-musl

# Build with target
cargo build --release --target x86_64-unknown-linux-musl
```

### Custom Kernel

To use custom kernel options:

1. Edit `alpine-profile/mkimg.archipelago.sh`
2. Modify `kernel_flavors` or `kernel_addons`
3. Rebuild image

## Next Steps

After building and flashing:

1. **Boot the device**
2. **Access web UI**: http://device-ip:8100
3. **Configure network** (if needed)
4. **Install apps** via UI
5. **Set up Bitcoin node** (if desired)

## Resources

- [Alpine Linux mkimage Documentation](https://wiki.alpinelinux.org/wiki/How_to_make_a_custom_ISO_image)
- [Archipelago Architecture](./architecture.md)
- [Development Setup](./development-setup.md)