lfg2025/archy
1
0
Fork 0
Code Issues 27 Pull Requests 4 Actions Packages Projects Releases 3 Wiki Activity

Enhance development workflow and deployment practices for Archipelago

Browse Source 
- Updated the Development-Workflow documentation to clarify deployment strategy, emphasizing direct deployment to the live system for testing.
- Added detailed instructions for the deployment command, including syncing code, building frontend and backend, and restarting services.
- Improved SSH key management section to assist with authentication issues.
- Expanded the testing workflow to include steps for checking logs and syncing changes back to the ISO build.
- Updated the ISO build integration section to ensure system-level changes are captured for future builds.
- Refactored various sections for clarity and completeness, including deployment paths and system configuration files.
This commit is contained in:
Dorian
2026-02-01 13:24:03 +00:00
parent 00d1af12f0
commit 34fc06726e
28 changed files with 1248 additions and 285 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/rules/Development-Workflow.mdc
+131 -121
View File
@@ -1,136 +1,146 @@
---
description: Development workflow and deployment practices for Archipelago
alwaysApply: true
---
# Archipelago Development Workflow
## Overview
## Deployment Strategy
Development happens on Mac (editing in Cursor), with the HP ProDesk running Archipelago as the live test target via SSH.
**Always deploy to live system for testing** - The target device (192.168.1.228) is a development machine, so deploy changes directly to the live system rather than using dev servers.
## Architecture
```
┌─────────────────────┐ SSH/rsync ┌─────────────────────┐
│ Mac (Dev Host) │ ──────────────────────────▶│ HP ProDesk (Target)│
│ │ │ │
│ • Cursor IDE │ │ • Archipelago OS │
│ • Source code │ │ • Live testing │
│ • ISO builds │ │ • Vue.js dev server│
│ │ │ • Rust backend │
└─────────────────────┘ └─────────────────────┘
```
## Target Machine Setup
**SSH Access:**
```bash
ssh archipelago@192.168.1.228
# Password: archipelago
```
**Required packages on target (install once):**
```bash
sudo apt update && sudo apt install -y \
nodejs npm \
rustc cargo \
git \
build-essential
```
## Development Commands
### Sync Code to Target
```bash
# From Mac - sync entire project
rsync -avz --exclude 'node_modules' --exclude 'target' --exclude 'dist' \
/Users/dorian/Projects/archy/ \
archipelago@192.168.1.228:/home/archipelago/archy/
# Or just the frontend
rsync -avz --exclude 'node_modules' \
/Users/dorian/Projects/archy/neode-ui/ \
archipelago@192.168.1.228:/home/archipelago/archy/neode-ui/
```
### Frontend Development (Vue.js)
```bash
# On target via SSH
cd ~/archy/neode-ui
npm install
npm run dev -- --host 0.0.0.0
# Access from Mac browser: http://192.168.1.228:5173
```
### Backend Development (Rust)
```bash
# On target via SSH
cd ~/archy/core
cargo build --release
# Test run
./target/release/archipelago
```
### Quick Deploy Script
Create `~/deploy.sh` on Mac:
```bash
#!/bin/bash
TARGET="archipelago@192.168.1.228"
PROJECT="/Users/dorian/Projects/archy"
# Sync code
rsync -avz --exclude 'node_modules' --exclude 'target' --exclude 'dist' \
"$PROJECT/" "$TARGET:/home/archipelago/archy/"
# Rebuild on target
ssh $TARGET "cd ~/archy/neode-ui && npm install && npm run build"
ssh $TARGET "cd ~/archy/core && cargo build --release"
# Deploy to live system
ssh $TARGET "sudo cp ~/archy/core/target/release/archipelago /usr/local/bin/"
ssh $TARGET "sudo cp -r ~/archy/neode-ui/dist/* /opt/archipelago/web-ui/"
ssh $TARGET "sudo systemctl restart archipelago"
echo "Deployed! Check http://192.168.1.228"
```
## ISO Builds
ISO builds still happen on Mac (requires Docker Desktop for creating rootfs):
### Standard Deployment Command
```bash
cd /Users/dorian/Projects/archy/image-recipe
./build-auto-installer-iso.sh
./scripts/deploy-to-target.sh --live
```
**Docker Desktop is required for:**
- Building the Debian rootfs tarball
- Creating squashfs overlay modules
- Pulling/saving container images for bundling
This command:
1. Syncs code from local Mac to remote target
2. Builds frontend (Vue.js) and backend (Rust)
3. Deploys to live paths:
- Frontend: `/opt/archipelago/web-ui/`
- Backend: `/usr/local/bin/archipelago`
4. Restarts services (systemd + nginx)
## File Locations
### Target Environment
| Component | Mac (Source) | Target (Dev) | Target (Live) |
|-----------|--------------|--------------|---------------|
| Frontend | `neode-ui/` | `~/archy/neode-ui/` | `/opt/archipelago/web-ui/` |
| Backend | `core/` | `~/archy/core/` | `/usr/local/bin/archipelago` |
| App manifests | `apps/` | `~/archy/apps/` | `/etc/archipelago/apps/` |
- **Host**: archipelago@192.168.1.228
- **OS**: Debian-based server
- **Container Runtime**: Podman (root context for system services)
- **Web Server**: Nginx
- **Backend**: Systemd service (`archipelago.service`) running as root
## What You Can Remove from Mac
## SSH Key Management
**Keep:**
- Docker Desktop (needed for ISO builds)
- Node.js/npm (for local editing/linting)
- Cursor IDE
The deployment scripts require SSH key authentication. If you encounter `Permission denied` errors:
**Can remove:**
- Any local test containers
- Podman (if installed)
- Local development servers (test on target instead)
1. Ensure SSH key is loaded: `ssh-add -l`
2. Add key if needed: `ssh-add ~/.ssh/id_ed25519`
3. Enter passphrase when prompted
## Workflow Summary
## Development Paths
1. **Edit** code in Cursor on Mac
2. **Sync** to HP ProDesk with rsync
3. **Test** on target (run dev server or deploy to live)
4. **Iterate** until working
5. **Build ISO** on Mac when ready for distribution
6. **Flash & test** ISO on HP ProDesk
### Local (Mac)
- Project root: `/Users/dorian/Projects/archy`
- Frontend: `neode-ui/`
- Backend: `core/`
- Scripts: `scripts/`
- ISO Build: `image-recipe/`
### Remote (Target)
- Dev directory: `~/archy/`
- Live frontend: `/opt/archipelago/web-ui/`
- Live backend: `/usr/local/bin/archipelago`
- Data: `/var/lib/archipelago/`
- Systemd service: `/etc/systemd/system/archipelago.service`
- Nginx config: `/etc/nginx/sites-available/archipelago`
## Testing Workflow
1. Make changes locally
2. Deploy with `--live` flag
3. Test at http://192.168.1.228
4. Check logs if needed:
- Backend: `ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago -f'`
- Nginx: `ssh archipelago@192.168.1.228 'sudo tail -f /var/log/nginx/error.log'`
5. **Sync changes back to ISO build** (see below)
## Running Containers
Check container status:
```bash
ssh archipelago@192.168.1.228 'sudo podman ps'
```
Common containers:
- Home Assistant (port 8123)
- Bitcoin Knots (ports 8332, 8333)
- LND (ports 9735, 10009)
## ISO Build Integration
**CRITICAL**: After testing on the live server, always update the ISO build to include your changes.
### System Configuration Files to Sync
When you make system-level changes on the live server, capture them for the ISO build:
1. **Systemd Service** (`/etc/systemd/system/archipelago.service`)
- Location in repo: `image-recipe/configs/archipelago.service`
- Capture command: `ssh archipelago@192.168.1.228 'sudo cat /etc/systemd/system/archipelago.service' > image-recipe/configs/archipelago.service`
2. **Nginx Configuration** (`/etc/nginx/sites-available/archipelago`)
- Location in repo: `image-recipe/configs/nginx-archipelago.conf`
- Capture command: `ssh archipelago@192.168.1.228 'sudo cat /etc/nginx/sites-available/archipelago' > image-recipe/configs/nginx-archipelago.conf`
3. **Other System Files**
- Logrotate: `image-recipe/configs/logrotate.conf`
- Any new scripts in `/opt/archipelago/scripts/`
### Build Process Checklist
Before building a new ISO, ensure:
- [ ] Latest backend built: `cd image-recipe && ./scripts/build-backend.sh`
- [ ] Latest frontend built: `cd image-recipe && ./scripts/build-frontend.sh`
- [ ] System configs synced from live server
- [ ] Integration script updated: `./integrate-archipelago.sh`
- [ ] ISO built: `./build-debian-iso.sh`
- [ ] ISO tested in QEMU: `./test-iso-qemu.sh`
### Key Configuration Values
**Backend Service (archipelago.service)**:
- **User**: `root` (required to access root Podman containers)
- **Environment**:
- `ARCHIPELAGO_BIND=0.0.0.0:5678`
- `ARCHIPELAGO_DEV_MODE=true` (for container auto-detection)
**Nginx Configuration**:
- Serves frontend from `/opt/archipelago/web-ui`
- Proxies `/rpc/` to backend at `127.0.0.1:5678`
- Proxies `/ws` for WebSocket connections
### Deployment Paths in ISO
The ISO build must install files to:
- `/usr/local/bin/archipelago` - Backend binary
- `/opt/archipelago/web-ui/` - Frontend files
- `/etc/systemd/system/archipelago.service` - Service definition
- `/etc/nginx/sites-available/archipelago` - Nginx config
- `/opt/archipelago/` - Base directory for scripts and data
## Common Issues
### Container Detection
- Containers must be in **root Podman context** (started with `sudo podman`)
- Backend must run as **root** to see root containers
- Check: `sudo podman ps` (should show containers)
- Check: `podman ps` (should be empty if using root containers)
### Service Not Starting
- Check systemd status: `sudo systemctl status archipelago`
- Check logs: `sudo journalctl -u archipelago -n 50`
- Verify binary: `ls -lh /usr/local/bin/archipelago`
- Test manually: `sudo /usr/local/bin/archipelago`