c9722a34f6
- Added new entries to .gitignore for build artifacts and macOS output directories to streamline the build process. - Deleted outdated documentation files: AUTH_LOGIN_FIX.md, AUTBOOT_CONFIGURATION.md, BACKEND_FIXES.md, BACKEND_STARTUP_FIX.md, BITCOIN_CORE_HEADLESS_FIX.md, BITCOIN_CORE_UI_COMPLETE.md, BITCOIN_STANDALONE_UI_COMPLETE.md, BITCOIN_UI_COMPLETE.md, BOOT_SEQUENCE_DIAGRAM.txt, and BUILD_COMMANDS_REFERENCE.txt to declutter the repository and remove unnecessary content.
217 lines
4.2 KiB
Markdown
217 lines
4.2 KiB
Markdown
# 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](https://www.docker.com/products/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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./scripts/build-backend.sh
|
|
```
|
|
|
|
This creates:
|
|
- `build/backend/archipelago` - Compiled binary
|
|
|
|
### Step 2: Build Frontend (Optional)
|
|
|
|
If you have local changes to the frontend:
|
|
|
|
```bash
|
|
./scripts/build-frontend.sh
|
|
```
|
|
|
|
This creates:
|
|
- `build/frontend/` - Static files
|
|
|
|
### Step 3: Build OS Image
|
|
|
|
```bash
|
|
./build-debian-iso.sh
|
|
```
|
|
|
|
## Flashing to USB
|
|
|
|
### Using dd (Recommended)
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
```bash
|
|
# 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](https://www.balena.io/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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# Debian version
|
|
DEBIAN_VERSION=bookworm
|
|
|
|
# Architecture
|
|
ARCH=amd64
|
|
|
|
# Output directory
|
|
OUTPUT_DIR=./results
|
|
```
|
|
|
|
## 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
|
|
```
|
|
|
|
### 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](https://live-team.pages.debian.net/live-manual/)
|
|
- [Archipelago Architecture](./architecture.md)
|
|
- [Development Setup](./development-setup.md)
|