From 8ad0723b00dcbe585355457b88eac33a0b043cfc Mon Sep 17 00:00:00 2001 From: ekko Date: Mon, 20 Apr 2026 19:55:31 +0800 Subject: [PATCH 1/3] docs: update Docker deployment guide and compose config - Update docker-compose.yml: use hermes-agent internal hostname for UPSTREAM, expose ports 8642-8670, add server data volume mapping - Rewrite docs/docker.md with pre-built image usage, env var table, data persistence (token location), port mapping, and common operations - Update README.md and README_zh.md Docker section with pre-built image instructions and token location Co-Authored-By: Claude Opus 4.6 --- README.md | 17 ++++------ README_zh.md | 17 ++++------ docker-compose.yml | 6 ++-- docs/docker.md | 80 +++++++++++++++++++++++++++++++++++----------- 4 files changed, 80 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 1879d796..c38891a0 100644 --- a/README.md +++ b/README.md @@ -162,25 +162,22 @@ hermes-web-ui start Run Web UI together with Hermes Agent: ```bash +# Use pre-built image (Recommended) +WEBUI_IMAGE=ekkoye8888/hermes-web-ui:latest docker compose up -d hermes-agent hermes-webui + +# Or build from source docker compose up -d --build hermes-agent hermes-webui + docker compose logs -f hermes-webui ``` Open **http://localhost:6060** - Persistent Hermes data is stored in `./hermes_data` -- The web UI service is built from this repository's `Dockerfile` +- Web UI auth token is stored in `./hermes_data/hermes-web-ui-data/.token` +- On first run with auth enabled, the token is printed to container logs - All runtime settings are environment-variable driven in `docker-compose.yml` -Override compose variables directly from command line (no `.env` file required): - -```bash -PORT=16060 \ -UPSTREAM=http://127.0.0.1:8642 \ -HERMES_BIN=/opt/hermes/.venv/bin/hermes \ -docker compose up -d --build hermes-agent hermes-webui -``` - For detailed notes and troubleshooting, see [`docs/docker.md`](./docs/docker.md). ### CLI Commands diff --git a/README_zh.md b/README_zh.md index 60796a6e..4b4af860 100644 --- a/README_zh.md +++ b/README_zh.md @@ -163,25 +163,22 @@ hermes-web-ui start 使用仓库内置的 compose 文件联合运行 Hermes Agent + Web UI： ```bash +# 使用预构建镜像（推荐） +WEBUI_IMAGE=ekkoye8888/hermes-web-ui:latest docker compose up -d hermes-agent hermes-webui + +# 或从源码构建 docker compose up -d --build hermes-agent hermes-webui + docker compose logs -f hermes-webui ``` 打开 **http://localhost:6060** - Hermes 持久化数据目录：`./hermes_data` -- Web UI 服务镜像由本仓库 `Dockerfile` 本地构建 +- Web UI 认证 Token 存储在 `./hermes_data/hermes-web-ui-data/.token` +- 首次启动并开启认证时，Token 会打印到容器日志中 - 运行参数全部由 `docker-compose.yml` 环境变量驱动 -可直接在命令行覆盖 compose 变量（不依赖 `.env` 文件）： - -```bash -PORT=16060 \ -UPSTREAM=http://127.0.0.1:8642 \ -HERMES_BIN=/opt/hermes/.venv/bin/hermes \ -docker compose up -d --build hermes-agent hermes-webui -``` - 更详细的说明与排错见：[`docs/docker.md`](./docs/docker.md) ### CLI 命令 diff --git a/docker-compose.yml b/docker-compose.yml index 02eb09e4..36d22e4d 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -10,6 +10,8 @@ services: stdin_open: true tty: true restart: unless-stopped + ports: + - "8642-8670:8642-8670" hermes-webui: build: @@ -30,10 +32,10 @@ services: - hermes-agent-src:/opt/hermes environment: - PORT=${PORT:-6060} - - UPSTREAM=${UPSTREAM:-http://127.0.0.1:8642} + - UPSTREAM=${UPSTREAM:-http://hermes-agent:8642} - HERMES_HOME=/home/agent/.hermes - HERMES_BIN=${HERMES_BIN:-/opt/hermes/.venv/bin/hermes} - - AUTH_DISABLED=${AUTH_DISABLED:-true} + - AUTH_DISABLED=${AUTH_DISABLED:-false} restart: unless-stopped volumes: diff --git a/docs/docker.md b/docs/docker.md index e0dfbd9f..ab327ca6 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -4,48 +4,84 @@ This repository ships an environment-variable driven Docker Compose setup. ## Quick Start +### Pull pre-built image (Recommended) + ```bash -docker compose up -d --build hermes-agent hermes-webui +WEBUI_IMAGE=ekkoye8888/hermes-web-ui:latest docker compose up -d hermes-agent hermes-webui docker compose logs -f hermes-webui ``` Open: `http://localhost:6060` +### Build from source + +```bash +docker compose up -d --build hermes-agent hermes-webui +docker compose logs -f hermes-webui +``` + +## Services + +This compose file runs two services: + +- `hermes-agent` — Hermes Agent runtime (image: `nousresearch/hermes-agent`) +- `hermes-webui` — Web UI dashboard (pre-built image or built from source) + ## Environment Variables All key runtime settings are configured from compose variables. -This compose file runs two services together: -- `hermes-agent` (image: `nousresearch/hermes-agent`) -- `hermes-webui` (built from this repository) +| Variable | Default | Description | +|---|---|---| +| `PORT` | `6060` | Web UI listen port | +| `UPSTREAM` | `http://hermes-agent:8642` | Hermes gateway URL (container internal) | +| `HERMES_BIN` | `/opt/hermes/.venv/bin/hermes` | Path to Hermes CLI binary | +| `HERMES_AGENT_IMAGE` | `nousresearch/hermes-agent:latest` | Hermes Agent base image | +| `WEBUI_IMAGE` | `hermes-web-ui-local:latest` | Web UI image (set to `ekkoye8888/hermes-web-ui:latest` to use pre-built) | +| `HERMES_DATA_DIR` | `./hermes_data` | Hermes runtime data directory | +| `AUTH_DISABLED` | `false` | Set to `true` to disable login authentication | -Compose mapping highlights: - -- Host/browser port: `${PORT}:${PORT}` -- Server `PORT` is set from `${PORT}` -- Upstream is set from `${UPSTREAM}` -- Hermes CLI binary is set from `${HERMES_BIN}` -- Hermes base image is set from `${HERMES_AGENT_IMAGE}` (used by both `hermes-agent` and webui build base) - -Override variables directly from shell when running compose: +Override variables directly from shell: ```bash PORT=16060 \ -UPSTREAM=http://127.0.0.1:8642 \ -HERMES_BIN=/opt/hermes/.venv/bin/hermes \ -docker compose up -d --build hermes-agent hermes-webui +AUTH_DISABLED=true \ +docker compose up -d hermes-agent hermes-webui +``` + +Or create a `.env` file in the project root: + +``` +WEBUI_IMAGE=ekkoye8888/hermes-web-ui:latest +PORT=6060 +AUTH_DISABLED=false ``` ## Data Persistence -- Hermes runtime data persists in `${HERMES_DATA_DIR}`. -- Default path is `./hermes_data`. +| Path | Description | +|---|---| +| `${HERMES_DATA_DIR}` (`./hermes_data`) | Hermes runtime data (sessions, config, profiles) | +| `${HERMES_DATA_DIR}/hermes-web-ui-data` | Web UI data (auth token) | + +- Hermes data persists in `./hermes_data`, mapped to `/home/agent/.hermes` in the container. +- Web UI auth token persists in `./hermes_data/hermes-web-ui-data/.token`. +- When `AUTH_DISABLED=false`, the token is auto-generated on first run and printed to container logs. +- Deleting the token file and restarting will generate a new one. + +## Port Mapping + +| Port | Service | Description | +|---|---|---| +| `${PORT}` (6060) | hermes-webui | Web UI dashboard | +| 8642-8670 | hermes-agent | Hermes Agent gateway ports (for multi-profile) | ## Code Runtime Behavior - Server upstream comes from `UPSTREAM` env (`packages/server/src/config.ts`). - Hermes CLI binary comes from `HERMES_BIN` env (`packages/server/src/services/hermes-cli.ts`). - If `HERMES_BIN` is not provided, code falls back to `hermes` in `PATH`. +- Profile switching dynamically resolves upstream URLs via `GatewayManager` — the `UPSTREAM` env only sets the default profile gateway. ## Common Operations @@ -55,6 +91,14 @@ Recreate webui: docker compose up -d --no-deps --force-recreate hermes-webui ``` +View auth token: + +```bash +docker compose logs hermes-webui | grep token +# or +cat ./hermes_data/hermes-web-ui-data/.token +``` + Stop: ```bash From 521a9edb86bdf200e5b43d2fb562e5289ca5a271 Mon Sep 17 00:00:00 2001 From: ekko Date: Mon, 20 Apr 2026 20:05:50 +0800 Subject: [PATCH 2/3] ci: add PR build check workflow and PR template - Add build.yml workflow that runs npm run build on PRs to main/dev - Add PR template with summary, type, changes, test plan sections - Required by branch protection rules on main Co-Authored-By: Claude Opus 4.6 --- .github/PULL_REQUEST_TEMPLATE.md | 31 +++++++++++++++++++++++++++++++ .github/workflows/build.yml | 26 ++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/build.yml diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..3c667f4a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,31 @@ +## Summary + + + +## Type of Change + +- [ ] Feature (new functionality) +- [ ] Bug fix +- [ ] Refactor (no functional change) +- [ ] Docs +- [ ] CI/CD +- [ ] Other + +## Changes + + + +## Test Plan + + + +- [ ] Build passes (`npm run build`) +- [ ] Tested manually + +## Screenshots (if applicable) + + + +## Related Issues + + diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 00000000..704a2d0b --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,26 @@ +name: Build + +on: + pull_request: + branches: + - main + - dev + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Install dependencies + run: npm install + + - name: Build + run: npm run build From 89e386593c714c0e966bccbd06bf678e42a77422 Mon Sep 17 00:00:00 2001 From: ekko Date: Mon, 20 Apr 2026 20:11:17 +0800 Subject: [PATCH 3/3] ci: update Node.js version to 23 in build workflow Co-Authored-By: Claude Opus 4.6 --- .github/workflows/build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 704a2d0b..6ebd2f7e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,7 +17,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: 22 + node-version: 23 - name: Install dependencies run: npm install