Add cross-border-ecommerce/hermes-web-ui-setup
This commit is contained in:
@@ -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 <PIDs>
|
||||||
|
|
||||||
|
# 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`.
|
||||||
Reference in New Issue
Block a user