lfg2025/archy
1
0
Fork 0
Code Issues 27 Pull Requests 5 Actions Packages Projects Releases 6 Wiki Activity

Revise BUILD-GUIDE and enhance ISO build process

Browse Source 
- Updated BUILD-GUIDE.md to streamline instructions for building the Archipelago Auto-Installer ISO, including prerequisites and post-installation steps.
- Added detailed sections on capturing the live server state and building from source.
- Enhanced Docker and Podman integration in build scripts for improved backend and web UI capture.
- Introduced new app metadata for "IndeedHub" in the Docker package scanner and updated UI components for better installation progress tracking.
- Improved styling and functionality in the Bitcoin UI for a more cohesive user experience.
This commit is contained in:
Dorian
2026-02-03 21:43:33 +00:00
parent 0f40cb88b5
commit 337ebee510
22 changed files with 2619 additions and 509 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BUILD-GUIDE.md
+88 -269
View File
@@ -1,296 +1,115 @@
# Archipelago ISO Build System
# Quick Build Guide - Archipelago Beta Release
Complete, robust build system for creating flashable Archipelago ISO images from source.
## Prerequisites
## Quick Start
Make sure you have:
- Docker or Podman installed
- `xorriso` installed
- Access to dev server: archipelago@192.168.1.228
### One-Command Build (Recommended)
Build everything and create a flashable ISO with a single command:
## Build Auto-Installer ISO
```bash
# Build on remote server (recommended for x86_64 target)
./build-iso-complete.sh --remote archipelago@192.168.1.228
cd /Users/dorian/Projects/archy/image-recipe
# Or build locally (if you have Rust + Node.js)
./build-iso-complete.sh --local
# Capture current live server state
DEV_SERVER=archipelago@192.168.1.228 ./build-auto-installer-iso.sh
# ISO will be created in: results/archipelago-auto-installer-*.iso
```
### Flash to USB
## What the ISO Includes
After building:
✅ Complete Debian 12 root filesystem
✅ Pre-built Archipelago backend
✅ Pre-built frontend (web UI)
✅ Nginx configuration (HTTPS ready)
✅ Auto-installer that:
- Detects internal disk
- Creates partitions (EFI + root)
- Extracts pre-built system
- Installs bootloader
- Reboots to working system
## What Users Need to Do Post-Install
1. **Deploy Containers** - The ISO doesn't include containers (too large)
Example - Bitcoin Knots:
```bash
sudo podman run -d --name bitcoin-knots \
-p 8332:8332 -p 8333:8333 \
-v /var/lib/archipelago/bitcoin:/home/bitcoin/.bitcoin \
--label "com.archipelago.app=bitcoin-knots" \
--label "com.archipelago.title=Bitcoin Knots" \
docker.io/bitcoinknots/bitcoin:latest \
-server=1 -txindex=1 -rpcallowip=0.0.0.0/0 \
-rpcbind=0.0.0.0:8332 -dbcache=4096
```
2. **Access Web UI** - Navigate to `http://[server-ip]`
## Testing the ISO
```bash
# Find your USB device
diskutil list
# Flash (will prompt for confirmation)
./flash-to-usb.sh /dev/diskN
# Use VirtualBox, QEMU, or real hardware
qemu-system-x86_64 \
-m 4G \
-cdrom results/archipelago-auto-installer-*.iso \
-hda archipelago-test.qcow2 \
-boot d
```
## Build Options
## Important Notes
⚠️ **The auto-installer will ERASE the target disk!**
⚠️ Make sure to test on a non-production machine first
⚠️ Minimum 20GB disk space required (500GB+ recommended for Bitcoin)
## Build from Source (Alternative)
If you want to build everything from scratch instead of capturing the live server:
```bash
./build-iso-complete.sh [options]
BUILD_FROM_SOURCE=1 ./build-auto-installer-iso.sh
```
### Options
- `--local` - Build everything on your local machine
- `--remote HOST` - Build on remote server (e.g., `archipelago@192.168.1.228`)
- `--skip-backend` - Skip backend compilation (use existing binary)
- `--skip-frontend` - Skip frontend build (use existing dist)
- `--clean` - Clean all build artifacts before building
- `--help` - Show help message
### Examples
```bash
# Full clean build on remote server
./build-iso-complete.sh --remote archipelago@192.168.1.228 --clean
# Quick rebuild with existing backend
./build-iso-complete.sh --remote archipelago@192.168.1.228 --skip-backend
# Local build (requires Rust + Node.js installed)
./build-iso-complete.sh --local
# Clean local build
./build-iso-complete.sh --local --clean
```
## What the Script Does
The build script automates the entire ISO creation process:
### 1. **Backend Build** (Rust)
- Compiles `core/archipelago` to native binary
- Can build locally or on remote server
- Outputs to `image-recipe/build/backend/archipelago`
### 2. **Frontend Build** (Vue.js + Vite)
- Builds `neode-ui` to static assets
- Includes PWA manifest and service worker
- Outputs to `image-recipe/build/frontend/`
### 3. **ISO Creation** (Debian Live)
- Downloads base Debian 12 Live ISO
- Integrates backend binary and frontend assets
- Configures auto-start and services
- Creates bootable ISO at `image-recipe/results/archipelago-debian-12-x86_64.iso`
### 4. **Verification**
- Validates all build artifacts exist
- Generates MD5 checksum
- Reports file sizes
## Build Artifacts
```
image-recipe/
├── build/
│ ├── backend/
│ │ └── archipelago # Compiled Rust binary
│ └── frontend/ # Built Vue.js assets
│ ├── index.html
│ ├── assets/
│ └── ...
├── results/
│ └── archipelago-debian-12-x86_64.iso # Final bootable ISO
└── iso-workdir/ # Temporary ISO build files (auto-cleaned)
```
## Requirements
### For Remote Build (Recommended)
- SSH access to build server
- `rsync` installed locally
- Build server must have:
- Rust/Cargo (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
- Node.js/npm (`curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -`)
- Build tools (`sudo apt install build-essential`)
### For Local Build
- macOS or Linux
- Rust/Cargo installed ([rustup.rs](https://rustup.rs))
- Node.js 18+ installed ([nodejs.org](https://nodejs.org))
- `xorriso` for ISO creation (`brew install xorriso` on macOS)
- Admin/sudo access for ISO creation
This will:
- Build backend from Rust source
- Build frontend with `npm run build`
- Create fresh SSL certificates
- Generate default configs
## Troubleshooting
### Backend Build Fails
```bash
# Check Rust installation
cargo --version
**ISO won't boot:**
- Ensure UEFI mode is enabled
- Try disabling Secure Boot
# Update Rust
rustup update
**Installer hangs:**
- Check the auto-start script fix is applied (see DEPLOYMENT.md)
# Clean and rebuild
./build-iso-complete.sh --remote HOST --clean
**Backend doesn't detect containers:**
- Verify `/etc/sudoers.d/archipelago-podman` exists
- Check backend can run `sudo podman ps`
## Version Naming
ISOs are automatically named with timestamp:
```
archipelago-auto-installer-YYYYMMDD-HHMMSS.iso
```
### Frontend Build Fails
```bash
# Check Node.js version (need 18+)
node --version
# Clean node_modules
cd neode-ui
rm -rf node_modules package-lock.json
npm install
cd ..
# Rebuild
./build-iso-complete.sh --remote HOST --clean
For releases, rename to:
```
archipelago-v0.1.0-beta.1.iso
```
### ISO Build Fails
```bash
# Check available disk space (needs ~2GB)
df -h
## Next Steps After Building
# Ensure build artifacts exist
ls -lh image-recipe/build/backend/
ls -lh image-recipe/build/frontend/
# Try with sudo
cd image-recipe
sudo bash build-debian-iso.sh
```
### Remote Connection Issues
```bash
# Test SSH connection
ssh archipelago@192.168.1.228
# Test rsync
rsync --version
# Use SSH key for passwordless access
ssh-copy-id archipelago@192.168.1.228
```
## Build Time Estimates
| Step | Time (First Build) | Time (Incremental) |
|------|-------------------|-------------------|
| Backend compile | 3-5 minutes | 30 seconds |
| Frontend build | 1-2 minutes | 20 seconds |
| ISO download | 5-10 minutes | 0 (cached) |
| ISO creation | 2-3 minutes | 2-3 minutes |
| **Total** | **11-20 minutes** | **3-4 minutes** |
## Development Workflow
### Making Changes to Backend
```bash
# Edit Rust code in core/archipelago/src/
# Then rebuild:
./build-iso-complete.sh --remote archipelago@192.168.1.228 --skip-frontend
```
### Making Changes to Frontend
```bash
# Edit Vue.js code in neode-ui/src/
# Then rebuild:
./build-iso-complete.sh --remote archipelago@192.168.1.228 --skip-backend
```
### Making Changes to Both
```bash
# Edit both, then full rebuild:
./build-iso-complete.sh --remote archipelago@192.168.1.228
```
### Testing Changes Without ISO Build
```bash
# Backend (on development server)
cd core/archipelago
cargo run
# Frontend (local development)
cd neode-ui
npm run dev
```
## CI/CD Integration
The build script is designed for automation:
```yaml
# Example GitHub Actions workflow
name: Build ISO
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build ISO
run: ./build-iso-complete.sh --local
- name: Upload ISO
uses: actions/upload-artifact@v3
with:
name: archipelago-iso
path: image-recipe/results/*.iso
```
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ build-iso-complete.sh (Orchestrator) │
└─────────────────┬───────────────────────────────────────┘
│
┌─────────┼─────────┐
│ │ │
┌────▼───┐ ┌──▼───┐ ┌───▼────────┐
│Backend │ │Front │ │ISO Builder │
│(Rust) │ │(Vue) │ │(Debian) │
└────┬───┘ └──┬───┘ └───┬────────┘
│ │ │
└────────┼─────────┘
│
┌────────▼────────┐
│ Bootable ISO │
│ (1.2 GB) │
└─────────────────┘
```
## Output
Successful build produces:
```
✅ ISO ready for flashing!
📀 ISO: /Users/dorian/Projects/archy/image-recipe/results/archipelago-debian-12-x86_64.iso
📏 Size: 1.2G
🔐 MD5: a3f2d8c9e4b1...
Next steps:
1. Insert USB drive
2. Find device: diskutil list
3. Flash ISO:
cd image-recipe && ./write-usb-dd.sh /dev/diskN
4. Boot from USB on target device
```
## Support
For issues or questions:
- Check the troubleshooting section above
- Review logs in `image-recipe/iso-workdir/build.log`
- Open an issue on GitHub
## License
Same as Archipelago project - see main LICENSE file
1. Test the ISO on VM
2. Verify web UI loads
3. Test container deployment
4. Document any issues
5. Tag the release in git
6. Upload ISO to distribution point