mirror of
https://github.com/nesquena/hermes-webui.git
synced 2026-05-19 13:47:04 +00:00
nesquena-hermes
b57525241b
Combines PR #1428 (UID/GID alignment) with a broader Docker reliability pass that addresses recurring user reports about compose files not working. Constituent PR: - #1428 sunnysktsang - Align agent UID/GID with webui (fixes #1399). Two- and three-container compose files had agent at UID 10000 (image default) and webui at UID 1000 (WANTED_UID default), causing permission denied on shared hermes-home volume. All services now use ${UID:-1000}. Plus broader Docker UX overhaul: - All 3 compose files document HERMES_SKIP_CHMOD/HERMES_HOME_MODE escape hatches inline (the v0.50.254 fix wasn't surfaced for Docker users). - New .env.docker.example template covering UID/GID, paths, password, permission handling. UID/GID are uncommented with placeholder values per Opus advisor (so macOS users don't skim past). - New docs/docker.md - comprehensive guide: 5-min quickstart, failure mode table with one-line fixes, bind-mount migration, multi-container architecture diagram, macOS Docker Desktop VirtioFS note, link to community sunnysktsang/hermes-suite all-in-one image. - README Docker section rewritten - clearer quickstart, failure-mode table, link to docs/docker.md. Stale /root/.hermes references removed. Plus Opus pre-release advisor MUST-FIX: - HERMES_HOME_MODE has DIFFERENT semantics in the WebUI vs the agent image. WebUI: credential-file mode threshold (0640 allows group bits). Agent: HERMES_HOME directory mode (default 0700). 0640 on a directory has no owner-execute bit, so the agent can't traverse its own home and bricks. My initial draft recommended HERMES_HOME_MODE=0640 in agent service blocks - corrected to 0750 across all 4 surfaces (compose files, .env.docker.example, docs/docker.md). 3 regression tests pin the asymmetry. 12 regression tests total in test_v050260_docker_invariants.py. Full suite: 3627 passed, 0 failed. Nathan explicitly authorized merge with my own review + Opus only, no independent review needed.
58 lines
2.8 KiB
YAML
58 lines
2.8 KiB
YAML
# Hermes WebUI — single-container Docker Compose
|
|
#
|
|
# QUICK START (most users):
|
|
# 1. (Optional) Copy .env.docker.example to .env and edit values
|
|
# 2. docker compose up -d
|
|
# 3. Open http://localhost:8787
|
|
#
|
|
# This is the simplest setup: one WebUI container that runs the agent in-process.
|
|
# The WebUI auto-detects host UID/GID from the mounted .hermes volume.
|
|
#
|
|
# For multi-container setups (separate agent + webui or agent+webui+dashboard),
|
|
# see docker-compose.two-container.yml or docker-compose.three-container.yml.
|
|
|
|
services:
|
|
hermes-webui:
|
|
build: .
|
|
ports:
|
|
# select only one; use 127.0.0.1 version to expose to localhost only
|
|
- "127.0.0.1:8787:8787"
|
|
# - "8787:8787"
|
|
volumes:
|
|
# Mount your Hermes home directory into the container.
|
|
# The default (${HOME}/.hermes) works on both macOS (/Users/<you>/.hermes)
|
|
# and Linux (/home/<you>/.hermes) — no change needed for standard installs.
|
|
# Only set HERMES_HOME explicitly if your .hermes lives somewhere non-standard.
|
|
# macOS note: set UID and GID below to match your user ID (run `id -u` and `id -g`).
|
|
- ${HERMES_HOME:-${HOME}/.hermes}:/home/hermeswebui/.hermes
|
|
# Your workspace directory shown on first launch (adapt if yours is different, the container will use the mounted /workspace)
|
|
- ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
|
|
environment:
|
|
# Set to your host user ID: run `id -u` and `id -g` to find them.
|
|
# On macOS, UIDs start at 501 (not 1000), so set UID and GID in a .env file:
|
|
# echo "UID=$(id -u)" >> .env
|
|
# echo "GID=$(id -g)" >> .env
|
|
# Without this, the container may not be able to read your mounted files.
|
|
- WANTED_UID=${UID:-1000}
|
|
- WANTED_GID=${GID:-1000}
|
|
# Required: bind address and port
|
|
- HERMES_WEBUI_HOST=0.0.0.0
|
|
- HERMES_WEBUI_PORT=8787
|
|
# Where to store sessions, workspaces, and other state (default: ~/.hermes/webui)
|
|
- HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui
|
|
# Default workspace directory shown on first launch
|
|
# - HERMES_WEBUI_DEFAULT_WORKSPACE=/workspace
|
|
# Optional: set a password for remote access
|
|
# - HERMES_WEBUI_PASSWORD=your-secret-password
|
|
#
|
|
# Bind-mount permission handling (fixes #1389, #1399):
|
|
# When you mount an EXISTING ~/.hermes directory (the common case),
|
|
# the WebUI's startup credential-permission fixer can clash with
|
|
# your host file modes (e.g. 0640 group-readable .env files).
|
|
# Set HERMES_SKIP_CHMOD=1 to bypass the fixer entirely, OR set
|
|
# HERMES_HOME_MODE=0640 to allow group bits while still stripping
|
|
# world-readable. Both are documented in api/startup.py.
|
|
# - HERMES_SKIP_CHMOD=1
|
|
# - HERMES_HOME_MODE=0640
|
|
restart: unless-stopped
|