archy/image-recipe/INTEGRATION-GUIDE.md

# 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=0.0.0.0: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`