# @bull-board

Dashboard UI for Bull and BullMQ job queues. Plug it into your server, see your queues.

_{Light and dark ship together, and this picks whichever you are reading in.}

Documentation · What you get · Install · Minimal Express example · Historical metrics · Packages · Contributing

#Try it

If you already have a Redis with queues in it, one command gets you the dashboard:

npx @bull-board/cli -r redis://localhost:6379

Or as a container, no Node needed (docs):

docker run --rm -p 127.0.0.1:3000:3000 ghcr.io/felixmosh/bull-board --redis redis://host.docker.internal:6379

No install and no code. To embed it in your own app instead, read on.

#Documentation

The docs have guides, recipes, the UIConfig reference, and per-adapter setup. There's also a live demo covering every view below.

#What you get

Every repeatable job across every queue, with its pattern or interval, when it next fires and when it last ran. Edit or remove one in place.	Opt-in throughput and latency history over 90 days, per queue and board-wide. The storage panel tells you what keeping it costs.
Parent and child jobs as one pannable graph, even when the children live in other queues, each with its own state and progress. Click a node to inspect it without leaving the page. Per-job logs alongside.	Design tokens named after the shadcn contract. Set primary and the focus ring, the sidebar and the selection states all follow it.

#Install

Pick the adapter for your framework:

npm install @bull-board/api @bull-board/express
# or @bull-board/fastify, @bull-board/koa, @bull-board/hapi,
# @bull-board/nestjs, @bull-board/hono, @bull-board/h3,
# @bull-board/elysia, @bull-board/bun

Just want to look at a queue without wiring anything into your app? See the CLI guide.

#Minimal Express example

const express = require('express');
const { Queue } = require('bullmq');
const { createBullBoard } = require('@bull-board/api');
const { BullMQAdapter } = require('@bull-board/api/bullMQAdapter');
const { ExpressAdapter } = require('@bull-board/express');

const emailQueue = new Queue('emails', { connection: { host: 'localhost', port: 6379 } });

const serverAdapter = new ExpressAdapter();
serverAdapter.setBasePath('/admin/queues');

createBullBoard({
  queues: [new BullMQAdapter(emailQueue)],
  serverAdapter,
});

const app = express();

app.use('/admin/queues', serverAdapter.getRouter());

// other configurations of your server

app.listen(3000, () => {
  console.log('Running on 3000...');
  console.log('For the UI, open http://localhost:3000/admin/queues');
  console.log('Make sure Redis is running on port 6379 by default');
});

That's it! Now you can access the /admin/queues route, and you will be able to monitor everything that is happening in your queues 😁

See the docs for queue adapter options (read-only, retries, formatters, visibility guard), BullMQ Pro setup, board UI config, and more.

BullMQ >= 5.56.0 and all of v6 are supported, including v6 queues stored in PostgreSQL. The adapter detects which it has, so there is nothing to configure. See supported versions for what CI tests and when the floor moves.

#Historical metrics

BullMQ keeps only a short ring buffer of per-minute metrics, so the throughput chart can't look back further than an hour or so. The optional @bull-board/metrics package (beta) snapshots those metrics into long-retention Redis buckets and feeds them back to the board, which adds a Metrics history page and 7/30/90 day ranges on every queue chart. It is entirely opt-in: without it the core stays stateless and writes nothing.

npm install @bull-board/metrics

The CLI and the Docker image carry the package already, so --history turns the same thing on with nothing to install:

npx @bull-board/cli -r redis://localhost:6379 --history

See the historical metrics recipe for the recorder setup and storage sizing, or try it on the live demo.

#Packages

Name	Version	Downloads
@bull-board/api
@bull-board/ui
@bull-board/metrics
@bull-board/cli
@bull-board/express
@bull-board/fastify
@bull-board/koa
@bull-board/hapi
@bull-board/nestjs
@bull-board/hono
@bull-board/h3
@bull-board/elysia
@bull-board/bun

#Contributing

Issues and PRs welcome. Check the issues page before opening a new one. When reporting a bug, include versions (Node, Redis, Bull/BullMQ, bull-board) and a minimal reproduction.

To develop locally:

git clone git@github.com:felixmosh/bull-board.git
cd bull-board
yarn && yarn dev:docker && yarn build && yarn dev

This starts Redis, builds the packages, and opens the dev server at http://localhost:3000/ui. See CONTRIBUTING.md for the monorepo layout, running tests and examples, and adding a new server adapter.

#Acknowledgements

• Juan for building the first version of this library.

#License

MIT.