archy/docs/building-os-images.md

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

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:

./scripts/build-backend.sh

This creates:

• build/backend/archipelago - Compiled binary

Step 2: Build Frontend (Optional)

If you have local changes to the frontend:

./scripts/build-frontend.sh

This creates:

• build/frontend/ - Static files

Step 3: Build OS Image

./build-debian-iso.sh

Flashing to USB

Using dd (Recommended)

# 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

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

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

# Debian version
DEBIAN_VERSION=bookworm

# Architecture
ARCH=amd64

# Output directory
OUTPUT_DIR=./results

Troubleshooting

Docker Issues (macOS)

Problem: Docker daemon not running

# Start Docker Desktop application
open -a Docker

Problem: Out of disk space

# Clean Docker
docker system prune -a

Build Failures

Problem: Backend build fails

# Check Rust installation
rustc --version

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

Problem: Frontend build fails

# 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
• Archipelago Architecture
• Development Setup