bunqueue-dashboard

v0.0.47

Published

15 days ago

Web dashboard for a bunqueue server (queues, jobs, DLQ, cron, metrics, workers, live activity). Run with `bunx bunqueue-dashboard` (requires Bun 1.4.2).

bunqueue dashboard

Monitor jobs and operate your Bunqueue server from one dashboard.

Manage queues, jobs, DLQ, cron, webhooks, workers, and a live activity stream for a bunqueue server (a fast, Redis-free, Bun-native background-job queue), plus start / stop / restart of the server process itself, all from one place.

For Bun developers and AI-agent builders running bunqueue who want to operate their queue, not just watch it.

📚 Read the documentation · ▶ Try the live demo

Quick start · User guide · Deployment · Verified test coverage

The live demo uses sample data. The docs explain how to connect and operate a real Bunqueue server.

A quick tour. Try it live →

The Overview page. See every screen in the illustrated guide →

⚠️ Beta. bunqueue dashboard is under active development, interfaces and behavior may change between releases. Review it before relying on it for unattended production use.

📚 Documentation

Full, illustrated docs live at egeominotti.github.io/bunqueue-dashboard/docs.

Illustrated user guide, section guides with screenshots, operations and limitations.
Deployment, Docker (Caddy), Kubernetes, PM2, and hosting platforms (Vercel, Netlify, Cloudflare, Fly.io, Render, Cloud Run).
Architecture and API mapping, how it fits together and every endpoint it drives.
Testing matrix, real-server coverage, reproduction steps and verification limits.
llms.txt, the documentation index for LLMs; llms-full.txt contains the full text.

Why

bunqueue exposes a rich HTTP API, but operating it by hand (curl, ad-hoc scripts) is slow and error-prone. This dashboard is a production-oriented operator console: it exposes the verified, safe subset of the API, fails closed where Bunqueue 2.9.x lacks atomic flow-safety guarantees, and also manages the server process through a separate guarded agent.

It uses Bunqueue's public HTTP API (:6790) for ordinary remote observability and a small local control agent for process, FlowProducer, Workflow Engine, database, and backup operations. The agent is pinned to the server it manages and uses the exact installable Bunqueue 2.9.4 npm client contracts; it never patches Bunqueue internals.

Features

| Area | Where | What you can do | | --- | --- | --- | | Home | Overview | Live health banner, throughput, queue health, recent activity | | Fleet | Fleet | Probe and operate multiple Bunqueue APIs + paired agents; verify shared PostgreSQL target/namespace topology | | Server | Control ▸ Server | Start / stop / restart the server process, edit its config, tail process logs | | Enqueue | Control ▸ Add Job | Add jobs (single or bulk) with every option | | Inspect | Control ▸ Job Inspector | Look up any job; promote / re-prioritize / delay; view data & result | | Queues | Control ▸ Queue Control | Pause/resume/promote; desired-state writes plus live SDK limits, group jobs/priorities/pause/policies, deduplication, metrics and journal retention | | Cron | Control ▸ Cron Manager | Submit acknowledged cron/interval upserts and delete schedules | | Workflow Engine | Workflow ▸ Overview / Executions / Waiting / Compensation / Archive | Start, recover, signal, inspect, compensate, archive and clean durable executions | | Job Flows | Workflow ▸ Job Flows | Explore DAGs, run all FlowProducer create modes and operate safe Flow Job methods | | DLQ | Control ▸ DLQ | Inspect/export failures; removal, retry and purge stay unavailable without atomic generation/topology preconditions | | Webhooks | Control ▸ Webhooks | Create / enable / delete job-event webhooks | | Ops | Control ▸ Diagnostics | Health, ping, storage, memory, connections, totals | | S3 backup | Management ▸ S3 Backup | Configure, inspect, list, create and guarded-restore official snapshots | | Browse | Queues / Jobs / DLQ / Cron / Metrics / Workers / Logs | Read-only browsing with basic actions |

Job actions are gated by the v2.9.3 flow contract. Every DLQ retry and completed-job requeue is unavailable: the DLQ GET + POST sequence has no atomic generation/state/topology precondition and can target a job recreated under the same ID, while retryCompleted does not rebuild dependency registration or flow order. Cancel, Discard, Drain, Clean, Obliterate and DLQ Purge also fail closed. Bunqueue 2.9's Queue.removeDlqJob() also accepts only queue + job ID, so custom-ID reuse prevents the dashboard from proving that a later deletion still targets the observed generation. DLQ maxAge/maxEntries are read-only, auto-retry can only be disabled, and Copilot's only mutations are Promote, Pause and Resume.

