bull-arena

Arena

An intuitive Web GUI for Bee Queue and Bull. Built on Express so you can run Arena standalone, or mounted in another app as middleware.

For a quick introduction to the motivations for creating Arena, read Interactively monitoring Bull, a Redis-backed job queue for Node.

Screenshots

Features

• Check the health of a queue and its jobs at a glance
• Paginate and filter jobs by their state
• View details and stacktraces of jobs with permalinks
• Restart and retry jobs with one click

Usage

Arena accepts a the following options:

const Arena = require('bull-arena');

// Mandatory import of queue library.
const Bee = require('bee-queue');

Arena({
  // All queue libraries used must be explicitly imported and included.
  Bee,

  // Provide a `Bull` option when using bull, similar to the `Bee` option above.

  queues: [
    {
      // Required for each queue definition.
      name: 'name_of_my_queue',

      // User-readable display name for the host. Required.
      hostId: 'Queue Server 1',

      // Queue type (Bull or Bee - default Bull).
      type: 'bee',

      // Queue key prefix. Defaults to "bq" for Bee and "bull" for Bull.
      prefix: 'foo',
    },
  ],

  // Optionally include your own stylesheet
  customCssPath: 'https://example.com/custom-arena-styles.css',
});

The required name and hostId in each queue object have to be present in each queue object. Additional keys can be present in them, to configure the redis client itself.

The three ways in which you can configure the client are:

1. port/host

// In a queue object.
{
  // Hostname or IP. Required.
  "host": "127.0.0.1",

  // Bound port. Optional, default: 6379.
  "port": 6379,

  // Optional, to issue a redis AUTH command.
  "password": "hello",

  // Optional; default 0. Most of the time, you'll leave this absent.
  "db": 1
}

2. URL

You can also provide a url field instead of host, port, db and password.

{
  "url": "[redis:]//[[user][:password@]][host][:port][/db-number][?db=db-number[&password=bar[&option=value]]]"
}

3. Redis client options

Arena is compatible with both Bee and Bull. If you need to pass some specific configuration options directly to the redis client library your queue uses, you can also do so.

Bee uses node redis client, Bull uses ioredis client. These clients expect different configurations options.

{
  "redis": {}
}

For Bee, the redis key will be directly passed to redis.createClient, as explained here.

For Bull, the redis key will be directly passed to ioredis, as explained here. To use this to connect to a Sentinel cluster, see here.

Custom configuration file

To specify a custom configuration file location, see Running Arena as a node module.

Note that if you happen to use Amazon Web Services' ElastiCache as your Redis host, check out http://mixmax.com/blog/bull-queue-aws-autodiscovery

Running Arena as a node module

See the Docker image section or the docker-arena repository for information about running this standalone.

Note that because Arena is implemented using async/await, Arena only currently supports Node >=7.6.

Using Arena as a node module has potential benefits:

• Arena can be configured to use any method of server/queue configuration desired
  • for example, fetching available redis queues from an AWS instance on server start
  • or even just plain old reading from environment variables
• Arena can be mounted in other express apps as middleware

Usage:

In project folder:

$ npm install bull-arena

In router.js:

const Arena = require('bull-arena');

const express = require('express');
const router = express.Router();

const arena = Arena({
  // Include a reference to the bee-queue or bull libraries, depending on the library being used.

  queues: [
    {
      // First queue configuration
    },
    {
      // Second queue configuration
    },
    {
      // And so on...
    },
  ],
});

router.use('/', arena);

Arena takes two arguments. The first, config, is a plain object containing the queue configuration. The second, listenOpts, is an object that can contain the following optional parameters:

• port - specify custom port to listen on (default: 4567)
• host - specify custom ip to listen on (default: '0.0.0.0')
• basePath - specify custom path to mount server on (default: '/')
• disableListen - don't let the server listen (useful when mounting Arena as a sub-app of another Express app) (default: false)
• useCdn - set false to use the bundled js and css files (default: true)
• customCssPath - an URL to an external stylesheet (default: null)

Example config (for bull)

import Arena from 'bull-arena';
import Bull from 'bull';

const arenaConfig = Arena({
  Bull,
  queues: [
    {
      type: 'bull',

      // Name of the bull queue, this name must match up exactly with what you've defined in bull.
      name: "Notification_Emailer",

      // Hostname or queue prefix, you can put whatever you want.
      hostId: "MyAwesomeQueues",

      // Redis auth.
      redis: {
        port: /* Your redis port */,
        host: /* Your redis host domain*/,
        password: /* Your redis password */,
      },
    },
  ],
},
{
  // Make the arena dashboard become available at {my-site.com}/arena.
  basePath: '/arena',

  // Let express handle the listening.
  disableListen: true,

  // Optionally include your own stylesheet
  customCssPath: 'https://example.com/custom-arena-styles.css'
});

// Make arena's resources (js/css deps) available at the base app route
app.use('/', arenaConfig);

(Credit to tim-soft for the example config.)

Example config (for bullmq)

import Arena from 'bull-arena';
import { Queue } from "bullmq";

const arenaConfig = Arena({
  BullMQ: Queue,
  queues: [
    {
      type: 'bullmq',

      // Name of the bullmq queue, this name must match up exactly with what you've defined in bullmq.
      name: "testQueue",

      // Hostname or queue prefix, you can put whatever you want.
      hostId: "worker",

      // Redis auth.
      redis: {
        port: /* Your redis port */,
        host: /* Your redis host domain*/,
        password: /* Your redis password */,
      },
    },
  ],
},
{
  // Make the arena dashboard become available at {my-site.com}/arena.
  basePath: '/arena',

  // Let express handle the listening.
  disableListen: true,

  // Optionally include your own stylesheet
  customCssPath: 'https://example.com/custom-arena-styles.css'
});

// Make arena's resources (js/css deps) available at the base app route
app.use('/', arenaConfig);

Bee Queue support

Arena is dual-compatible with Bull 3.x and Bee-Queue 1.x. To add a Bee queue to the Arena dashboard, include the type: 'bee' property with an individual queue's configuration object.

BullMQ Queue support

Arena has added preliminary support for BullMQ post 3.4.x version. To add a BullMQ queue to the Arena dashboard, include the type: 'bullmq' property with an individual queue's configuration object.

Docker image

You can docker pull Arena from Docker Hub.

Please see the docker-arena repository for details.

Contributing

See contributing guidelines and an example.

License

The MIT License.

Changelog

3.16.0 (2021-03-31)

Features

• add optional custom css (3f68dc1)