@code-parth/rabbithole

v1.0.9

Published

2 months ago

RabbitHole - A beautiful, self-hosted dashboard for monitoring RabbitMQ with multi-connection support and built-in CORS proxy

Downloads

0High
0Medium
0Low

code-parth

rabbitmq dashboard monitoring amqp management realtime observability

🐰 RabbitHole

A beautiful, self-hosted dashboard for monitoring RabbitMQ with multi-connection support and built-in CORS proxy.

Features

🔄 Real-time Monitoring - Live updates of queues, connections, channels, and nodes
🌐 Multi-Connection Support - Manage multiple RabbitMQ instances from one dashboard
🔒 Built-in CORS Proxy - No need for CORS configuration on your RabbitMQ server
🔐 SSL/TLS Support - Per-connection SSL for HTTPS RabbitMQ servers, self-signed certs, and mutual TLS
📊 Topology Visualization - Interactive graph showing exchanges, queues, and bindings
🎨 Beautiful UI - Modern, responsive design with dark mode support
⚡ Fast & Lightweight - Static site with client-side routing
🛠️ Zero Configuration - Works out of the box with sensible defaults
📋 Connection Management - Enhanced setup page with batch testing, edit, delete, and health indicators
🗂️ Pre-defined Connections - Configure connections in .rabbitholerc for auto-loading

Quick Start

Run with bunx (No Installation)

bunx @code-parth/rabbithole

That's it! The dashboard will start on http://localhost:4152

Install Globally

npm install -g @code-parth/rabbithole
rabbithole

With Custom Options

# Custom port
rabbithole --port 8080

# Auto-open browser
rabbithole --open

# Enable debug logging
rabbithole --debug

# HTTPS with custom certificates
rabbithole --ssl-cert ./cert.pem --ssl-key ./key.pem

# Restrict CORS origin
rabbithole --cors-origin "https://yourdomain.com"

# Check for updates
rabbithole update

CLI Options

| Option | Alias | Description | Default | | ------------------------ | ----- | ------------------------------ | --------------- | | --port <number> | -p | Server port | 4152 | | --host <string> | | Host to bind | localhost | | --open | -o | Auto-open browser | false | | --cors-origin <string> | | CORS allowed origin | * | | --debug | -d | Enable debug logging | false | | --config <path> | -c | Config file path | .rabbitholerc | | --ssl-cert <path> | | SSL certificate path | | | --ssl-key <path> | | SSL private key path | | | --version | -v | Show version | | | --help | -h | Show help | | | update | | Check for and show new updates | |

Configuration File

Create a .rabbitholerc file in your project directory or home directory:

{
  "port": 4152,
  "host": "localhost",
  "corsOrigin": "*",
  "debug": false,
  "open": true,
  "ssl": {
    "cert": "/path/to/cert.pem",
    "key": "/path/to/key.pem"
  },
  "connections": [
    {
      "name": "Local Development",
      "url": "http://localhost:15672",
      "username": "guest",
      "password": "guest"
    }
  ]
}

Configuration Priority:

CLI arguments (highest)
.rabbitholerc in current directory
.rabbitholerc in home directory
Default values (lowest)

Pre-defining RabbitMQ Connections

You can pre-configure RabbitMQ connections in your .rabbitholerc file. These connections will be automatically loaded when the dashboard starts and appear on the setup page.

Example Configuration

Create a .rabbitholerc file:

{
  "port": 4152,
  "connections": [
    {
      "name": "Local Development",
      "url": "http://localhost:15672",
      "username": "guest",
      "password": "guest"
    },
    {
      "name": "Production (HTTPS)",
      "url": "https://prod-rabbitmq.example.com:15672",
      "username": "admin",
      "password": "your-password",
      "ssl": {
        "rejectUnauthorized": true,
        "ca": "/path/to/ca-bundle.pem"
      }
    },
    {
      "name": "Staging (Self-Signed)",
      "url": "https://staging-rabbitmq:15672",
      "username": "staging",
      "password": "staging-pass",
      "ssl": {
        "rejectUnauthorized": false
      }
    }
  ]
}

SSL Configuration

Two Types of SSL:

Top-Level SSL (ssl at root): Serves the RabbitHole dashboard over HTTPS
- Secures: Browser ↔ RabbitHole Server
- Optional: Only needed if you want HTTPS for the dashboard
Per-Connection SSL (ssl in each connection): Connects to RabbitMQ servers using HTTPS
- Secures: RabbitHole Server ↔ RabbitMQ Server
- Optional: Only needed if your RabbitMQ uses HTTPS

Per-Connection SSL Options:

rejectUnauthorized: Set to false to accept self-signed certificates (default: true)
ca: Path to custom Certificate Authority bundle
cert: Path to client certificate for mutual TLS authentication
key: Path to client private key for mutual TLS authentication

Security Note: Connection credentials and SSL settings in .rabbitholerc are stored in plain text. Only use this for:

