lfg2025/archy
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases 44 Wiki Activity
archy/docs/building-os-images.md
zazawowow 731cd67cfb mid coding commit
2026-01-24 22:59:20 +00:00

5.9 KiB
Raw Blame History

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

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

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

cd image-recipe
./build-linux.sh

For native Alpine Linux:

cd image-recipe
./build-alpine-native.sh

Build Process

Step 1: Build Backend

The backend is compiled from Rust source:

./scripts/build-backend.sh

This creates:

  • build/backend/archipelago - Compiled binary

Step 2: Build Frontend

The frontend is built from Vue.js source:

./scripts/build-frontend.sh

This creates:

  • build/frontend/ - Static files

Step 3: Create APK Package

Backend is packaged as Alpine APK:

./scripts/create-backend-apk.sh

This creates:

  • apks/archipelago-backend-*.apk

Step 4: Build OS Image

The main build script orchestrates everything:

./build-alpine-iso.sh

Or build specific type:

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

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

    # 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

# 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

# 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

Problem: Alpine aports clone fails

# 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

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

# 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