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
|
## 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
|
```bash
|
||||||
# Build on remote server (Linux target)
|
# Option 1: SSH and build directly on server
|
||||||
ssh archipelago@192.168.1.228
|
ssh archipelago@192.168.1.228
|
||||||
cd ~/archy/core
|
cd ~/archy/core/archipelago
|
||||||
|
source ~/.cargo/env # Load Rust environment
|
||||||
cargo build --release --bin archipelago
|
cargo build --release --bin archipelago
|
||||||
sudo cp target/release/archipelago /usr/local/bin/
|
sudo systemctl stop archipelago
|
||||||
sudo systemctl restart 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
|
```bash
|
||||||
# Build locally (macOS)
|
# Build locally (macOS is fine for frontend)
|
||||||
cd neode-ui
|
cd neode-ui
|
||||||
npm run build
|
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'
|
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
|
## CRITICAL RULES
|
||||||
|
|
||||||
|
### 🚨 NEVER VIOLATE THESE
|
||||||
|
|
||||||
1. **ALWAYS deploy to the live development server (192.168.1.228)** for testing
|
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
|
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/`
|
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`
|
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`
|
- **Cause**: Using `build-debian-iso.sh` (live system) instead of `build-auto-installer-iso.sh`
|
||||||
- **Fix**: Use correct auto-installer script
|
- **Fix**: Use correct auto-installer script
|
||||||
|
|
||||||
**Issue**: macOS backend binary on Linux server
|
**Issue**: macOS backend binary on Linux server ("Exec format error")
|
||||||
- **Cause**: Building backend on macOS and copying to Linux
|
- **Cause**: Compiling Rust backend on macOS and copying to Linux server
|
||||||
- **Fix**: Always build backend on the Linux dev 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
|
**Issue**: Frontend not updating on server
|
||||||
- **Cause**: Building to wrong output directory or not deploying to correct Nginx root
|
- **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
|
// Bitcoin UI runs on host network at port 8334
|
||||||
debug!("Using bitcoin-ui for bitcoin-knots: http://localhost:8334");
|
debug!("Using bitcoin-ui for bitcoin-knots: http://localhost:8334");
|
||||||
Some("http://localhost:8334".to_string())
|
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" {
|
} else if app_id == "tailscale" {
|
||||||
// Tailscale uses host networking, so no port mappings
|
// Tailscale uses host networking, so no port mappings
|
||||||
// But web UI is always on port 8240
|
// But web UI is always on port 8240
|
||||||
|
|||||||
@ -10,6 +10,7 @@ export interface ContainerStatus {
|
|||||||
image: string
|
image: string
|
||||||
created: string
|
created: string
|
||||||
ports: string[]
|
ports: string[]
|
||||||
|
lan_address?: string // Launch URL for the app's UI
|
||||||
}
|
}
|
||||||
|
|
||||||
export interface ContainerAppInfo {
|
export interface ContainerAppInfo {
|
||||||
|
|||||||
@ -13,6 +13,7 @@ export interface BundledApp {
|
|||||||
ports: { host: number; container: number }[]
|
ports: { host: number; container: number }[]
|
||||||
volumes: { host: string; container: string }[]
|
volumes: { host: string; container: string }[]
|
||||||
category: 'bitcoin' | 'lightning' | 'home' | 'other'
|
category: 'bitcoin' | 'lightning' | 'home' | 'other'
|
||||||
|
lan_address?: string // Runtime launch URL from backend
|
||||||
}
|
}
|
||||||
|
|
||||||
export const BUNDLED_APPS: BundledApp[] = [
|
export const BUNDLED_APPS: BundledApp[] = [
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user