Local development environments
Docker containers with proper file permissions
Secure, non-public networks

For production, consider using environment variables or secure secret management.

Using the Dashboard

Adding a RabbitMQ Connection

Open the dashboard in your browser
Go to Settings (gear icon in sidebar)
Click Add Connection
Fill in the connection details:
- Name: A friendly name for this connection
- URL: RabbitMQ Management API URL (e.g., http://localhost:15672)
- Username: RabbitMQ username (default: guest)
- Password: RabbitMQ password (default: guest)
Click Test Connection to verify
Click Save

Managing Multiple Connections

The dashboard supports multiple RabbitMQ connections:

Setup Page: Central hub for managing all connections
- Add, edit, and delete connections
- Test connection health (individual or batch test all)
- Connect to any saved connection to start monitoring
Switch Connections: Use the dropdown in the sidebar or return to setup page
Storage: Connections are stored in your browser's local storage
Pre-defined Connections: Configure connections in .rabbitholerc for auto-loading
Each connection is independent and isolated

Dashboard Features

Overview

Real-time metrics: messages, message rates, connections, channels
System resource usage
Cluster information

Queues

List all queues with real-time stats
Filter and search queues
View message rates, consumers, and memory usage

Exchanges

View all exchanges and their types
See bindings and routing

Connections & Channels

Monitor active connections
View channel details and message rates

Nodes

Cluster node status
Resource usage (CPU, memory, disk, file descriptors)
Erlang process information

Topology

Interactive graph visualization
Shows exchanges, queues, and bindings
Drag to rearrange, zoom and pan
Real-time updates

How It Works

RabbitHole uses a built-in proxy server to avoid CORS issues:

Browser → RabbitHole Server → RabbitMQ Management API

Your browser connects to the RabbitHole server (localhost:4152)
When you make a request, it goes to /api/proxy/*
The proxy server forwards it to your RabbitMQ instance
Response comes back with CORS headers added

No CORS configuration needed on RabbitMQ!

API Endpoints

The RabbitHole server exposes:

Health Check

GET /health

Response:
{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 12345,
  "proxy": "enabled"
}

Proxy Endpoint

GET /api/proxy/<rabbitmq-endpoint>

Headers:
  X-RabbitMQ-URL: http://localhost:15672
  X-RabbitMQ-Auth: base64(username:password)

Development

Building from Source

# Clone the repository
git clone https://github.com/code-parth/rabbithole.git
cd rabbithole

# Install dependencies
bun install

# Build the static site
bun run build

# Run the server locally
bun run start

# Or with debug mode
bun run dev:server

Project Structure

@code-parth/rabbithole/
├── bin/
│   └── cli.js              # CLI entry point
├── server/
│   ├── index.js            # HTTP/HTTPS server + proxy
│   ├── logger.js           # Logging utilities
│   └── config.js           # Configuration loader
├── app/                    # Next.js pages
├── components/             # React components
├── lib/                    # Utilities and API clients
├── out/                    # Built static files
└── package.json

Security Considerations

Credentials

Credentials are never stored on the server
All connection details are stored in browser localStorage
Each user manages their own connections

CORS Proxy

The proxy only forwards requests with proper headers
You can restrict CORS origin with --cors-origin
Proxy logs can be enabled with --debug flag

HTTPS

Use --ssl-cert and --ssl-key for HTTPS
Recommended for production deployments

Best Practices

Don't expose to public internet - Run on localhost or private network
Use HTTPS in production
Restrict CORS origin if exposing to specific domains
Use strong RabbitMQ credentials
Enable RabbitMQ authentication - Never use default credentials in production

Troubleshooting

Port Already in Use

Error: Port 4152 is already in use

Solution: Use a different port

rabbithole --port 8080

Cannot Connect to RabbitMQ

Failed to connect to RabbitMQ

Check:

RabbitMQ is running
Management plugin is enabled: rabbitmq-plugins enable rabbitmq_management
Correct URL (default: http://localhost:15672)
Valid credentials

Debug Mode

Enable debug mode to see detailed logs:

rabbithole --debug

This shows:

Proxy requests and responses
Configuration loading
File serving
Error details

Comparison with RabbitMQ Management UI

| Feature | RabbitHole | RabbitMQ UI | | ------------------------ | ---------- | ------------------ | | Multi-connection support | ✅ | ❌ | | No CORS issues | ✅ | ⚠️ Requires config | | Modern UI | ✅ | ⏺️ Basic | | Dark mode | ✅ | ❌ | | Real-time topology | ✅ | ⏺️ Static | | Self-hosted | ✅ | ✅ | | Install required | ❌ (node) | ✅ |

Requirements

Node.js: 24+ or Bun
RabbitMQ: 3.12+ with Management plugin enabled
Browser: Modern browser with ES2020+ support

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: [email protected]

Acknowledgments

Built with Next.js
UI components from shadcn/ui
Topology visualization with ReactFlow
Icons from Lucide

Made with ❤️ for the RabbitMQ community