From 7752fec2b6bda72215a06353de84125389c93bfd Mon Sep 17 00:00:00 2001 From: admin9webs Date: Fri, 10 Jul 2026 16:12:09 +0800 Subject: [PATCH] Add cross-border-ecommerce/hermes-web-ui-setup --- .../hermes-web-ui-setup/SKILL.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 skills/cross-border-ecommerce/hermes-web-ui-setup/SKILL.md diff --git a/skills/cross-border-ecommerce/hermes-web-ui-setup/SKILL.md b/skills/cross-border-ecommerce/hermes-web-ui-setup/SKILL.md new file mode 100644 index 0000000..10df072 --- /dev/null +++ b/skills/cross-border-ecommerce/hermes-web-ui-setup/SKILL.md @@ -0,0 +1,172 @@ +--- +name: hermes-web-ui-setup +description: Install and run both Hermes Web UI projects — nesquena/hermes-webui (chat interface) and joeynyc/hermes-hudui (monitoring dashboard) +version: 1.0 +--- + +# Hermes Web UI — Installation & Setup + +Two complementary Web UIs for the Hermes AI Agent, running on separate ports. + +## Environment + +- Server: Ubuntu Linux, Python 3.11+, Node.js 18+ +- Hermes data: `~/.hermes/` +- Both projects cloned to Gitea: `https://gitea9webs.sh3.ikuai7.com/admin9webs/` + +## Project 1: hermes-webui (Chat Interface) — Port 8787 + +**Repo:** `https://github.com/nesquena/hermes-webui` (★6250) +**Gitea:** `https://gitea9webs.sh3.ikuai7.com/admin9webs/hermes-webui` +**Tech:** Python backend + vanilla JS frontend, no build step + +### Install & Run + +```bash +cd /home/ubuntu/hermes-webui +cp .env.example .env +# Edit .env with host/port/password +python3 bootstrap.py --no-browser +``` + +### Key .env Settings + +```bash +HERMES_WEBUI_HOST=0.0.0.0 # Bind to all interfaces for remote access +HERMES_WEBUI_PORT=8787 +HERMES_HOME=/home/ubuntu/.hermes +HERMES_WEBUI_PASSWORD=xxx # REQUIRED if binding 0.0.0.0 — otherwise 401 warning +``` + +### ⚠️ Pitfalls + +- **No password on 0.0.0.0** = anyone can access your agent and filesystem. Always set `HERMES_WEBUI_PASSWORD`. +- **No build step** — bootstrap.py handles everything, just needs pyyaml. +- **Background launch**: Use `terminal(background=true)` + env vars inline, NOT `nohup &` (Hermes blocks shell backgrounding). +- Password auth returns 401 on `/api/sessions` without credentials — this confirms it's working. + +## Project 2: hermes-hudui (Monitoring Dashboard) — Port 3001 + +**Repo:** `https://github.com/joeynyc/hermes-hudui` (★1394) +**Gitea:** `https://gitea9webs.sh3.ikuai7.com/admin9webs/hermes-hudui` +**Tech:** FastAPI backend + React/Vite/Tailwind frontend, requires build step + +### Install (manual steps) + +```bash +cd /home/ubuntu/hermes-hudui + +# 1. Create venv & install backend +python3 -m venv venv +source venv/bin/activate +pip install -e . + +# 2. Build frontend +cd frontend +npm install +npm run build +cd .. + +# 3. Copy frontend build to static serving dir +mkdir -p backend/static/assets +cp frontend/dist/index.html backend/static/ +cp frontend/dist/assets/* backend/static/assets/ +``` + +### Run + +```bash +cd /home/ubuntu/hermes-hudui +source venv/bin/activate +HERMES_HOME=/home/ubuntu/.hermes hermes-hudui --port 3001 +``` + +### ⚠️ Pitfalls + +- **Must build frontend first** — without `npm run build` + copy to `backend/static/`, the dashboard serves nothing. +- **Vite build output filenames have hashes** (e.g., `index-CULqjDQ_.js`) — copy ALL files from `dist/assets/`, not just specific ones. +- **Old build files may linger** — `backend/static/assets/` may have stale JS from previous builds; clean before copying. +- **Health endpoint**: `/api/health` (not `/health`) returns full diagnostics JSON. +- **Minor DB issue**: `tool_calls` table may be missing — harmless, dashboard still works. +- **v0.9.0+ requires `cryptography`**: New Replay feature uses `backend.services.replay_signer` which imports `cryptography.exceptions.InvalidSignature`. If missing, startup crashes with `ModuleNotFoundError: No module named 'cryptography'`. Fix: `pip install cryptography` in the venv. Always check for new deps after `git pull`. +- **stash pop conflicts on `backend/static/index.html`**: This file has hash-based asset references that differ between builds. On merge conflict, always take the upstream version: `git checkout upstream/main -- backend/static/index.html`. + +## Running Both Simultaneously + +| Project | Port | Purpose | +|---------|------|---------| +| hermes-webui | 8787 | Chat with Hermes (browser-based CLI) | +| hermes-hudui | 3001 | Monitor Hermes (18-tab dashboard) | + +Use `terminal(background=true)` for each, with inline env vars. Kill existing processes on a port with `fuser -k PORT/tcp`. + +## Updating from GitHub Upstream + +When local code falls behind GitHub upstream: + +### hermes-webui +```bash +cd /home/ubuntu/hermes-webui +git pull origin master +# Then restart service (see below) +``` + +### hermes-hudui +Origin points to Gitea, so add GitHub as upstream: +```bash +cd /home/ubuntu/hermes-hudui +git remote add upstream https://github.com/joeynyc/hermes-hudui.git 2>/dev/null +git fetch upstream main +# Stash local changes first if any +git stash +git merge upstream/main +git stash pop # May conflict on backend/static/index.html — use upstream version +git checkout upstream/main -- backend/static/index.html # If conflict +git add backend/static/index.html +``` + +### ⚠️ After updating, always reinstall dependencies +New versions may add Python dependencies. Check if the service starts cleanly: +```bash +# hudui example: v0.9.0 added 'cryptography' — install in venv +cd /home/ubuntu/hermes-hudui && source venv/bin/activate && pip install cryptography +``` + +## Restarting Services + +Both run as background processes. Kill old ones first, then relaunch: + +```bash +# Find and kill old processes +ps aux | grep -E "hermes.*(webui|hudui)" | grep -v grep +kill + +# Restart webui +# terminal(background=true): +cd /home/ubuntu/hermes-webui && source .env 2>/dev/null; export HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PORT=8787 HERMES_HOME=/home/ubuntu/.hermes HERMES_WEBUI_PASSWORD='xxx'; python3 bootstrap.py --no-browser + +# Restart hudui +# terminal(background=true): +cd /home/ubuntu/hermes-hudui && source venv/bin/activate && HERMES_HOME=/home/ubuntu/.hermes hermes-hudui --port 3001 +``` + +Verify after restart: +```bash +curl -sk -o /dev/null -w "%{http_code}" http://127.0.0.1:8787/ # Expect 302 (redirect to login) +curl -sk -o /dev/null -w "%{http_code}" http://127.0.0.1:3001/ # Expect 200 +``` + +## Gitea Mirror Push + +Push to Gitea with auth in URL (credential-less push fails): +```bash +git push https://admin9webs:Tt123456!@gitea9webs.sh3.ikuai7.com/admin9webs/hermes-webui.git master +git push https://admin9webs:Tt123456!@gitea9webs.sh3.ikuai7.com/admin9webs/hermes-hudui.git main +``` + +For large repos, increase http buffer: +```bash +git config http.postBuffer 524288000 +``` + +The `hermes-web-ui` repo (empty, labeled "EKKOLearnAI") was deleted via `DELETE /api/v1/repos/admin9webs/hermes-web-ui`.