Quick start

Prerequisites: Bun 1.4.2 and a reachable bunqueue server (or let the control agent start one for you from the Server page).

Run from npm (no clone)

bunx bunqueue-dashboard

One command serves the prebuilt dashboard on http://127.0.0.1:8080, proxies /api/* to your bunqueue server (BUNQUEUE_URL, default http://localhost:6790), and runs the control agent on 127.0.0.1:6800. Same env knobs as the standalone binaries: PORT · BIND_ADDR · BUNQUEUE_URL · AGENT_PORT · AGENT_ALLOWED_ORIGINS · AGENT_ALLOWED_HOSTS · AGENT_TOKEN · BUNQUEUE_TOKEN · TRUST_PROXY · BASE_PATH · BUNQUEUE_MANAGED · BUNQUEUE_START_CMD.

Install it permanently instead of running via bunx:

bun add -g bunqueue-dashboard
bunqueue-dashboard

Run from source

git clone https://github.com/egeominotti/bunqueue-dashboard.git
cd bunqueue-dashboard
bun install
bun start

bun start boots both the control agent and the dashboard in one terminal and shuts both down on Ctrl-C:

| Service | URL | Role | | --- | --- | --- | | Dashboard | http://localhost:5273 | The UI (/api/* is proxied to :6790 in dev) | | Control agent | http://127.0.0.1:6800 | Starts / stops / restarts the server process | | bunqueue server | http://localhost:6790 | Your queue server, started from the Server page or run separately |

Prefer separate terminals? The individual commands still exist, see Scripts.

Architecture

flowchart LR
    subgraph Browser
        UI["Dashboard (React 19 SPA)"]
    end
    subgraph Local
        Agent["Control agent (Bun)<br/>127.0.0.1:6800"]
        Server["bunqueue server<br/>:6790 HTTP · :6789 TCP"]
    end
    UI -- "HTTP: queues, jobs, DLQ, cron…" --> Server
    UI -- "SSE: live activity" --> Server
    UI -- "/control/* start·stop·restart" --> Agent
    Agent -- "spawn / kill process" --> Server

Reads by polling (usePolledData) and a Server-Sent Events stream (useActivityStream).
Writes through the same HTTP API, with every mutation shape-verified against the live server.
Managed operations use the local control agent for process lifecycle, Queue SDK controls, FlowProducer, Workflow Engine, SQLite inspection, and backups.

For multiple brokers, create one named Dashboard profile and one paired control agent per broker. The Fleet page probes all profiles without retargeting the active UI, groups brokers that share an exact PostgreSQL target + namespace, and drives each node's Start/Stop/Restart controls. Queue state is shared by PostgreSQL; lifecycle, process logs/config, in-memory webhooks, and each agent's Workflow Engine store remain node-local. See the Fleet guide.

Two HTTP clients coexist on purpose: src/lib/api.ts (first-generation view pages) and src/lib/bq.ts (the complete, shape-verified client used by every Control ▸ * page). See docs/ for the full, source-verified reference.

Configuration

The VITE_* dashboard defaults are build-time values and can also seed the first named profile in Settings. Add up to 32 broker/agent profiles at runtime. The all-in-one server reads the non-VITE_* runtime variables below. Copy .env.example to .env to set defaults.

| Variable | Purpose | Default | | --- | --- | --- | | VITE_BUNQUEUE_URL | bunqueue server origin | /api (dev proxy → :6790) | | VITE_BUNQUEUE_AGENT_URL | Control-agent origin | http://localhost:6800 | | BIND_ADDR | All-in-one dashboard bind address | 127.0.0.1 | | BASE_PATH | Runtime mount for the all-in-one server (for example /internal/queue) | / | | BUNQUEUE_MANAGED | 0 attaches to the externally supervised BUNQUEUE_URL; 1 enables local lifecycle controls | 1 | | AGENT_PORT | Control-agent port | 6800 | | AGENT_ALLOWED_ORIGINS | Extra browser origins allowed to drive the agent (comma-separated) | dev defaults | | AGENT_ALLOWED_HOSTS | Extra Host names/IPs accepted by the all-in-one server and agent | loopback names | | AGENT_TOKEN | Agent bearer token; mandatory on every bridged route for LAN/proxy access | none (local-only) | | BUNQUEUE_TOKEN | Admin-API bearer; mandatory on every /api/* route for LAN/proxy access | none (/api remote-disabled) | | TRUST_PROXY | Trust an overwritten X-Forwarded-Host from a Host-rewriting proxy (1) | off |

