archy/BITCOIN_CORE_HEADLESS_FIX.md

# Bitcoin Core Launch Fix + Quiet Docker Downloads

## Issues Fixed

### 1. Bitcoin Core "Launch" Confusion
**Problem**: Bitcoin Core is a **headless node** with no web interface. It only exposes an RPC API on port 18443.

**Solution**: Changed the launch button to show connection details instead of trying to open a non-existent web UI.

### 2. Noisy Docker Downloads
**Problem**: First-run Docker image downloads were extremely verbose, showing detailed progress for each of 13+ images.

**Solution**: Made downloads quiet with a simple spinner. Users can still monitor progress in Docker Desktop if needed.

### 3. Backend WebSocket Disconnects
**Not actually a problem**: The logs show the backend is working fine. WebSocket disconnects happen naturally when you refresh the page. The backend reconnects automatically.

## What Changed

### `/Users/dorian/Projects/archy/neode-ui/src/views/Apps.vue`
**Before**: Tried to open `/bitcoin-core.html` in a new tab
**After**: Shows an alert with RPC connection details:
```
✅ Bitcoin Core is running!

🔗 RPC Endpoint: http://localhost:18443
👤 User: bitcoin
🔑 Password: bitcoinpass

💡 Use bitcoin-cli or an RPC client to interact.
📊 View blockchain data in Mempool: http://localhost:4080
```

### `/Users/dorian/Projects/archy/start-docker-apps.sh`
**Before**: Verbose output showing every image download
**After**: Quiet mode with spinner:
```
📦 Pulling Docker images (this will take a while)...
   💡 Tip: You can monitor progress in Docker Desktop

   Downloading images... ✅

✅ All images downloaded!
```

### Deleted: `/Users/dorian/Projects/archy/neode-ui/public/bitcoin-core.html`
Removed because Bitcoin Core doesn't have a web UI.

## How Bitcoin Core Works Now

1. **Status**: Shows "Running" in My Apps
2. **Start/Stop**: Works via the action buttons
3. **Launch**: Shows connection info popup (can't launch a headless node)
4. **Access**: Use bitcoin-cli or connect via RPC at `localhost:18443`
5. **Blockchain Explorer**: Use Mempool at `http://localhost:4080` (once you start it)

## RPC Usage Examples

### Using bitcoin-cli (from within container)
```bash
docker exec -it archy-bitcoin bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass getblockchaininfo
```

### Using curl (from host)
```bash
curl -u bitcoin:bitcoinpass \
  -X POST http://localhost:18443 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"test","method":"getblockchaininfo","params":[]}'
```

### Using a GUI wallet/tool
Configure any Bitcoin wallet or tool to connect to:
- **Host**: localhost
- **Port**: 18443
- **Network**: regtest
- **RPC User**: bitcoin
- **RPC Password**: bitcoinpass

## About Regtest Mode

Bitcoin Core is running in **regtest** (regression test) mode:
- ✅ No blockchain sync required (instant start)
- ✅ Full Bitcoin functionality
- ✅ Create blocks on demand
- ✅ Perfect for development/testing
- ❌ Not connected to mainnet/testnet

### Generate test blocks
```bash
docker exec -it archy-bitcoin bitcoin-cli -regtest -rpcuser=bitcoin -rpcpassword=bitcoinpass generatetoaddress 101 <your-address>
```

## Understanding "Headless" Apps

Some apps in Archipelago don't have web UIs:

| App | Type | Access |
|-----|------|--------|
| Bitcoin Core | Headless | RPC only (port 18443) |
| LND | Headless + API | gRPC/REST API (port 8080) |
| BTCPay Server | Web UI | http://localhost:14142 ✅ |
| Mempool | Web UI | http://localhost:4080 ✅ |
| Home Assistant | Web UI | http://localhost:8123 ✅ |
| Grafana | Web UI | http://localhost:3000 ✅ |

For headless apps, the "Launch" button will show connection info instead of opening a browser.

## Backend Status (It's Fine!)

The WebSocket errors you saw are **normal behavior**:
1. ✅ Backend is running on port 5959
2. ✅ Scanning Docker containers every 5 seconds
3. ✅ Detecting Bitcoin Core correctly
4. ✅ WebSocket reconnects after page refresh

The log shows:
```
[INFO] Detected container: Bitcoin Core (running)
[DEBUG] Data model updated to revision 25
[INFO] WebSocket /ws/db connected
```

Everything is working as expected!

## Next Steps

### To Start Mempool Explorer (for Bitcoin blockchain viewing)
```bash
docker compose up -d mempool-web mempool-api
```

### To Start Other Apps
```bash
docker compose up -d btcpay     # BTCPay Server
docker compose up -d lnd        # Lightning Network
docker compose up -d grafana    # Metrics dashboard
docker compose up -d homeassistant  # Home automation
```

### To See All Running Apps
```bash
docker compose ps
```

### To Stop Everything
```bash
./stop-docker-apps.sh
# or
docker compose down
```

## Architecture Clarification

```
User clicks "Launch" on Bitcoin Core
    ↓
Apps.vue checks app ID
    ↓
if (id === 'bitcoin')
    ↓
Show alert with RPC connection details
    ↓
User can use bitcoin-cli, curl, or GUI wallet to connect
```

For apps with web UIs (BTCPay, Mempool, Grafana):
```
User clicks "Launch"
    ↓
Apps.vue gets lanAddress from package
    ↓
window.open(lanAddress, '_blank')
    ↓
Opens app in new browser tab ✅
```

## Summary

- ✅ Bitcoin Core launch now shows connection info (not broken HTML page)
- ✅ Docker downloads are now quiet with spinner
- ✅ Backend is working perfectly (WebSocket disconnects are normal)
- ✅ Bitcoin Core is a headless node - this is correct behavior
- ✅ Use Mempool or bitcoin-cli to interact with the blockchain