archy/.cursor/rules/Development-Workflow.md

# Archipelago Development Workflow

## Overview

Archipelago is a Bitcoin Node OS that users install from a bootable USB. We develop on a live development server, then package that server's state into an auto-installer ISO.

## Target Experience (Like Other Bitcoin Nodes)

Users interact with Archipelago like **Umbrel**, **Start9**, **RaspiBlitz**:
1. Flash ISO to USB
2. Boot from USB → Auto-installer runs
3. Installer detects internal disk and installs Archipelago
4. Remove USB, reboot
5. **Access web UI at http://<IP>** (port 80, served by Nginx)
6. Manage Bitcoin, Lightning, apps through web interface

## Development Workflow

### 1. Development Server (Primary Development Environment)

**Server**: `archipelago@192.168.1.228`
**Purpose**: Live development and testing environment

This is where ALL development happens:
- Backend changes: `/usr/local/bin/archipelago` (Rust binary)
- Frontend changes: `/opt/archipelago/web-ui` (Vue.js, served by Nginx on port 80)
- Backend API: `localhost:5678` (proxied by Nginx)
- System configs: Nginx, systemd services, etc.
- Container apps: Podman containers for Bitcoin, LND, etc.

**CRITICAL**: This is the AUTHORITATIVE source. The ISO must capture THIS server's exact state.

### 2. Build Process (Snapshot → ISO)

**Goal**: Create an auto-installer ISO that installs the EXACT state of the dev server

**Process**:
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`)
   - Capture system configs (Nginx, systemd, etc.)
   - Capture app manifests and configs
   
2. **Package into bootable ISO**:
   - Base: Debian Live (minimal installer environment)
   - Includes: Pre-built rootfs with all Archipelago components
   - Auto-installer script detects internal disk and installs system
   
3. **Result**: Bootable ISO that users can flash to USB

### 3. ISO Flash & Install (End User Experience)

**User steps**:
1. Flash `archipelago-installer-x86_64.iso` to USB
2. Boot from USB
3. Press Enter at "Install Archipelago" prompt
4. Installer automatically:
   - Detects internal disk (NVMe/SSD)
   - Creates partitions (EFI + Root)
   - Installs Archipelago system
   - Installs GRUB bootloader
   - Shows "INSTALLATION COMPLETE" with Web UI URL
5. Remove USB and reboot
6. Access Web UI at `http://<IP>`

### 4. Deployment Targets

- **Development Server**: `192.168.1.228` (always up to date)
- **Test Devices**: 
  - Dell OptiPlex (current test device)
  - Start9 Server Pure (Intel i7, NVMe)
  - HP ProDesk 400 G4 DM
- **Production**: Any x86_64 device with NVMe/SSD

## Architecture

### Frontend (Web UI)
- **Framework**: Vue.js 3 + Vite
- **Build Output**: `web/dist/neode-ui/` (NOT `neode-ui/dist/`)
- **Deployment**: Copied to `/opt/archipelago/web-ui` on dev server
- **Served By**: Nginx on port 80
- **API Proxy**: Nginx proxies `/rpc/`, `/ws/`, `/health` to `localhost:5678`

### Backend (API Server)
- **Language**: Rust
- **Binary Location**: `/usr/local/bin/archipelago`
- **Bind Address**: `0.0.0.0:5678`
- **Systemd Service**: `archipelago.service`
- **Managed By**: systemd (auto-start on boot)

### System Integration
- **OS**: Debian 12 (Bookworm)
- **Web Server**: Nginx (port 80)
- **Container Runtime**: Podman (rootless)
- **Apps**: Bitcoin Core, LND, BTCPay, Nostr relays, etc.

## Build Scripts

### `build-auto-installer-iso.sh` (CORRECT SCRIPT)
Creates a bootable auto-installer ISO (like the working build from this morning).

**Features**:
- Pre-built rootfs (no network needed during install)
- Auto-detects internal disk
- One-button installation
- Boots directly to web UI after install
- Pre-bundles container images (Bitcoin, LND, etc.)

**Usage**:
```bash
cd image-recipe
sudo bash build-auto-installer-iso.sh
```

**IMPORTANT**: Must capture LIVE SERVER state, not build from source.

### `build-debian-iso.sh` (DEPRECATED)
Creates a live system ISO (boots into a live environment, doesn't install).
**DO NOT USE** - This was causing the boot-to-prompt issue.

## Deployment to Dev Server

When making changes locally:

1. **Backend**:
   ```bash
   # Build on remote server (Linux target)
   ssh archipelago@192.168.1.228
   cd ~/archy/core
   cargo build --release --bin archipelago
   sudo cp target/release/archipelago /usr/local/bin/
   sudo systemctl restart archipelago
   ```

2. **Frontend**:
   ```bash
   # Build locally (macOS)
   cd neode-ui
   npm run build
   
   # Deploy to server
   rsync -avz ../web/dist/neode-ui/ archipelago@192.168.1.228:/tmp/neode-ui-build/
   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'
   ```

## CRITICAL RULES

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

## Testing Checklist

Before creating ISO:
- [ ] Backend running on dev server (`curl http://192.168.1.228:5678/health`)
- [ ] Frontend accessible (`curl http://192.168.1.228/`)
- [ ] Web UI shows correct apps and icons
- [ ] API calls working (check browser console)
- [ ] All systemd services enabled and running

After flashing ISO:
- [ ] ISO boots to installer menu
- [ ] Auto-installer detects internal disk
- [ ] Installation completes without errors
- [ ] System reboots and shows Web UI URL
- [ ] Web UI accessible at `http://<IP>`
- [ ] Backend API responding
- [ ] Apps visible in marketplace

## Common Issues

**Issue**: ISO boots to prompt instead of auto-starting
- **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**: Frontend not updating on server
- **Cause**: Building to wrong output directory or not deploying to correct Nginx root
- **Fix**: Build to `web/dist/neode-ui/`, deploy to `/opt/archipelago/web-ui`

**Issue**: ISO doesn't have latest changes
- **Cause**: Building from source instead of capturing live server state
- **Fix**: Modify build script to snapshot dev server, not compile from scratch

## Next Steps

- [ ] Fix `build-auto-installer-iso.sh` to capture live server state
- [ ] Create snapshot script for dev server
- [ ] Document container image bundling process
- [ ] Create automated testing framework
- [ ] Set up CI/CD for ISO builds