Server and agent bearer tokens are secrets: enter them in Settings or the authentication prompt for the current browser session. Do not put secrets in a VITE_* variable; Vite values are compiled as plaintext into the public bundle.

For BIND_ADDR=0.0.0.0, list every LAN hostname/IP in AGENT_ALLOWED_HOSTS (or its full origin in AGENT_ALLOWED_ORIGINS) and set both AGENT_TOKEN and BUNQUEUE_TOKEN. Enter BUNQUEUE_TOKEN as the Server token in Settings; when Bunqueue itself uses AUTH_TOKENS, use the same token there so the forwarded Authorization header is valid upstream. Behind a reverse proxy, allowlist the public origin; if it rewrites Host, also allowlist the rewritten Host and use TRUST_PROXY=1 only when the proxy overwrites X-Forwarded-Host.

For a broker already owned by systemd, Docker or Kubernetes, run the all-in-one dashboard with BUNQUEUE_MANAGED=0. Control ▸ Server then reports health from BUNQUEUE_URL and cannot spawn, stop, restart or reconfigure a child. Stopped-only backup restore is also rejected because the dashboard cannot prove that an externally supervised broker is inactive. To mount the same process below a reverse-proxy prefix, set for example BASE_PATH=/internal/queue and preserve that prefix when proxying; the SPA, assets, /api proxy and /agent bridge all move below it, including the target-pinned Flow, Workflow, Queue and Backup agent operations.

Scripts

| Command | Does | | --- | --- | | bun start | Agent + dashboard together (one-command dev) | | bun dev | Dashboard only (Vite dev server) | | bun run agent | Control agent only | | bun run build | Typecheck (tsc --noEmit) + production build → dist/ | | bun run preview | Preview the production build | | bun run lint | Lint with Oxlint, including type-aware rules and the implicit-any parity guard | | bun run format:check | Check formatting with Oxfmt | | bun run check | Oxlint + Oxfmt validation (the CI gate) | | bun run check:fix | Apply safe Oxlint fixes, then format with Oxfmt | | bun test | Unit + agent-lifecycle tests | | bun run test:e2e:tls | Queue, Flow and Workflow over verified native TLS, including untrusted-certificate rejection | | bun run test:e2e:upgrade | Real npm Bunqueue 2.9.2 SQLite schema-35 → 2.9.4 schema-37 migration and retention semantics | | bun run test:e2e | Real TLS, SQLite upgrade, Flow, Workflow, Queue SDK, and three-broker PostgreSQL runtime tests | | bun run test:e2e:browser | Production UI tests on Chromium, Firefox and WebKit | | bun run test:e2e:browser:postgres-fleet | Real UI operations across three PostgreSQL brokers (requires Docker and Chromium) | | bun run quality | Complete static, build, docs, coverage, runtime, package and dependency gate | | bun run test:e2e:postgres-fleet | Three authenticated Bunqueue 2.9.4 brokers + three agents sharing disposable PostgreSQL 18.6 |

Docker

A multi-stage image builds the SPA with Bun and serves it with Caddy (gzip/zstd, SPA history fallback, immutable asset caching). Published to the GitHub Container Registry on every push.

# Pull & run the published image (`edge` tracks main; use `vX.Y.Z`/`latest` after a release)
docker run --rm -p 8080:80 ghcr.io/egeominotti/bunqueue-dashboard:edge
# → http://localhost:8080  (set the server URL from the Settings page)

# …or build locally, optionally baking in a default server origin
docker build --build-arg VITE_BUNQUEUE_URL=https://queue.example.com -t bunqueue-dashboard .
docker run --rm -p 8080:80 bunqueue-dashboard

Tags: latest and vX.Y.Z on releases, edge on main.

Deployment

