Enhance README and RPC for package management
- Added instructions to README.md for building an ISO from source and flashing it to USB. - Introduced a new RPC method for package installation, including security checks and container management. - Updated Docker and Podman integration in build scripts to support both container runtimes. - Enhanced Nginx configuration for improved timeout settings and WebSocket support. - Added new app metadata for additional applications in the Docker package scanner.
This commit is contained in:
Dorian
+296
@@ -0,0 +1,296 @@
|
||||
# Archipelago ISO Build System
|
||||
|
||||
Complete, robust build system for creating flashable Archipelago ISO images from source.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### One-Command Build (Recommended)
|
||||
|
||||
Build everything and create a flashable ISO with a single command:
|
||||
|
||||
```bash
|
||||
# Build on remote server (recommended for x86_64 target)
|
||||
./build-iso-complete.sh --remote archipelago@192.168.1.228
|
||||
|
||||
# Or build locally (if you have Rust + Node.js)
|
||||
./build-iso-complete.sh --local
|
||||
```
|
||||
|
||||
### Flash to USB
|
||||
|
||||
After building:
|
||||
|
||||
```bash
|
||||
# Find your USB device
|
||||
diskutil list
|
||||
|
||||
# Flash (will prompt for confirmation)
|
||||
./flash-to-usb.sh /dev/diskN
|
||||
```
|
||||
|
||||
## Build Options
|
||||
|
||||
```bash
|
||||
./build-iso-complete.sh [options]
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Backend Build Fails
|
||||
```bash
|
||||
# Check Rust installation
|
||||
cargo --version
|
||||
|
||||
# Update Rust
|
||||
rustup update
|
||||
|
||||
# Clean and rebuild
|
||||
./build-iso-complete.sh --remote HOST --clean
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### ISO Build Fails
|
||||
```bash
|
||||
# Check available disk space (needs ~2GB)
|
||||
df -h
|
||||
|
||||
# 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
|
||||
Reference in New Issue
Block a user