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.
This commit is contained in:
Dorian 2026-02-03 22:06:45 +00:00
parent 47a56e2212
commit 59072bd16c
4 changed files with 63 additions and 12 deletions

View File

@ -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/<app-name>
podman build -t localhost/<app-name>:latest .
podman save localhost/<app-name>: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

View File

@ -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

View File

@ -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 {

View File

@ -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[] = [