emirce/bullstudio repository overview

⁠bullstudio

A lightweight, beautiful queue management dashboard for Bull⁠ and BullMQ⁠.
Monitor your queues, inspect jobs, visualize flows, and manage your Redis-backed job infrastructure.

⁠Quick Start

npx bullstudio -r <redis_url>

That's it! The dashboard opens automatically at http://localhost:4000⁠. No code integration needed. Bullstudio automatically detects your provider (Bull or BullMq).

⁠Installation

⁠Run directly with npx (recommended)

npx bullstudio

⁠Or install globally

npm install -g bullstudio
bullstudio

⁠Docker

⁠Quick Start

docker run -d \
  -p 4000:4000 \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  emirce/bullstudio

The dashboard is available at http://localhost:4000⁠.

⁠Connect to Redis

# Local Redis (Docker for Mac/Windows)
docker run -d -p 4000:4000 -e REDIS_URL=redis://host.docker.internal:6379 emirce/bullstudio

# Remote Redis
docker run -d -p 4000:4000 -e REDIS_URL=redis://myhost.com:6379 emirce/bullstudio

# Redis with authentication
docker run -d -p 4000:4000 -e REDIS_URL=redis://:[email protected]:6379 emirce/bullstudio

⁠Custom Port

docker run -d -p 8080:8080 -e PORT=8080 -e REDIS_URL=redis://host.docker.internal:6379 emirce/bullstudio

⁠With Authentication

docker run -d \
  -p 4000:4000 \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -e BULLSTUDIO_PASSWORD=secret123 \
  emirce/bullstudio

⁠Docker Compose

services:
  bullstudio:
    image: emirce/bullstudio
    ports:
      - "4000:4000"
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

docker compose up -d

⁠Environment Variables

⁠Available Tags

⁠Supported Platforms

• linux/amd64
• linux/arm64

⁠Usage

bullstudio [options]

⁠Options

⁠Examples

⁠Connect to local Redis

bullstudio

⁠Connect to a remote Redis server

bullstudio -r redis://myhost.com:6379

⁠Connect with authentication

bullstudio -r redis://:[email protected]:6379

⁠Use a custom port

bullstudio -p 5000

⁠Connect to Redis with username and password

bullstudio -r redis://username:[email protected]:6379

⁠Run without opening browser

bullstudio --no-open

⁠Combine options

bullstudio -r redis://:[email protected]:6379 -p 8080 --no-open

⁠Protect dashboard with password

bullstudio --password secret123

The browser will prompt for credentials:

• Username: bullstudio
• Password: secret123

⁠Authentication

You can protect the dashboard with HTTP Basic Auth in production mode only. Development mode (--dev) does not require authentication.

⁠Usage

# Using CLI flag
bullstudio --password secret123

## Custom username
bullstudio --username bullstudio_admin --password secret123

# Using environment variable
BULLSTUDIO_PASSWORD=secret123 bullstudio

# Docker with authentication
docker run -e BULLSTUDIO_PASSWORD=secret123 -p 4000:4000 emirce/bullstudio

⁠Authentication Details

• Username: bullstudio (fixed, cannot be changed)
• Password: Set via --password flag or BULLSTUDIO_PASSWORD environment variable
• Mode: Only applies to production mode (default). Development mode (--dev) bypasses authentication
• Method: HTTP Basic Auth (browser will show native login dialog)

⁠Health Check

The /health endpoint is publicly accessible without authentication:

curl http://localhost:4000/health
# {"status":"ok","timestamp":"2026-02-08T21:58:47.508Z","redis":"configured"}

⁠Features

⁠Overview Dashboard

Get a bird's-eye view of your queue health with real-time metrics, throughput charts, and failure tracking.

⁠Jobs Browser

• Browse all jobs across queues
• Filter by status (waiting, active, completed, failed, delayed)
• Search jobs by name, ID, or data
• Retry failed jobs with one click
• View detailed job data, return values, and stack traces

⁠Flows Visualization

• Visualize parent-child job relationships as interactive graphs
• See the live state of each job in the flow
• Click nodes to navigate to job details
• Auto-refresh while flows are active

⁠Requirements

• Node.js 18 or higher
• Redis server running (local or remote)
• BullMQ queues in your Redis instance

⁠Environment Variables

You can also configure bullstudio using environment variables:

export REDIS_URL=redis://localhost:6379
export PORT=4000
export BULLSTUDIO_USERNAME=bullstudio
export BULLSTUDIO_PASSWORD=secret123
bullstudio

Command-line options take precedence over environment variables.

⁠Troubleshooting

⁠"Connection refused" error

Make sure Redis is running:

# Check if Redis is running
redis-cli ping

# Start Redis (macOS with Homebrew)
brew services start redis

# Start Redis (Docker)
docker run -d -p 6379:6379 redis

⁠No queues showing up

bullstudio discovers queues by scanning for BullMQ metadata keys in Redis. Make sure:

1. Your application has created at least one queue
2. You're connecting to the correct Redis instance
3. If using a prefix other than bull, your queues use the default prefix

⁠Port already in use

Use a different port:

bullstudio -p 5000

⁠License

MIT

Made with love for the BullMQ community