# Building Archipelago OS Images

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

## Overview

The build system creates bootable ISO images containing:
- Debian Linux 12 (Bookworm) base system
- Podman container runtime
- Archipelago backend (Rust)
- Archipelago frontend (Vue.js)
- Systemd services
- Network configuration via NetworkManager

## Prerequisites

### macOS

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

### Linux

- **Docker** (optional, for building backend)
- **xorriso**: `apt-get install xorriso`
- **7zip**: `apt-get install p7zip-full`
- **Disk Space**: At least 10GB free

## Quick Start

```bash
cd image-recipe
./build-debian-iso.sh
```

This will:
1. Download Debian Live ISO (if not cached)
2. Extract and customize the ISO
3. Add Archipelago components
4. Create final bootable ISO

Output: `results/archipelago-debian-12-x86_64.iso`

## Build Process

### Step 1: Build Backend (Optional)

If you have local changes to the backend:

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

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

### Step 2: Build Frontend (Optional)

If you have local changes to the frontend:

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

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

### Step 3: Build OS Image

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

## Flashing to USB

### Using dd (Recommended)

```bash
# macOS
./write-usb-dd.sh /dev/diskN

# Or manually:
sudo dd if=results/archipelago-debian-12-x86_64.iso of=/dev/rdiskX bs=4m status=progress
```

```bash
# Linux
sudo dd if=results/archipelago-debian-12-x86_64.iso of=/dev/sdX bs=4M status=progress
```

### Using Balena Etcher

1. Download [Balena Etcher](https://www.balena.io/etcher/)
2. Select the ISO file
3. Select target USB drive
4. Click Flash

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

## Installation Methods

### 1. Live USB Boot

Boot from the USB to run Archipelago in live mode:
- Test the system without installing
- Changes don't persist after reboot

### 2. Full Disk Installation

From the live environment:

```bash
sudo /archipelago/install-to-disk.sh
```

This will:
1. Partition the target disk (GPT with EFI)
2. Install Debian via debootstrap
3. Install Archipelago components
4. Configure bootloader (GRUB)

## Default Credentials

### Live Mode
- Username: `user`
- Password: `live`

### After Installation
- Username: `archipelago`
- Password: `archipelago`

⚠️ **Change passwords immediately after installation!**

## Customization

### Environment Variables

```bash
# Debian version
DEBIAN_VERSION=bookworm

# Architecture
ARCH=amd64

# Output directory
OUTPUT_DIR=./results
```

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

### Image Boot Issues

**Problem**: Image doesn't boot
- Verify ISO 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`

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

- [Debian Live Manual](https://live-team.pages.debian.net/live-manual/)
- [Archipelago Architecture](./architecture.md)
- [Development Setup](./development-setup.md)