docs: add MIGRATION-PLAYBOOK.md for manual cutover steps
Manual sequence Marius runs AFTER the PR merges. Pre-flight (tests, backups), stop-services, ANAF live-state copy, dashboard migration, memory inversion (clawd/memory -> echo-core/memory), systemd, crontab, OpenClaw decommission, verification, and rollback path. Flagged at the top as human-only -- no AI agent should auto-execute these steps.
This commit is contained in:
163
MIGRATION-PLAYBOOK.md
Normal file
163
MIGRATION-PLAYBOOK.md
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
# OpenClaw → Echo-Core Migration Playbook
|
||||||
|
|
||||||
|
> **⚠️ This document should NOT be run by an AI agent.**
|
||||||
|
> Marius runs it by hand, one step at a time, verifying between steps.
|
||||||
|
> Each step has a "before" and "after" state. Never batch.
|
||||||
|
|
||||||
|
Run this after the PR `feat/openclaw-consolidation-2026-04` has merged to master.
|
||||||
|
Estimated downtime: 5–10 minutes. Rollback path at the bottom.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pre-flight (read-only)
|
||||||
|
|
||||||
|
1. Confirm clean git state on echo-core master:
|
||||||
|
```
|
||||||
|
cd /home/moltbot/echo-core && git status
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Verify tests pass:
|
||||||
|
```
|
||||||
|
cd /home/moltbot/echo-core
|
||||||
|
source .venv/bin/activate && pytest tests/ -x
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Backup:
|
||||||
|
```
|
||||||
|
cp -rp /home/moltbot/clawd/dashboard /home/moltbot/clawd-backup-$(date +%Y-%m-%d)/
|
||||||
|
cp -rp /home/moltbot/clawd/memory /home/moltbot/clawd-backup-$(date +%Y-%m-%d)/memory
|
||||||
|
```
|
||||||
|
|
||||||
|
## Legacy consumer grep (decide on compat symlink)
|
||||||
|
|
||||||
|
4. Check whether anything still reads clawd/memory:
|
||||||
|
```
|
||||||
|
grep -rn 'clawd/memory' /home/moltbot/{bin,.config,.openclaw} 2>/dev/null
|
||||||
|
grep -rn 'clawd/memory' /home/moltbot/echo-core 2>/dev/null
|
||||||
|
```
|
||||||
|
- If empty → skip **step 11** (no compat symlink needed).
|
||||||
|
- If non-empty → keep **step 11**.
|
||||||
|
|
||||||
|
## Stop services
|
||||||
|
|
||||||
|
5. ```
|
||||||
|
systemctl --user stop echo-core echo-taskboard echo-whatsapp-bridge openclaw-gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
## Copy ANAF live state
|
||||||
|
|
||||||
|
6. ```
|
||||||
|
cp -rp /home/moltbot/clawd/tools/anaf-monitor/{hashes.json,versions.json,monitor.log} \
|
||||||
|
/home/moltbot/echo-core/tools/anaf-monitor/ 2>/dev/null
|
||||||
|
cp -rp /home/moltbot/clawd/tools/anaf-monitor/snapshots \
|
||||||
|
/home/moltbot/echo-core/tools/anaf-monitor/
|
||||||
|
diff -r /home/moltbot/clawd/tools/anaf-monitor/snapshots \
|
||||||
|
/home/moltbot/echo-core/tools/anaf-monitor/snapshots
|
||||||
|
```
|
||||||
|
Diff should be empty (or only show new snapshots echo-core captured during testing).
|
||||||
|
|
||||||
|
## Dashboard migration
|
||||||
|
|
||||||
|
7. Delete echo-core dashboard placeholder content if any collisions, then:
|
||||||
|
```
|
||||||
|
cp -rp /home/moltbot/clawd/dashboard/{habits,issues,status,todos}.json \
|
||||||
|
/home/moltbot/echo-core/dashboard/
|
||||||
|
cp -rp /home/moltbot/clawd/dashboard/tests/ \
|
||||||
|
/home/moltbot/echo-core/dashboard/tests/
|
||||||
|
# Recreate the 4 dashboard symlinks pointing into echo-core:
|
||||||
|
ln -sfn /home/moltbot/echo-core/memory /home/moltbot/echo-core/dashboard/memory
|
||||||
|
ln -sfn /home/moltbot/echo-core/conversations /home/moltbot/echo-core/dashboard/conversations # create conversations/ first if you want this
|
||||||
|
ln -sfn /home/moltbot/echo-core/memory/kb /home/moltbot/echo-core/dashboard/notes-data
|
||||||
|
ln -sfn /home/moltbot/echo-core/memory/kb/youtube /home/moltbot/echo-core/dashboard/youtube-notes
|
||||||
|
```
|
||||||
|
|
||||||
|
## Memory inversion
|
||||||
|
|
||||||
|
8. `rm /home/moltbot/echo-core/memory` *(removes symlink only, not target)*
|
||||||
|
9. `cp -rp /home/moltbot/clawd/memory /home/moltbot/echo-core/memory`
|
||||||
|
10. `diff -rq /home/moltbot/clawd/memory /home/moltbot/echo-core/memory` *(verify identical)*
|
||||||
|
11. *(only if step 4 found consumers)*
|
||||||
|
```
|
||||||
|
mv /home/moltbot/clawd/memory /home/moltbot/clawd/memory.old-2026-04
|
||||||
|
ln -s /home/moltbot/echo-core/memory /home/moltbot/clawd/memory
|
||||||
|
```
|
||||||
|
12. `rm -rf /home/moltbot/echo-core/memory.bak` *(leftover, safe to delete)*
|
||||||
|
|
||||||
|
## Systemd
|
||||||
|
|
||||||
|
13. Copy the template into place:
|
||||||
|
```
|
||||||
|
cp /home/moltbot/echo-core/dashboard/echo-taskboard.service \
|
||||||
|
/home/moltbot/.config/systemd/user/echo-taskboard.service
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
```
|
||||||
|
|
||||||
|
## Crontab
|
||||||
|
|
||||||
|
14. ```
|
||||||
|
bash /home/moltbot/echo-core/scripts/update_crontab.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## Decommission OpenClaw
|
||||||
|
|
||||||
|
15. `systemctl --user stop openclaw-gateway`
|
||||||
|
16. `systemctl --user disable openclaw-gateway`
|
||||||
|
17. Strip credentials from `~/.openclaw/` but keep `jobs.json.bak`:
|
||||||
|
```
|
||||||
|
cd /home/moltbot/.openclaw
|
||||||
|
find . -name 'auth*' -o -name '*token*' -o -name '*.secret' | xargs rm -v 2>/dev/null
|
||||||
|
ls -la agents/*/ # inspect for any remaining secrets, delete manually
|
||||||
|
```
|
||||||
|
18. **Note:** schedule a reminder for 2026-05-21 to `rm -rf /home/moltbot/.openclaw`
|
||||||
|
entirely if nothing was restored.
|
||||||
|
|
||||||
|
## Restart
|
||||||
|
|
||||||
|
19. `systemctl --user start echo-core echo-taskboard echo-whatsapp-bridge`
|
||||||
|
20. `systemctl --user status echo-core echo-taskboard echo-whatsapp-bridge` — all **active (running)**.
|
||||||
|
21. `systemctl --user status openclaw-gateway` — **inactive (dead)**.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
22. `curl -s http://localhost:8088/api/status` → `{"status":"ok",...}`
|
||||||
|
23. Visit `https://moltbot.tailf7372d.ts.net/echo/` — home page loads.
|
||||||
|
24. `/api/cron` panel populated with echo-core jobs (anaf-monitor, morning-report, etc).
|
||||||
|
25. `/api/agents` returns 404 (removed).
|
||||||
|
26. Click **Commit** in `index.html` — creates commit on echo-core repo.
|
||||||
|
27. Manually trigger anaf monitor:
|
||||||
|
```
|
||||||
|
cd /home/moltbot/echo-core && .venv/bin/python3 tools/anaf-monitor/monitor_v2.py
|
||||||
|
```
|
||||||
|
Verify `status.json` updates **and** stdout ends with
|
||||||
|
`GSTACK-CRON: changes=N`.
|
||||||
|
28. Wait for first scheduled anaf-monitor trigger (10:00 or 16:00 Mon-Fri).
|
||||||
|
Check `echo-core.log` for execution.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rollback path (if anything breaks badly)
|
||||||
|
|
||||||
|
```
|
||||||
|
systemctl --user stop echo-core echo-taskboard echo-whatsapp-bridge
|
||||||
|
rm -rf /home/moltbot/echo-core/memory
|
||||||
|
cp -rp /home/moltbot/clawd-backup-YYYY-MM-DD/memory /home/moltbot/clawd/memory # restore
|
||||||
|
ln -s /home/moltbot/clawd/memory /home/moltbot/echo-core/memory # restore symlink
|
||||||
|
|
||||||
|
# Restore old systemd unit from git history in clawd repo if available, else rewrite manually.
|
||||||
|
git -C /home/moltbot/echo-core checkout master # revert to pre-merge state
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
systemctl --user start echo-core echo-taskboard echo-whatsapp-bridge
|
||||||
|
systemctl --user start openclaw-gateway # if wanted
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- **Cron schedules are Bucharest local time**, not UTC.
|
||||||
|
- **Most imported claude jobs arrive DISABLED** — enable them via `eco` / dashboard
|
||||||
|
once you've verified each one produces the expected output.
|
||||||
|
- `heartbeat-2h` is the **only imported claude job that stays enabled** (preserving
|
||||||
|
its state from OpenClaw).
|
||||||
|
- The 5 shell jobs (anaf-monitor, security-audit-daily, kb-index-refresh,
|
||||||
|
archive-tasks-daily, backup-config) start **enabled** on day one.
|
||||||
Reference in New Issue
Block a user