archy/FULL_STACK_DOCKER_COMPLETE.md

# ✅ FULL STACK DOCKER INTEGRATION COMPLETE

## Summary

The **full stack** (Rust backend + Vue.js frontend) now displays real Docker containers in the "My Apps" section. Both mode 1 (mock backend) and mode 2 (full stack) are fully functional.

## What's Working

### Mode 2: Full Stack (Rust Backend)
```bash
./scripts/dev-start.sh
# Choose option 2
```

**Backend Features:**
- ✅ Connects to Docker API on startup
- ✅ Scans running containers every 5 seconds
- ✅ Maps `archy-*` containers to app IDs
- ✅ Extracts ports automatically
- ✅ Broadcasts updates via WebSocket
- ✅ Works on macOS (fixed hardcoded `/home` paths)

**Console Output:**
```
🚀 Starting Archipelago Bitcoin Node OS
📁 Data directory: /tmp/archipelago-dev
🐳 Scanning Docker containers...
Found 1 containers
Detected container: Bitcoin Core (running)
Data model updated to revision 1
```

### Mode 1: Mock Backend (Node.js)
```bash
cd neode-ui
npm run dev:mock
```

Also has Docker integration via `dockerode`.

## Files Modified

### Rust Backend

1. **`core/archipelago/src/container/docker_packages.rs`** (NEW)
   - Scans Docker containers
   - Maps container names to app IDs
   - Extracts ports and builds package data
   - Includes metadata for all 13 apps

2. **`core/archipelago/src/server.rs`**
   - Initializes Docker scanner on startup
   - Spawns background task to scan every 5 seconds
   - Updates state manager with package data

3. **`core/container/src/runtime.rs`**
   - Fixed hardcoded `/home/` paths → uses `$HOME` env var
   - Fixed Docker `list_containers()` to parse NDJSON format
   - Now extracts ports from container JSON

4. **`core/container/src/podman_client.rs`**
   - Fixed hardcoded `/home/` paths for macOS compatibility

5. **`scripts/dev-start.sh`**
   - Added `ARCHIPELAGO_CONTAINER_RUNTIME=docker` env var

### Mock Backend

6. **`neode-ui/mock-backend.js`**
   - Added `dockerode` integration
   - Queries Docker API every 5 seconds
   - Maps containers to package data

### Frontend

7. **`neode-ui/src/views/Apps.vue`**
   - Removed all dummy app logic
   - Now uses only real packages from store

## Testing

### Start Bitcoin Core
```bash
cd /Users/dorian/Projects/archy
docker ps | grep archy-bitcoin
# Should show: archy-bitcoin   Up X minutes
```

### Check Backend Logs
```bash
tail -f /tmp/archipelago-backend.log
```

**Expected:**
```
Detected container: Bitcoin Core (running)
```

### Check Frontend
1. Open http://localhost:8100
2. Navigate to "My Apps"
3. See Bitcoin Core with green "running" badge
4. Click Launch → opens http://localhost:18443

## App Container Mapping

The backend recognizes these containers:

| Container Name | App ID | Port |
|---|---|---|
| `archy-bitcoin` | bitcoin | 18443 |
| `archy-btcpay` | btcpay-server | 23000 |
| `archy-homeassistant` | homeassistant | 8123 |
| `archy-grafana` | grafana | 3000 |
| `archy-endurain` | endurain | 8084 |
| `archy-fedimint` | fedimint | 8174 |
| `archy-morphos` | morphos-server | 8085 |
| `archy-lnd` | lightning-stack | 8080 |
| `archy-mempool-web` | mempool | 8083 |
| `archy-ollama` | ollama | 11434 |
| `archy-searxng` | searxng | 8082 |
| `archy-onlyoffice` | onlyoffice | 8081 |
| `archy-penpot-frontend` | penpot | 9001 |

## Start More Apps

```bash
# Start all apps defined in docker-compose.yml
docker compose up -d

# Or start specific apps
docker compose up -d grafana homeassistant mempool
```

Apps appear in "My Apps" within 5 seconds.

## Architecture

```
┌─────────────────────────────────────────┐
│ Vue.js Frontend (localhost:8100)        │
│ - Displays apps from WebSocket data     │
│ - Launch buttons use lan-address        │
└─────────────┬───────────────────────────┘
              │ HTTP + WebSocket
┌─────────────▼───────────────────────────┐
│ Rust Backend (localhost:5959)           │
│ - RPC API                                │
│ - WebSocket broadcasts                   │
│ - Docker scanner (every 5s)              │
└─────────────┬───────────────────────────┘
              │ Docker API
┌─────────────▼───────────────────────────┐
│ Docker Engine                            │
│ - archy-bitcoin                          │
│ - archy-grafana                          │
│ - archy-* (all apps)                     │
└──────────────────────────────────────────┘
```

## Key Fixes Applied

### 1. macOS Path Issue
**Problem:** Hardcoded `/home/{user}` in Docker/Podman clients  
**Solution:** Use `std::env::var("HOME")` instead

### 2. Docker JSON Parsing
**Problem:** Expected JSON array, got NDJSON (newline-delimited)  
**Solution:** Parse line-by-line with `json.lines()`

### 3. Port Extraction
**Problem:** Ports not being extracted from Docker output  
**Solution:** Parse `Ports` field from JSON and split by `, `

### 4. Dummy App Removal
**Problem:** Frontend showing fake data  
**Solution:** Removed all dummy logic from `Apps.vue`

## Current Status

✅ **Full Stack Mode (Mode 2)**: Working perfectly  
✅ **Mock Backend Mode (Mode 1)**: Working perfectly  
✅ **Docker Integration**: Complete for both modes  
✅ **Live Updates**: 5-second polling active  
✅ **Port Mapping**: Extracted and displayed  
✅ **Launch Functionality**: Working with correct URLs  

## Next Steps

To see more apps in "My Apps":
```bash
docker compose up -d
```

All containers will automatically appear in the UI!

---

**Test Command:**
```bash
./scripts/dev-start.sh
# Choose 2 (Full stack)
# Open http://localhost:8100
# Navigate to "My Apps"
# See Bitcoin Core running!
```