lfg2025/archy
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 33 Wiki Activity

Enhance ISO build process and documentation for Archipelago

Browse Source 
- Updated BUILD-GUIDE.md to clarify instructions for building the Archipelago Auto-Installer ISO, emphasizing the recommended method of building directly on the target server.
- Added auto-installation of missing dependencies (xorriso, podman) when running the build script with sudo.
- Enhanced the build-auto-installer-iso.sh script to capture container images from the live server, ensuring the ISO includes the same set of applications as the dev server.
- Revised deployment documentation to stress the importance of building the Rust backend on the Linux dev server and included new instructions for capturing system-level changes for ISO builds.
- Improved UI components and added new bundled applications (BTCPay Server, Mempool Explorer, Nostr Relay, Strfry Relay, Tailscale) to enhance user experience.
This commit is contained in:
Dorian
2026-02-14 16:44:20 +00:00
parent d988396111
commit 6035c93289
19 changed files with 824 additions and 406 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
.cursor/rules/Development-Workflow.md
View File

@@ -38,6 +38,7 @@ This is where ALL development happens:
1. **Snapshot the dev server** (192.168.1.228):
- Capture current backend binary (`/usr/local/bin/archipelago`)
- Capture current frontend files (`/opt/archipelago/web-ui`)
- When `DEV_SERVER` is set: capture container images from the live server so the ISO prepackages current apps
- Capture system configs (Nginx, systemd, etc.)
- Capture app manifests and configs
@@ -120,6 +121,12 @@ Creates a live system ISO (boots into a live environment, doesn't install).
## Deployment to Dev Server
### Dev server access
- **Host:** `archipelago@192.168.1.228`
- **Password:** `archipelago` — use this for deployment. For non-interactive sync/deploy from scripts or the agent, use: `sshpass -p "archipelago"` (e.g. `sshpass -p "archipelago" rsync ...` or prepend it to ssh/rsync when running `./scripts/deploy-to-target.sh` or equivalent).
- **Build approach:** We build **directly on the server** by SSHing in and running `cargo build --release` there. Do not build the backend on macOS and copy the binary.
### ⚠️ CRITICAL: Backend Compilation Architecture
**NEVER compile the Rust backend on macOS and deploy to Linux!**
@@ -133,23 +140,20 @@ The dev server (`192.168.1.228`) is **x86_64 Linux (Debian 12)**. Binaries compi
### Deployment Procedures
1. **Backend** (MUST build on Linux):
1. **Backend** (MUST build on Linux — use rsync then build on server):
```bash
# Option 1: SSH and build directly on server
ssh archipelago@192.168.1.228
cd ~/archy/core/archipelago
source ~/.cargo/env # Load Rust environment
cargo build --release --bin archipelago
sudo systemctl stop archipelago
sudo cp ../target/release/archipelago /usr/local/bin/
sudo systemctl start archipelago
# Option 2: Update source and build remotely
# From local machine:
scp core/archipelago/src/**/*.rs archipelago@192.168.1.228:~/archy/core/archipelago/src/
ssh archipelago@192.168.1.228 'source ~/.cargo/env && cd ~/archy/core/archipelago && cargo build --release'
ssh archipelago@192.168.1.228 'sudo systemctl stop archipelago && sudo cp ~/archy/core/target/release/archipelago /usr/local/bin/ && sudo systemctl start archipelago'
# From project root. Sync source to server (exclude local target/.git).
sshpass -p "archipelago" rsync -avz --exclude target --exclude .git -e "ssh -o StrictHostKeyChecking=no" \
core/ archipelago@192.168.1.228:~/archy/core/
# Build on server and deploy binary
sshpass -p "archipelago" ssh -o StrictHostKeyChecking=no archipelago@192.168.1.228 \
'source ~/.cargo/env && cd ~/archy/core/archipelago && cargo build --release && \
sudo systemctl stop archipelago && \
sudo cp ~/archy/core/target/release/archipelago /usr/local/bin/ && \
sudo systemctl start archipelago'
```
**Do not** build the binary on macOS and copy it; always rsync source and build on the server.
2. **Frontend** (can build locally):
```bash
@@ -175,16 +179,17 @@ The dev server (`192.168.1.228`) is **x86_64 Linux (Debian 12)**. Binaries compi
### 🚨 NEVER VIOLATE THESE
1. **ALWAYS deploy to the live development server (192.168.1.228)** for testing
2. **🔴 NEVER EVER compile the Rust backend on macOS and deploy to Linux**
2. **After every change: sync and build on the live server.** When you finish implementing a feature or fix, run the deploy script so the live server has the latest code. Command: `./scripts/deploy-to-target.sh --live` (from project root). If SSH is not available in the current environment, tell the user to run it locally. Do not skip this step. **App UIs** (e.g. `docker/lnd-ui/`, `docker/bitcoin-ui/`) are served by their own containers; the deploy script rebuilds the LND UI image and restarts its container so changes to the LND UI are visible after deploy.
3. **🔴 NEVER EVER compile the Rust backend on macOS and deploy to Linux**
- Dev server is `x86_64 Linux (Debian 12)`
- Always build backend **ON the Linux server** using `source ~/.cargo/env && cargo build --release`
- macOS binaries will cause "Exec format error" and break the system
- Frontend (Vue.js) CAN be built on macOS - it's just HTML/CSS/JS
3. **The ISO must capture the CURRENT STATE of the dev server**, not build from source
4. **Frontend build output is in `web/dist/neode-ui/`**, NOT `neode-ui/dist/`
5. **Nginx serves on port 80** and proxies backend on `localhost:5678`
6. **App icons are in `neode-ui/public/assets/img/app-icons/`**
7. **The auto-installer ISO is the ONLY way to deploy** - no live systems
4. **The ISO must capture the CURRENT STATE of the dev server**, not build from source
5. **Frontend build output is in `web/dist/neode-ui/`**, NOT `neode-ui/dist/`
6. **Nginx serves on port 80** and proxies backend on `localhost:5678`
7. **App icons are in `neode-ui/public/assets/img/app-icons/`**
8. **The auto-installer ISO is the ONLY way to deploy** - no live systems
## Testing Checklist

33
.cursor/rules/Development-Workflow.mdc
View File

@@ -9,6 +9,10 @@ alwaysApply: true
**Always deploy to live system for testing** - The target device (192.168.1.228) is a development machine, so deploy changes directly to the live system rather than using dev servers.
### Backend: build on server via rsync (never on macOS)
- **Always** deploy backend by: (1) rsync `core/` to `archipelago@192.168.1.228:~/archy/core/`, then (2) SSH and run `cargo build --release` on the server, then copy binary to `/usr/local/bin/` and restart `archipelago.service`.
- Use `sshpass -p "archipelago"` for non-interactive rsync/SSH. **Action these builds** when making backend changes; do not build the Rust binary on macOS and copy it (causes Exec format error on Linux).
### Standard Deployment Command
```bash
@@ -82,6 +86,35 @@ Common containers:
**CRITICAL**: After testing on the live server, always update the ISO build to include your changes.
### Building the ISO
**Recommended**: Build on the target server (has all dependencies):
```bash
# SSH to target server
ssh archipelago@192.168.1.228
# Navigate to project
cd ~/archy/image-recipe
# Run build with sudo (auto-installs missing deps like xorriso)
sudo ./build-auto-installer-iso.sh
# The ISO will be at: results/archipelago-auto-installer-*.iso
# Copy back to Mac
# On your Mac:
scp archipelago@192.168.1.228:~/archy/image-recipe/results/archipelago-auto-installer-*.iso .
```
**Alternative**: Build from Mac (requires Docker Desktop installed).
### Common ISO Build Issues
- **Missing xorriso**: Run with `sudo` to auto-install, or: `sudo apt install -y xorriso`
- **Missing podman**: Run with `sudo` to auto-install, or: `sudo apt install -y podman`
- **No Docker on Mac**: Either install Docker Desktop or build on target server (recommended)
### System Configuration Files to Sync
When you make system-level changes on the live server, capture them for the ISO build:

38
.cursor/rules/coding-rules.mdc
View File

@@ -439,6 +439,13 @@
## Development Workflow
### Backend: always build on the dev server (never on macOS)
- **CRITICAL**: The Rust backend **must** be built **on the Linux dev server**, not on macOS. Deploy by **rsync then build**:
1. **Rsync** source to server: `sshpass -p "archipelago" rsync -avz --exclude target --exclude .git -e "ssh -o StrictHostKeyChecking=no" core/ archipelago@192.168.1.228:~/archy/core/`
2. **Build and deploy on server**: `sshpass -p "archipelago" ssh -o StrictHostKeyChecking=no archipelago@192.168.1.228 'source ~/.cargo/env && cd ~/archy/core/archipelago && cargo build --release && sudo systemctl stop archipelago && sudo cp ~/archy/core/target/release/archipelago /usr/local/bin/ && sudo systemctl start archipelago'`
- When making backend changes, **action the build**: run the rsync + SSH build/deploy steps above. Do not build the binary locally and copy it (causes Exec format error on Linux).
- Dev server: `archipelago@192.168.1.228`, password: `archipelago`.
### Scripts & Automation
- ✅ All scripts in `scripts/` directory
- ✅ Use `#!/usr/bin/env bash` for portability
@@ -507,21 +514,22 @@
15. **Depend on external registries** - Host our own or use Docker Hub
### ✅ ALWAYS DO:
1. **Use workspace-relative paths** - Portable code
2. **Create global Tailwind classes** - Consistent styling
3. **Build Archipelago-native solutions** - Clean architecture
4. **Include security in all containers** - Security first
5. **Use environment variables** - Configurable deployments
6. **Add modules to Cargo.toml** - Workspace coherence
7. **Create reusable components** - DRY principle
8. **Use Docker (dev) or Podman (prod)** - Standard containers
9. **Handle all errors gracefully** - User-friendly messages
10. **Follow the architecture plan** - Consistency
11. **Write tests** - Prevent regressions
12. **Document code** - Help future contributors
13. **Review your own code** - Catch issues early
14. **Run CI checks locally** - Before pushing
15. **Think production first** - Build it right
1. **Build backend on the dev server** - Rsync `core/` to `archipelago@192.168.1.228:~/archy/core/`, then SSH in and run `cargo build --release` and deploy the binary. Never build the Rust binary on macOS for deployment.
2. **Use workspace-relative paths** - Portable code
3. **Create global Tailwind classes** - Consistent styling
4. **Build Archipelago-native solutions** - Clean architecture
5. **Include security in all containers** - Security first
6. **Use environment variables** - Configurable deployments
7. **Add modules to Cargo.toml** - Workspace coherence
8. **Create reusable components** - DRY principle
9. **Use Docker (dev) or Podman (prod)** - Standard containers
10. **Handle all errors gracefully** - User-friendly messages
11. **Follow the architecture plan** - Consistency
12. **Write tests** - Prevent regressions
13. **Document code** - Help future contributors
14. **Review your own code** - Catch issues early
15. **Run CI checks locally** - Before pushing
16. **Think production first** - Build it right
## Architecture Adherence