docs(docker): point gateway-not-configured banner at a real fix

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 #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 #2785
This commit is contained in:
Sanjay Santhanam
2026-05-25 11:35:24 -07:00
parent 48a2e79224
commit 655b5f9101
3 changed files with 33 additions and 1 deletions

View File

@@ -3,6 +3,10 @@
## [Unreleased]
### Changed
- Tasks panel "Gateway not configured" banner now includes a direct link to the new `docs/docker.md#scheduled-jobs-require-a-gateway-daemon` section that walks through running the gateway container so scheduled cron jobs actually tick. (Refs #2785)
## [v0.51.137] — 2026-05-25 — Release DI (stage-batch19 — 6-PR medium-risk batch)
### Added

View File

@@ -51,7 +51,7 @@ them manually from the Tasks panel. In Docker, scheduled jobs require the Hermes
to tick while you are away. If System Settings shows `Gateway not configured`,
use `docker-compose.two-container.yml`,
`docker-compose.three-container.yml`, or run `hermes gateway` separately before
relying on offline scheduled runs.
relying on offline scheduled runs. See [Scheduled jobs require a gateway daemon](#scheduled-jobs-require-a-gateway-daemon) below for the full background and verification steps.
For troubleshooting, reinstall, or onboarding reproduction trials, do not mount
your real `~/.hermes` unless you intentionally want to test real state. Use an
@@ -60,6 +60,29 @@ isolated Hermes home and follow
## What goes wrong (and how to fix it)
### Scheduled jobs require a gateway daemon
**Symptom**: Cron jobs created in the Tasks panel never fire. System Settings shows the orange "Gateway not configured" pill, and the Tasks panel shows the same banner above the job list.
**Cause**: Scheduled cron ticks are not driven by the WebUI itself. The gateway daemon ticks the scheduler every 60 seconds; without one running, scheduled jobs sit idle. "Run now" / "Trigger" buttons still work because the WebUI handles those in-process.
**Fix**: Run a gateway container alongside the WebUI. The two-container compose file is the recommended path:
```bash
cp .env.docker.example .env
docker compose -f docker-compose.two-container.yml up -d
```
The three-container layout adds the dashboard but is otherwise the same shape. If you must stay single-container, you can run `hermes gateway` inside the container as a long-lived background process, but the compose split is sturdier.
**Verify**: Once the gateway is up, the System Settings pill should turn green and the Tasks banner disappear. From inside the gateway container:
```bash
docker exec -it <gateway-container> hermes gateway status
```
Refs #2785.
### 1. "Permission denied" at startup
**Symptom**: Container starts but immediately crashes, logs show:

View File

@@ -437,9 +437,14 @@ function _cronGatewayNoticeHtml(status) {
const body = notConfigured
? 'In Hermes WebUI, scheduled jobs require the Hermes gateway daemon. If this is a single-container Docker install, jobs can be created and run manually here, but scheduled ticks need a gateway container or `hermes gateway` running outside the WebUI.'
: 'In Hermes WebUI, scheduled jobs require the Hermes gateway daemon to be running. Start the gateway container or `hermes gateway` before relying on offline scheduled runs.';
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>`
: '';
return `
<div class="detail-alert-title">${esc(title)}</div>
<p>${esc(body)}</p>
${helpLink}
`;
}