Skip to content

docs(docker): give the cron 'Gateway not configured' banner a real fix link#2950

Merged
2 commits merged into
nesquena:masterfrom
Sanjays2402:docs/2785-scheduled-jobs-link
May 26, 2026
Merged

docs(docker): give the cron 'Gateway not configured' banner a real fix link#2950
2 commits merged into
nesquena:masterfrom
Sanjays2402:docs/2785-scheduled-jobs-link

Conversation

@Sanjays2402

Copy link
Copy Markdown
Contributor

Picks up the docs-PR follow-up the maintainer suggested in #2785: single-container Docker installs surface a 'Gateway not configured' banner in the Tasks panel but don't tell the user where to go next.

Two small changes:

  1. New 'Scheduled jobs require a gateway daemon' section in docs/docker.md under 'What goes wrong' with the two-container compose command and a verify step. The existing short blurb higher up now cross-links to it, so both entry points land on the same fix.
  2. loadCronGatewayNotice in static/panels.js appends a 'How to enable scheduled jobs in Docker ↗' link to the banner when the gateway is unconfigured. Banner text itself is unchanged; the link is hidden in the 'configured but not running' branch where the message is different and the next step is just to start the daemon.

Verified locally by running the WebUI with no gateway, opening Tasks, and confirming the new link appears and lands on the new docs section. Started hermes gateway and confirmed the banner goes away.

Refs #2785

Scheduled cron jobs created in the Tasks panel never tick on a
single-container Docker install because the WebUI doesn't run the
gateway daemon itself. The maintainer's analysis on nesquena#2785 spells this
out: the gateway ticks the scheduler every 60s, and without it
'Gateway not configured' just sits there.

The Tasks panel already shows a banner explaining this, but doesn't
give the user anywhere to go. Two small docs-shaped changes:

1. Add a 'Scheduled jobs require a gateway daemon' section to
   docs/docker.md under 'What goes wrong' with the two-container
   compose command and a verify step. Cross-linked from the existing
   short paragraph higher up so both entry points land on the same
   fix.

2. Append a 'How to enable scheduled jobs in Docker' link to the
   cron panel banner (loadCronGatewayNotice) pointing at the new
   docs anchor when the gateway is unconfigured. The banner text
   itself is unchanged.

Verified locally by serving the WebUI without a gateway, opening
Tasks, and confirming the banner now shows the new link; clicked it
and confirmed it lands on the new docs section. With the gateway
running the banner stays hidden as before.

Refs nesquena#2785
@nesquena-hermes

Copy link
Copy Markdown
Collaborator

Summary

Thanks @Sanjays2402 — this is the right shape for the #2785 docs follow-up. The banner currently dead-ends users; an inline anchor to the docs is minimum-viable and well-scoped. I read static/panels.js:430-460 (the notice renderer) plus the new docs/docker.md section, and cross-checked the gateway's cron tick at ~/.hermes/hermes-agent/gateway/run.py:17858-17880 against your "Cause" paragraph.

Two small things to address, plus a couple optional polish points.

Code reference

PR head at static/panels.js:437-449:

const docsHref = 'https://github.com/nesquena/hermes-webui/blob/master/docs/docker.md#scheduled-jobs-require-a-gateway-daemon';
const helpLink = notConfigured
  ? `<p><a href="${docsHref}" target="_blank" rel="noopener">How to enable scheduled jobs in Docker ↗</a></p>`
  : '';

The cron tick the docs describe at gateway/run.py:17858-17880:

def _start_cron_ticker(stop_event, adapters=None, loop=None, interval: int = 60):
    """Background thread that ticks the cron scheduler at a regular interval.
    Runs inside the gateway process so cronjobs fire automatically without
    needing a separate `hermes cron daemon` or system cron entry."""

So the "gateway daemon ticks every 60s" framing matches the agent code.

Diagnosis

1. Section numbering breaks visual flow

You inserted ### Scheduled jobs require a gateway daemon before the existing numbered list (### 1. "Permission denied" through ### 7.). Rendered top-to-bottom, that gives an unnumbered subsection followed by 1, 2, …, 7. Readers will read this as "section 0" or "the numbering is broken."

Options:

  • Lowest churn: title it ### 0. Scheduled jobs require a gateway daemon.
  • Best fit (my preference): promote it above ## What goes wrong (and how to fix it) into its own ## Scheduled jobs and the gateway daemon H2. It isn't really a "what went wrong" entry — it's the architectural explanation behind the banner. The numbered 1–7 stay coherent, and the existing cross-link from docs/docker.md:49-53 (quickstart paragraph) still resolves because the heading slug is unchanged.

2. The verify command names a container the user doesn't have yet

The verify step:

docker exec -it <gateway-container> hermes gateway status

Anyone landing here doesn't have a gateway container yet — the banner is what brought them. The gateway service name in docker-compose.two-container.yml is concrete and known; substituting it makes the step copy-paste-ready, e.g. docker compose -f docker-compose.two-container.yml exec gateway hermes gateway status (please verify the service name against the actual compose file; I didn't open it). If the name varies, add a one-liner docker compose -f docker-compose.two-container.yml ps so users can discover their own.

Optional polish

  • The notConfigured branch shows the link; "configured but not running" hides it. That's right — the latter says "start the gateway container," which is enough.
  • alone is poor for screen readers. aria-label="How to enable scheduled jobs in Docker (opens in new tab)" on the anchor, or an aria-hidden SVG plus (opens in new tab) text suffix, would be cleaner. Not blocking.
  • The hardcoded github.com/.../blob/master/docs/... URL is consistent with how other in-app docs links are written, so fine as-is. A shared DOCS_BASE_URL would future-proof if the docs ever move, but out of scope.

Test plan

After the two fixes:

  1. WebUI single-container, no gateway. Open Tasks. Confirm the new link is in the banner and lands on the right anchor.
  2. View the GitHub-rendered docs page and confirm #scheduled-jobs-require-a-gateway-daemon resolves (GitHub slugifies headings; the slug for "Scheduled jobs require a gateway daemon" is exactly that, and a promotion to H2 doesn't change the slug).
  3. Stop the gateway (so configured=true, running=false). Confirm the banner switches to "Gateway not running" with no docs link — the asymmetry you intentionally kept.
  4. Start the gateway. Banner disappears.

LGTM in concept — the user-facing improvement is real and the docs section is well-written. Just want the numbered-flow + copy-pasteable verify step tightened up before merge.

@Sanjays2402

Copy link
Copy Markdown
Contributor Author

Fixed in cf94f2f. Promoted the section to its own H2 (## Scheduled jobs and the gateway daemon) so the 1\u20137 numbered list stays coherent, updated the in-app anchor to the new slug, and rewrote the verify command to docker compose -f docker-compose.two-container.yml exec hermes-agent hermes gateway status so it runs before the user has a container, with a compose ps discover line for non-standard service names.

@nesquena-hermes

Copy link
Copy Markdown
Collaborator

Merged in Release DJ / v0.51.138 (stage-batch20 — 7-PR ultra-safe batch with PRs #2948 #2949 #2950 #2960 #2972 #2975 #2982).

Thanks @Sanjays2402! 🚢

franksong2702 pushed a commit to franksong2702/hermes-webui-fork that referenced this pull request May 27, 2026
# Conflicts:
#	CHANGELOG.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants