mid coding commit
This commit is contained in:
zazawowow
@@ -0,0 +1,319 @@
|
||||
# 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
|
||||
|
||||
- **Docker Desktop**: [Install Docker Desktop](https://www.docker.com/products/docker-desktop)
|
||||
- **Disk Space**: At least 10GB free
|
||||
- **Memory**: 8GB+ recommended
|
||||
|
||||
### 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
cd image-recipe
|
||||
./build-linux.sh
|
||||
```
|
||||
|
||||
For native Alpine Linux:
|
||||
```bash
|
||||
cd image-recipe
|
||||
./build-alpine-native.sh
|
||||
```
|
||||
|
||||
## Build Process
|
||||
|
||||
### Step 1: Build Backend
|
||||
|
||||
The backend is compiled from Rust source:
|
||||
|
||||
```bash
|
||||
./scripts/build-backend.sh
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `build/backend/archipelago` - Compiled binary
|
||||
|
||||
### Step 2: Build Frontend
|
||||
|
||||
The frontend is built from Vue.js source:
|
||||
|
||||
```bash
|
||||
./scripts/build-frontend.sh
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `build/frontend/` - Static files
|
||||
|
||||
### Step 3: Create APK Package
|
||||
|
||||
Backend is packaged as Alpine APK:
|
||||
|
||||
```bash
|
||||
./scripts/create-backend-apk.sh
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `apks/archipelago-backend-*.apk`
|
||||
|
||||
### Step 4: Build OS Image
|
||||
|
||||
The main build script orchestrates everything:
|
||||
|
||||
```bash
|
||||
./build-alpine-iso.sh
|
||||
```
|
||||
|
||||
Or build specific type:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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**:
|
||||
```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
|
||||
```
|
||||
|
||||
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**:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```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
|
||||
```
|
||||
|
||||
**Problem**: Alpine aports clone fails
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
- [Alpine Linux mkimage Documentation](https://wiki.alpinelinux.org/wiki/How_to_make_a_custom_ISO_image)
|
||||
- [Archipelago Architecture](./architecture.md)
|
||||
- [Development Setup](./development-setup.md)
|
||||
Reference in New Issue
Block a user