archy/image-recipe/GETTING_STARTED.md

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)

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

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

# 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

# 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 - Full detailed guide
• Build Status - Implementation status
• Summary - 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! 🚀