From 59072bd16c55da8beb77f5e957695d85515f50c7 Mon Sep 17 00:00:00 2001 From: Dorian Date: Tue, 3 Feb 2026 22:06:45 +0000 Subject: [PATCH] Revise Development-Workflow documentation and enhance backend deployment instructions - Added critical warnings against compiling the Rust backend on macOS for deployment to Linux, detailing the reasons and potential errors. - Updated deployment procedures for the backend to ensure builds are performed directly on the Linux dev server. - Included new instructions for building container images with Docker/Podman and clarified frontend build processes. - Enhanced the critical rules section to emphasize the importance of following deployment protocols to avoid system errors. --- .cursor/rules/Development-Workflow.md | 69 +++++++++++++++---- .../src/container/docker_packages.rs | 4 ++ neode-ui/src/api/container-client.ts | 1 + neode-ui/src/stores/container.ts | 1 + 4 files changed, 63 insertions(+), 12 deletions(-) diff --git a/.cursor/rules/Development-Workflow.md b/.cursor/rules/Development-Workflow.md index 56d9d39d..3a99d994 100644 --- a/.cursor/rules/Development-Workflow.md +++ b/.cursor/rules/Development-Workflow.md @@ -120,21 +120,40 @@ Creates a live system ISO (boots into a live environment, doesn't install). ## Deployment to Dev Server -When making changes locally: +### ⚠️ CRITICAL: Backend Compilation Architecture -1. **Backend**: +**NEVER compile the Rust backend on macOS and deploy to Linux!** + +The dev server (`192.168.1.228`) is **x86_64 Linux (Debian 12)**. Binaries compiled on macOS (even with cross-compilation) can cause "Exec format error" due to: +- Different architecture (macOS ARM64/Intel vs Linux x86_64) +- Different libc (macOS vs glibc) +- Different system call interfaces + +**ALWAYS build the backend directly on the Linux dev server.** + +### Deployment Procedures + +1. **Backend** (MUST build on Linux): ```bash - # Build on remote server (Linux target) + # Option 1: SSH and build directly on server ssh archipelago@192.168.1.228 - cd ~/archy/core + cd ~/archy/core/archipelago + source ~/.cargo/env # Load Rust environment cargo build --release --bin archipelago - sudo cp target/release/archipelago /usr/local/bin/ - sudo systemctl restart 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' ``` -2. **Frontend**: +2. **Frontend** (can build locally): ```bash - # Build locally (macOS) + # Build locally (macOS is fine for frontend) cd neode-ui npm run build @@ -143,10 +162,24 @@ When making changes locally: ssh archipelago@192.168.1.228 'sudo rm -rf /opt/archipelago/web-ui/* && sudo cp -r /tmp/neode-ui-build/* /opt/archipelago/web-ui/ && sudo chown -R www-data:www-data /opt/archipelago/web-ui' ``` +3. **Container Images** (Docker/Podman): + ```bash + # Build locally and push to server + cd docker/ + podman build -t localhost/:latest . + podman save localhost/:latest | ssh archipelago@192.168.1.228 'podman load' + ``` + ## CRITICAL RULES +### 🚨 NEVER VIOLATE THESE + 1. **ALWAYS deploy to the live development server (192.168.1.228)** for testing -2. **NEVER build macOS binaries for Linux deployment** (backend must be built on Linux) +2. **🔴 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` @@ -177,9 +210,21 @@ After flashing ISO: - **Cause**: Using `build-debian-iso.sh` (live system) instead of `build-auto-installer-iso.sh` - **Fix**: Use correct auto-installer script -**Issue**: macOS backend binary on Linux server -- **Cause**: Building backend on macOS and copying to Linux -- **Fix**: Always build backend on the Linux dev server +**Issue**: macOS backend binary on Linux server ("Exec format error") +- **Cause**: Compiling Rust backend on macOS and copying to Linux server +- **Symptom**: `systemd` service fails with "status=203/EXEC" and "Failed to execute: Exec format error" +- **Why it happens**: Different architectures and system ABIs between macOS and Linux +- **Fix**: **ALWAYS build the backend ON the Linux server**: + ```bash + ssh archipelago@192.168.1.228 + cd ~/archy/core/archipelago + source ~/.cargo/env + cargo build --release + sudo systemctl stop archipelago + sudo cp ../target/release/archipelago /usr/local/bin/ + sudo systemctl start archipelago + ``` +- **Prevention**: Never use local `cargo build` for deployment - always build on target system **Issue**: Frontend not updating on server - **Cause**: Building to wrong output directory or not deploying to correct Nginx root diff --git a/core/archipelago/src/container/docker_packages.rs b/core/archipelago/src/container/docker_packages.rs index 9a699e52..ac244aa2 100644 --- a/core/archipelago/src/container/docker_packages.rs +++ b/core/archipelago/src/container/docker_packages.rs @@ -100,6 +100,10 @@ impl DockerPackageScanner { // Bitcoin UI runs on host network at port 8334 debug!("Using bitcoin-ui for bitcoin-knots: http://localhost:8334"); Some("http://localhost:8334".to_string()) + } else if app_id == "lnd" { + // LND UI runs on host network at port 8081 + debug!("Using lnd-ui for lnd: http://localhost:8081"); + Some("http://localhost:8081".to_string()) } else if app_id == "tailscale" { // Tailscale uses host networking, so no port mappings // But web UI is always on port 8240 diff --git a/neode-ui/src/api/container-client.ts b/neode-ui/src/api/container-client.ts index a334b9e2..83547db0 100644 --- a/neode-ui/src/api/container-client.ts +++ b/neode-ui/src/api/container-client.ts @@ -10,6 +10,7 @@ export interface ContainerStatus { image: string created: string ports: string[] + lan_address?: string // Launch URL for the app's UI } export interface ContainerAppInfo { diff --git a/neode-ui/src/stores/container.ts b/neode-ui/src/stores/container.ts index 86b063bd..6d870f5a 100644 --- a/neode-ui/src/stores/container.ts +++ b/neode-ui/src/stores/container.ts @@ -13,6 +13,7 @@ export interface BundledApp { ports: { host: number; container: number }[] volumes: { host: string; container: string }[] category: 'bitcoin' | 'lightning' | 'home' | 'other' + lan_address?: string // Runtime launch URL from backend } export const BUNDLED_APPS: BundledApp[] = [