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:
parent
47a56e2212
commit
59072bd16c
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 {
|
||||
|
||||
@ -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[] = [
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user