Guide new installs to a first monitored workflow

Merged
YO
24d ago
+2605-387

What

Guide a fresh install from startup to a first monitored workflow, and fix the first-run bugs found on the way.

Startup

  • dagu server and dagu start-all now exit with an error when the web UI port is taken or the TLS certificate cannot be loaded. Before, the listener bound inside a goroutine, the error was only logged, and the process kept running without a web UI.
  • Port conflicts name the fix: --port / DAGU_PORT for the web UI, and --coordinator.port, DAGU_COORDINATOR_PORT or DAGU_COORDINATOR_ENABLED=false for the coordinator in start-all.
  • On a terminal, a short banner prints the web UI URL, the admin setup link while no user exists, the DAGs directory, and the free monitoring link on Community servers. Without a terminal, the "Server is starting" log line now carries url=.
  • start-all runs one notification/incident monitor pair (the scheduler's). Before, the server started a second pair in the same process, which logged "Notification lock is held by another process" on every start.

First-launch examples

  • New example-06-retry-on-failure: its first attempt fails and a step retry succeeds, which shows what an orchestrator adds over cron.
  • example-03-scheduling no longer claims to be scheduled while its schedule is commented out.

Web UI

  • Getting-started checklist on the Activity tab: run a workflow, create one, put one on a schedule, get alerted when something fails. Steps complete from server state. A server already in use when first seen never shows it, and dismissal is remembered per server.
  • Free Dagu Console monitoring is offered where alerts matter: the checklist's last step, the empty notification rules page, the Overview of a workflow with an active schedule, and an admin-only "External Monitoring" sidebar link to /license#monitoring. The offer is dismissible and shown only to admins of Community servers whose license is not set by environment variables.
  • The step table shows "Retried N×" when a step was retried.
  • Bug fixes: the empty-state create button was hidden under the default "All workspaces" selection; empty-state and DAG name validation strings were untranslated; the create dialog showed a raw regex and set a pattern attribute that browsers reject; the Start dialog showed "Parameters 0 fields".

Packaging and README

  • README quick start: write hello.yaml in an empty folder (--dags . loads every YAML file in the folder), create the admin account, and a note for script-installer users whose service already runs on 8080.
  • Homebrew caveats, installer summaries list the DAGs directory and the monitoring link, and npm postinstall no longer prints debug output or leaves a failed download unhandled.

Why

A fresh install worked, but it showed nothing a cron job could not do, buried the free monitoring offer under Plan & features, and had sharp edges on the quick start path (silent port conflicts, a missing create button, stray YAML loaded as broken workflows).

Docs

Companion PR for the docs site quickstart: https://github.com/dagucloud/docs/pull/52 (merge after this one).

Test plan

Regression tests that failed before their fix:

  • TestServeListenFailure/PortInUse, /MissingTLSCert (frontend): timed out because Serve kept blocking.
  • TestServerCommand/PortInUse, TestStartAllCommand/WebPortInUse: the command kept running.
  • TestStartAllCommand/CoordinatorPortInUse: the error had no hint.
  • TestFirstLaunchExamplesLoadAndRun: now asserts example-06 exists and its call_api step was retried once in a succeeded run.
  • DAGTable.test.tsx and pages/__tests__/index.test.tsx: create button missing under "All workspaces"; untranslated empty state.

New tests: TestServeWithoutNotificationMonitors, TestLocalURL, TestStartupBanner, MonitoringOffer.test.tsx, useStoredValue.test.tsx, gettingStarted.test.ts, useGettingStarted.test.tsx, GettingStartedChecklist.test.tsx, placement tests for the notifications, DAG and license pages, menu test, and Playwright e2e/getting-started.spec.ts (1440 and 390 widths, dismissal survives reload).

Commands run:

  • make test TEST_TARGET=... for internal/service/frontend, internal/cmd, internal/persis/file/dag, internal/service/scheduler; go test -race ./internal/intg/ -run TestServer
  • make fmt, make check (0 issues on linux, windows, darwin), make conformance
  • pnpm test, pnpm typecheck, pnpm build
  • make test-e2e for getting-started, license-experience, dag-crud, notification-rules (14 passed)
  • Manual: fresh DAGU_HOME under a pty shows the banner and no "standby" line; piped output has no banner; a second server on the same port exits 1 with the hint; setup, checklist, retry example run ("Retried 1×"), and checklist progress in a browser.

Summary by CodeRabbit

  • New Features
    • Added a getting-started checklist to guide setup, workflow creation, scheduling, and notifications.
    • Community administrators can find free server-monitoring information from the dashboard, scheduled workflows, notification rules, and navigation.
    • Workflow steps now show when they have been retried, and a retry example is available.
    • Startup guidance shows the local UI address and, when needed, the admin setup link.
  • Bug Fixes
    • Port conflicts now include guidance for resolving the issue.
    • Workflow parameter controls and name-validation messages are clearer.
  • Documentation
    • Updated quick-start instructions for creating and running workflows, including service-based installations.