Standalone executables, every release ships self-contained binaries for Linux (x64/arm64), macOS (x64/arm64) and Windows (x64): download one file and run it, it serves the dashboard (assets embedded), proxies /api to your bunqueue server (BUNQUEUE_URL, default :6790) and includes the control agent.
```
./bunqueue-dashboard-vX.Y.Z-darwin-arm64        # → http://localhost:8080
PORT=3000 BUNQUEUE_URL=https://queue.example.com ./bunqueue-dashboard-vX.Y.Z-linux-x64
```
GitHub Pages, every push to main builds and publishes the static SPA (.github/workflows/pages.yml). The workflow attempts to auto-provision Pages; if the first run reports Get Pages site failed, enable it once under Settings ▸ Pages ▸ Source → GitHub Actions (the default GITHUB_TOKEN can't create a Pages site on its own). The build sets the correct sub-path base and a 404.html SPA fallback automatically.
Container, self-host the published ghcr.io image behind any reverse proxy.
Static host, bun run build emits a plain dist/ you can serve from any CDN or static host.

Because the deployed build is a static shell, point it at a reachable bunqueue server via VITE_BUNQUEUE_URL (build time) or the Settings page (runtime).

Testing & quality gate

Use both the canonical gate and browser tests to validate a change. Browser tests are a separate CI job; quality alone does not run Playwright:

bun run test:e2e:browser:install  # first run only
bun run quality                  # includes runtime E2E; requires Docker
bun run test:e2e:browser          # production UI on all three browser engines
bun run test:e2e:browser:postgres-fleet # cross-node UI; separate from both commands above

The E2E stage starts disposable Bunqueue 2.9.4 processes and exercises the complete FlowProducer, Workflow Engine, and Queue SDK operator bridges. It also starts PostgreSQL 18.6 in Docker with three authenticated brokers and paired agents, proving cross-broker enqueue/inspect/leased pull+ack, pause/resume, cron, rate limits, group admission, group priority and group pause/resume on PostgreSQL schema 20. Run it alone with bun run test:e2e (Docker is required for the PostgreSQL stage).

The blocking browser job builds the production bundle under /e2e/dashboard, starts an authenticated disposable Bunqueue server, and drives the UI with Playwright on Chromium, Firefox, and WebKit. It covers the token gate, every sidebar route, SSE recovery across a real server restart, confirmed Cron creation/deletion, job submission and bulk import, persisted job inspection, DLQ failures, live monitoring and alerts, SQLite queries, webhook registry mutations, a real producer/worker benchmark, and automated WCAG A/AA checks. Install the browser binaries once with bun run test:e2e:browser:install, then run bun run test:e2e:browser.

See the section-by-section validation matrix for reproducible commands, prerequisites, and the distinction between live operations, navigation checks, and external integrations that need their own environment. The live demo uses sample data and is not test evidence.

CI enforces the quality gate and browser matrix on every push and pull request. See Contributing.

Project structure

bunqueue-dashboard/
├── .github/workflows/   # CI, Pages deploy, Docker publish, Release
├── agent/               # guarded process, Flow, Workflow, Queue, database and backup adapters
├── docker/              # Caddyfile for the container image
├── docs/                # source-verified reference (architecture, pages, API mapping, known issues)
├── scripts/dev.ts       # one-command dev launcher (`bun start`)
├── src/
│   ├── lib/             # api.ts, bq.ts, hooks, formatters, job-action gating
│   ├── components/      # layout shell, UI kit, Zustand stores
│   ├── features/        # feature slices with domain, application, infrastructure and UI layers
│   └── pages/           # view pages + Control ▸ * operator pages
└── test/                # unit, contract, UI race, agent lifecycle and integration tests

Full walkthrough in docs/README.md.

Security

The control agent can spawn processes, so it is hardened by design (agent/server.ts):

Binds 127.0.0.1 only.
CORS locked to an allowlist, Access-Control-Allow-Origin is never *.
Requests carrying a disallowed Origin are rejected (403) before reaching the process manager, blocking drive-by CSRF from a malicious tab.
A Host allowlist blocks DNS-rebinding requests and fails closed for unknown names.
Truly local agent reads stay zero-configuration; any LAN/proxied /agent bridge requires AGENT_TOKEN on every route.
The all-in-one server requires BUNQUEUE_TOKEN on every LAN/proxied /api/* route; without it the API proxy returns 403 before contacting Bunqueue.
Embedded and Docker responses deny framing, MIME sniffing and referrer leakage.

Keep the direct agent port on loopback. Static/Caddy deployments that expose Bunqueue directly must still use Bunqueue AUTH_TOKENS or front-proxy authentication; the all-in-one BUNQUEUE_TOKEN boundary applies only to scripts/serve.ts. Host/Origin checks are not user authentication. See docs/known-issues.md for the honest, verified limitations.

Contributing

Keep it additive, prefer new files + minimal glue over rewriting existing ones (see CLAUDE.md).
Make the gate green: bun run quality.
Open a PR, the template walks you through the checklist. CI must pass.