@bull-board

Bull Dashboard is a UI built on top of Bull or BullMQ to help you visualize your queues and their jobs. With this library you get a beautiful UI for visualizing what's happening with each job in your queues, their status and some actions that will enable you to get the job done.

Packages

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

Notes

As this library provides only the visualization for your queues, keep in mind that:

• You must have either Bull or BullMQ installed in your projects;
• Aside the options to retry and clean jobs, this library is not responsible for processing the jobs, reporting progress or any other thing. This must be done in your application with your own logic;
• If you want to understand the possibilities you have with the queues please refer to Bull's docs or BullMQ's docs;
• This library doesn't hijack Bull's way of working.

If you want to learn more about queues (Bull or BullMQ) and Redis.

Starting

To add it to your project start by installing a server framework specific adapter to your dependencies list:

1yarn add @bull-board/express
2# or
3yarn add @bull-board/fastify
4# or
5yarn add @bull-board/hapi
6# or
7yarn add @bull-board/koa
8# or
9yarn add @bull-board/nestjs
10# or
11yarn add @bull-board/hono
12# or
13yarn add @bull-board/h3
14# or
15yarn add @bull-board/elysia

NestJS specific setup

@bull-board provides a module for easy integration with NestJS, for reference on how to use the module refer to the NestJS Module package

Hello World

1const express = require('express');
2const Queue = require('bull');
3const QueueMQ = require('bullmq');
4const { createBullBoard } = require('@bull-board/api');
5const { BullAdapter } = require('@bull-board/api/bullAdapter');
6const { BullMQAdapter } = require('@bull-board/api/bullMQAdapter');
7const { ExpressAdapter } = require('@bull-board/express');
8
9const someQueue = new Queue('someQueueName', {
10  redis: { port: 6379, host: '127.0.0.1', password: 'foobared' },
11}); // if you have a special connection to redis.
12const someOtherQueue = new Queue('someOtherQueueName');
13const queueMQ = new QueueMQ('queueMQName');
14
15const serverAdapter = new ExpressAdapter();
16serverAdapter.setBasePath('/admin/queues');
17
18const { addQueue, removeQueue, setQueues, replaceQueues } = createBullBoard({
19  queues: [new BullAdapter(someQueue), new BullAdapter(someOtherQueue), new BullMQAdapter(queueMQ)],
20  serverAdapter: serverAdapter,
21});
22
23const app = express();
24
25app.use('/admin/queues', serverAdapter.getRouter());
26
27// other configurations of your server
28
29app.listen(3000, () => {
30  console.log('Running on 3000...');
31  console.log('For the UI, open http://localhost:3000/admin/queues');
32  console.log('Make sure Redis is running on port 6379 by default');
33});

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 😁

For more advanced usages check the examples folder, currently it contains:

1. Basic authentication example
2. Multiple instance of the board
3. With Fastify server
4. With Hapi.js server
5. With Koa.js server
6. With Nest.js server using the built-in module (Thanx to @dennissnijder)
7. With Nest.js server using the express adapter (Thanx to @lodi-g)
8. With Hono server (Thanks to @nihalgonsalves)
9. With H3 server using the h3 adapter (Thanx to @genu)
10. With Elysia server using the elysia adapter (Thanx to @kravetsone)

Board options

1. uiConfig.boardTitle (default: Bull Dashboard) The Board and page titles
2. uiConfig.boardLogo (default: empty) { path: string; width?: number | string; height?: number | string } An object that allows you to specify a different logo
3. uiConfig.miscLinks (default: empty) Array< { text: string; url: string }> An array of misc link that you can add to the dashboard, such as logout link.
4. uiConfig.favIcon (default: { default: 'static/images/logo.svg', alternative: 'static/favicon-32x32.png', }) { default: string; alternative: 'string' } An object that allows you to specify the default and alternative favicons.

1const QueueMQ = require('bullmq');
2const {createBullBoard} = require('@bull-board/api');
3const {BullMQAdapter} = require('@bull-board/api/bullMQAdapter');
4
5const queueMQ = new QueueMQ();
6
7createBullBoard({
8  queues: [new BullMQAdapter(queueMQ)],
9  serverAdapter,
10  options: {
11    uiConfig: {
12      boardTitle: 'My BOARD',
13      boardLogo: {
14        path: 'https://cdn.my-domain.com/logo.png',
15        width: '100px',
16        height: 200,
17      },
18      miscLinks: [{text: 'Logout', url: '/logout'}],
19      favIcon: {
20        default: 'static/images/logo.svg',
21        alternative: 'static/favicon-32x32.png',
22      },
23    },
24  },
25});

Queue options

1. readOnlyMode (default: false) Makes the UI as read only, hides all queue & job related actions

