# 🚀 Icarus Phase 2 — Deployment Instructions

**To:** Matt (Director) + Socrates 🧠  
**From:** Wadsworth 📋  
**Status:** Phase 1 Complete ✅ → Phase 2 Deployment

---

## Pre-Deployment Checklist

### Socrates — Verify These First

```bash
cd /home/hoffmann_admin/.openclaw/workspace/services/icarus

# 1. Source environment
source staging.env

# 2. Test import
python3 -c "from icarus.core.api import app; print('✅ Import OK')"

# 3. Test data directories exist
mkdir -p $DATA_DIR $CHROMA_DB_PATH $RADICALE_DATA_DIR

# 4. Local test (optional)
python3 -m uvicorn icarus.core.api:app --host 127.0.0.1 --port 8001 &
curl http://127.0.0.1:8001/health
kill %1  # Stop test server
```

**Expected:** `{"status": "ok", "env": "icarus-staging", ...}`

---

## Deployment Steps (Requires Sudo)

### Step 1: Create Systemd Service File

**Matt — Run:**

```bash
sudo tee /etc/systemd/system/icarus-staging.service << 'EOF'
[Unit]
Description=Icarus Staging API (Port 8001)
After=network.target

[Service]
Type=simple
User=hoffmann_admin
WorkingDirectory=/home/hoffmann_admin/.openclaw/workspace/services/icarus
Environment=ICARUS_ENV=staging
EnvironmentFile=/home/hoffmann_admin/.openclaw/workspace/services/icarus/staging.env
ExecStart=/home/hoffmann_admin/.local/bin/uvicorn icarus.core.api:app --host 0.0.0.0 --port 8001 --log-level info
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF
```

### Step 2: Reload Systemd + Enable Service

```bash
sudo systemctl daemon-reload
sudo systemctl enable icarus-staging.service
```

### Step 3: Start Service

```bash
sudo systemctl start icarus-staging.service
```

### Step 4: Verify Service Status

```bash
sudo systemctl status icarus-staging.service
sudo journalctl -u icarus-staging.service -f
```

**Expected:** `Active: active (running)`

---

## Post-Deployment Verification

### Test Cloudflare Routing

```bash
# From any machine (or phone)
curl -s https://icarus-test.hoffdesk.com/health | python3 -m json.tool
```

**Expected:**
```json
{
    "status": "ok",
    "env": "icarus-staging",
    "version": "0.0.1",
    "stage": "phase-2-ready"
}
```

### Verify Port Binding

```bash
# On Beelink
ss -tlnp | grep 8001
# Expected: 0.0.0.0:8001 (LISTEN)
```

### Verify No Port Conflicts

```bash
# Production on 8000 should still work
curl -s https://family.hoffdesk.com/ | head -5
curl -s https://notes.hoffdesk.com/api/blog/posts | head -5
```

---

## Troubleshooting

### Service Won't Start

```bash
# Check logs
sudo journalctl -u icarus-staging.service --no-pager -n 50

# Common issues:
# - ImportError: Run `source staging.env` in service file context
# - Port 8001 in use: `sudo lsof -i :8001` then `sudo kill <pid>`
# - Permission denied: Check file ownership of icarus/ directory
```

### 502 Bad Gateway from Cloudflare

```bash
# Check if service is actually running on port 8001
curl http://127.0.0.1:8001/health

# If that works but Cloudflare 502s:
# - Check cloudflared config: `cat ~/.cloudflared/config.yml`
# - Verify `icarus-test.hoffdesk.com` route is FIRST in ingress
# - Restart cloudflared: `sudo systemctl restart cloudflared`
```

### Import Errors in Logs

```bash
# If "No module named icarus":
# - Add PYTHONPATH to service file:
Environment=PYTHONPATH=/home/hoffmann_admin/.openclaw/workspace/services/icarus:$PYTHONPATH

# Then:
sudo systemctl daemon-reload
sudo systemctl restart icarus-staging.service
```

---

## Success Criteria

✅ Phase 2 Complete When:

| Check | Command | Expected |
|-------|---------|----------|
| Service running | `sudo systemctl status icarus-staging` | `active (running)` |
| Port bound | `ss -tlnp \| grep 8001` | `0.0.0.0:8001` |
| Local health | `curl http://127.0.0.1:8001/health` | JSON with `"status": "ok"` |
| Cloudflare health | `curl https://icarus-test.hoffdesk.com/health` | Same JSON |
| Production unaffected | `curl https://family.hoffdesk.com/` | Still returns dashboard |

---

## Post-Phase-2

Once ✅ all checks pass:

1. **Socrates** begins Phase 3: Vision pipeline, briefing cards
2. **Wadsworth** updates Master Roadmap to Phase 3 active
3. **Matt** tests end-to-end flow

---

**Execute deployment. Report status.**