v0.50.260 — Docker reliability overhaul

A coordinated pass on Docker UX after recurring user reports about compose files not working. 1 PR + broader docs/config improvements + 1 Opus pre-release advisor MUST-FIX.

Fixed

• Docker compose UID/GID alignment (#1399, fixed by #1428) — the two- and three-container compose files had a UID mismatch between containers sharing the hermes-home volume: hermes-agent and hermes-dashboard ran as UID 10000 (image default) while hermes-webui ran as UID 1000 (WANTED_UID default), causing Permission denied errors on every shared file. All services now read from ${UID:-1000} and ${GID:-1000} so they align by construction. Empirically tested on both two- and three-container setups by the contributor. (#1428, @sunnysktsang)

Changed — Docker UX overhaul

After researching #1399, #1389, #858, #681, #668, and #569 plus closed-but-still-painful Docker reports, this release ships a coordinated set of doc/config improvements:

• All 3 compose files now document the HERMES_SKIP_CHMOD and HERMES_HOME_MODE escape hatches inline (the v0.50.254 fix for #1389 wasn't surfaced for Docker users).
• New .env.docker.example template specifically for Docker users, covering UID/GID, paths, password, and permission-handling escape hatches with explicit UID=1000/GID=1000 placeholders so macOS users don't skim past the warning.
• New docs/docker.md — comprehensive guide covering all 3 compose files, common failure modes (with one-line fixes), bind-mount migration recipe, multi-container architecture diagram, macOS Docker Desktop file-sharing implementation note, and pointer to the community all-in-one image for Podman 3.4 / multi-arch users.
• README Docker section rewritten — clearer 5-minute quickstart pointing at the single-container setup as the recommended path; failure-mode table with one-line fixes; pointer to docs/docker.md for the deep dive. Stale /root/.hermes reference removed (the agent images use /home/hermes/.hermes).

Pre-release hardening (Opus advisor)

• HERMES_HOME_MODE semantic asymmetry warning — Opus caught a footgun in my initial draft: HERMES_HOME_MODE means different things in the WebUI vs. the agent image:

  • WebUI: credential-FILE mode threshold (0640 allows group bits on .env)
  • 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 → bricked. My initial draft recommended HERMES_HOME_MODE=0640 as the example value in agent service blocks. Fixed across all 4 surfaces: compose files (per-service comments), .env.docker.example (multi-container warning), docs/docker.md (failure mode #2 callout). 3 dedicated regression tests pin the asymmetry.

Tests

3627 passed, 2 skipped, 3 xpassed (master 3615, +12 net). 12 regression tests in tests/test_v050260_docker_invariants.py covering UID/GID alignment (positive + negative-pattern guards), escape-hatch documentation across all compose files, .env.docker.example shape, docs/docker.md failure-mode coverage, README link integrity, YAML validity, and the agent vs WebUI HERMES_HOME_MODE asymmetry. Browser tests + Phase 2 API sanity all green.

What's NOT in this release

• A custom all-in-one Hermes image — sunnysktsang/hermes-suite already does this. The docs point at it as the right escape hatch for Podman 3.4 / multi-arch / supervisord-style preference.
• Resolving the architectural #681 (tools running in WebUI container, not agent container in two-container setups) — known limit, documented honestly in docs/docker.md failure mode #5 with three workarounds.

Contributors

@sunnysktsang

Full Changelog: v0.50.259...v0.50.260