---
description: Development workflow and deployment practices for Archipelago
alwaysApply: true
---

# Archipelago Development Workflow

## Deployment Strategy

**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.

### Standard Deployment Command

```bash
./scripts/deploy-to-target.sh --live
```

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)

### Target Environment

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

## SSH Key Management

The deployment scripts require SSH key authentication. If you encounter `Permission denied` errors:

1. Ensure SSH key is loaded: `ssh-add -l`
2. Add key if needed: `ssh-add ~/.ssh/id_ed25519`
3. Enter passphrase when prompted

## Development Paths

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