128 lines
3.2 KiB
Markdown
128 lines
3.2 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```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
|
|
```
|
|
|
|
### Option 2: Disk Image Direct Flash
|
|
|
|
```bash
|
|
# 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](../docs/building-os-images.md) - Full detailed guide
|
|
- [Build Status](BUILD_STATUS.md) - Implementation status
|
|
- [Summary](SUMMARY.md) - 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! 🚀
|