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

# 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.):

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

# 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:

[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:

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