1const Queue = require('bull')
2const QueueMQ = require('bullmq')
3const { createBullBoard } = require('@bull-board/api')
4const { BullMQAdapter } = require('@bull-board/api/bullMQAdapter')
5const { BullAdapter } = require('@bull-board/api/bullAdapter')
6
7const someQueue = new Queue()
8const queueMQ = new QueueMQ()
9
10createBullBoard({
11  queues: [
12    new BullAdapter(someQueue, { readOnlyMode: true }), // only this queue will be in read only mode
13    new BullMQAdapter(queueMQ, { readOnlyMode: true }),
14  ]
15})

2. allowRetries (default: true) When set to false the UI removes the job retry buttons for a queue. This option will be ignored if readOnlyMode is true.

1const QueueMQ = require('bullmq')
2const { createBullBoard } = require('@bull-board/api')
3const { BullMQAdapter } = require('@bull-board/api/bullMQAdapter')
4const { BullAdapter } = require('@bull-board/api/bullAdapter')
5
6const someQueue = new Queue()
7const queueMQ = new QueueMQ()
8
9createBullBoard({
10  queues: [
11    new BullAdapter(someQueue, { allowRetries: false }), // No retry buttons
12    new BullMQAdapter(queueMQ, { allowRetries: true, readOnlyMode: true }), // allowRetries will be ignored in this case in lieu of readOnlyMode
13  ]
14})

3. description (default: empty) Queue description text.

4. prefix (default: empty) Job name prefix.

5. queueAdapter.setFormatter(field: 'data' | 'returnValue' | 'name', formatter: (fieldData) => any) You can specify a formatter for 'data' | 'returnValue' | 'name' job's fields.

1const QueueMQ = require('bullmq');
2const fastRedact = require('fast-redact');
3const { createBullBoard } = require('@bull-board/api');
4const { BullMQAdapter } = require('@bull-board/api/bullMQAdapter');
5
6const redact = fastRedact({
7  paths: ['headers.cookie', 'password', 'access_token']
8})
9
10const queueMQ = new QueueMQ()
11const queueAdapter = new BullMQAdapter(queueMQ);
12queueAdapter.setFormatter('name', (job) => `#Queue1 - ${job.name}`);
13queueAdapter.setFormatter('data', (data) => redact(data));
14queueAdapter.setFormatter('returnValue', (returnValue) => redact(returnValue));
15
16createBullBoard({
17  queues: [queueAdapter]
18})

Hosting router on a sub path

If you host your express service on a different path than root (/) ie. https://<server_name>/<sub_path>/, then you can add the following code to provide the configuration to the bull-board router. In this example the sub path will be my-base-path.

1const Queue = require('bull')
2const { createBullBoard } = require('@bull-board/api')
3const { BullAdapter } = require('@bull-board/api/bullAdapter')
4const { ExpressAdapter } = require('@bull-board/express')
5
6const basePath = '/my-base-path';
7
8const someQueue = new Queue('someQueueName')
9const serverAdapter = new ExpressAdapter();
10serverAdapter.setBasePath(basePath)
11
12createBullBoard({
13  queues: [
14    new BullAdapter(someQueue),
15  ],
16  serverAdapter
17})
18
19// ... express server configuration
20
21app.use(basePath, serverAdapter.getRouter());

You will then find the bull-board UI at the following address https://<server_name>/my-base-path/queues.

Contributing

First, thank you for being interested in helping out, your time is always appreciated in every way. 💯

Remember to read the Code of Conduct so you also help maintaining a good Open source community around this project!

Here are some tips:

• Check the issues page for already opened issues (or maybe even closed ones) that might already address your question/bug/feature request.
• When opening a bug report provide as much information as you can, some things might be useful for helping debugging and understading the problem
  • Node, Redis, Bull, BullMQ, bull-board versions
  • Sample code that reproduces the problem
  • Some of your environment details
  • Framework you're using (Express, Koa, Hapi, etc).
• Feature requests are welcomed! Provide some details on why it would be helpful for you and others, explain how you're using bull-board and if possible even some screenshots if you are willing to mock something!

Developing

If you want to help us to solve the issues, be it a bug, a feature or a question, you might need to fork and clone this project.

To fork a project means you're going to have your own version of it under your own GitHub profile, you do it by clicking the "Fork" button on the top of any project's page on GitHub.

Cloning a project means downloading it to your local machine, you do it in the command line:

1git clone git@github.com:YOUR_GITHUB_USERNAME/bull-board.git

That will create a bull-board folder inside the directory you executed the command, so you need to navigate inside it:

1cd bull-board

This project requires that you have yarn installed

Also make sure you are running Redis for this project (bull-board's example connects to Redis' default port 6379).

Now, to try it out locally you can run:

1yarn && yarn build && yarn start:dev

The ui open automaticlly in the browser at http://localhost:3000/ui

Acknowledgements ❤️

• Juan for building the first version of this library

License

This project is licensed under the MIT License, so it means it's completely free to use and copy, but if you do fork this project with nice additions that we could have here, remember to send a PR 👍