Archipelago — open-source initial import

2026-08-12 10:55:50 +00:00
commit 1e5d0cd313
1931 changed files with 440577 additions and 0 deletions
@@ -0,0 +1,195 @@
+# Live Server to ISO Build Integration Guide
+
+This document explains how to keep the ISO build synchronized with the live development server.
+
+## Development Workflow
+
+### 1. Develop and Test on Live Server
+
+```bash
+# Make changes locally
+vim core/archipelago/src/...
+
+# Deploy to live server for testing
+./scripts/deploy-to-target.sh --live
+
+# Test at http://192.168.1.228
+# Check logs: ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago -f'
+```
+
+### 2. Capture System Changes
+
+When you make system-level changes on the live server (nginx config, systemd service, etc.):
+
+```bash
+cd image-recipe
+./sync-from-live.sh
+```
+
+This automatically captures:
+- `/etc/systemd/system/archipelago.service` → `configs/archipelago.service`
+- `/etc/nginx/sites-available/archipelago` → `configs/nginx-archipelago.conf`
+- `/etc/logrotate.d/archipelago` → `configs/logrotate.conf`
+
+### 3. Build New ISO
+
+```bash
+# Build backend and frontend
+./scripts/build-backend.sh
+./scripts/build-frontend.sh
+
+# Build ISO with latest changes
+./build-debian-iso.sh
+
+# Test in QEMU
+./test-iso-qemu.sh
+```
+
+### 4. Verify Integration
+
+The ISO build script should:
+1. Copy `configs/archipelago.service` to `/etc/systemd/system/`
+2. Copy `configs/nginx-archipelago.conf` to `/etc/nginx/sites-available/archipelago`
+3. Create symlink: `/etc/nginx/sites-enabled/archipelago`
+4. Enable the service: `systemctl enable archipelago`
+5. Install backend to `/usr/local/bin/archipelago`
+6. Install frontend to `/opt/archipelago/web-ui/`
+
+## Critical Configuration Settings
+
+### Backend Service (archipelago.service)
+
+**Must-have settings**:
+```ini
+[Service]
+User=root                                    # Required for root Podman access
+Environment="ARCHIPELAGO_BIND=127.0.0.1:5678"  # Backend API port
+Environment="ARCHIPELAGO_DEV_MODE=true"       # Enable container auto-detection
+```
+
+**Why root?**: The backend must run as root to access containers started with `sudo podman`. Containers in root Podman context are invisible to rootless Podman.
+
+### Nginx Configuration (nginx-archipelago.conf)
+
+**Must-have proxies**:
+```nginx
+location /rpc/ {
+    proxy_pass http://127.0.0.1:5678;  # Backend RPC endpoint
+}
+
+location /ws {
+    proxy_pass http://127.0.0.1:5678;  # WebSocket for real-time updates
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+}
+```
+
+## File Paths Reference
+
+### Build Artifacts
+- `build/backend/archipelago` - Compiled Rust backend
+- `build/frontend/` - Built Vue.js frontend
+- `configs/` - System configuration files
+- `results/` - Built ISO images
+
+### Live Server Paths
+- `/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
+- `/var/lib/archipelago/` - Application data
+
+### ISO Installation Paths
+Same as live server (above) - the ISO must replicate the exact file structure.
+
+## Container Management
+
+### Root vs Rootless Podman
+
+**Current approach**: Root Podman
+- Containers started with: `sudo podman run ...`
+- Backend runs as: `root` user (in systemd)
+- Container detection: Works automatically in dev mode
+
+**Why not rootless?**
+- Would require `User=archipelago` in systemd service
+- All containers must be started as `archipelago` user
+- More complex permission management
+
+### Container Detection
+
+The backend automatically detects running containers when:
+1. `ARCHIPELAGO_DEV_MODE=true` is set
+2. Backend runs with same privileges as container runtime
+3. Containers exist in accessible Podman context
+
+## Troubleshooting
+
+### Issue: Containers not detected in ISO
+
+**Cause**: Backend not running as root, or dev mode disabled
+
+**Fix**: 
+1. Check `configs/archipelago.service` has `User=root`
+2. Check `Environment="ARCHIPELAGO_DEV_MODE=true"` is set
+3. Rebuild ISO and test
+
+### Issue: UI not loading
+
+**Cause**: Nginx config not copied or frontend files missing
+
+**Fix**:
+1. Verify `configs/nginx-archipelago.conf` exists
+2. Check frontend built to `build/frontend/`
+3. Verify ISO build script copies these files
+
+### Issue: Backend won't start
+
+**Cause**: Binary permissions or missing dependencies
+
+**Fix**:
+1. Check backend binary is executable: `chmod +x /usr/local/bin/archipelago`
+2. Check dependencies installed (Podman, nginx)
+3. Review systemd logs: `journalctl -u archipelago`
+
+## Testing Checklist
+
+Before releasing an ISO, verify:
+
+- [ ] Boot ISO in QEMU
+- [ ] Systemd service starts: `systemctl status archipelago`
+- [ ] Backend responds: `curl http://localhost:5678/health`
+- [ ] UI accessible: Open browser to `http://localhost`
+- [ ] Container detection: `sudo podman run -d --name test nginx` → Shows in UI
+- [ ] RPC works: Test login and API calls
+- [ ] WebSocket connects: Check browser console
+
+## Automated Build Pipeline (Future)
+
+To automate this workflow:
+
+1. **CI/CD Integration**
+   - Trigger on main branch commits
+   - Run `sync-from-live.sh` with credentials
+   - Build backend and frontend
+   - Build ISO
+   - Upload to releases
+
+2. **Version Management**
+   - Tag releases with semantic versions
+   - Include git commit hash in ISO metadata
+   - Track which configs were included
+
+3. **Testing Automation**
+   - Boot ISO in headless QEMU
+   - Run API tests
+   - Verify container detection
+   - Generate test report
+
+## Resources
+
+- Development Workflow Rules: `.cursor/rules/Development-Workflow.mdc`
+- Build Checklist: `ISO-BUILD-CHECKLIST.md`
+- Architecture Docs: `.cursor/rules/Architecture.mdc`
+- Deployment Scripts: `scripts/deploy-to-target.sh`