🐰 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

$3

``bash
bunx @code-parth/rabbithole
`

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

$3

`bash
npm install -g @code-parth/rabbithole
rabbithole
`

$3

`bash


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 | -p | Server port | 4152 |
| --host | | Host to bind | localhost |
| --open | -o | Auto-open browser | false |
| --cors-origin | | CORS allowed origin | * |
| --debug | -d | Enable debug logging | false |
| --config | -c | Config file path | .rabbitholerc |
| --ssl-cert | | SSL certificate path | |
| --ssl-key | | 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:

`json
{
"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:

1. CLI arguments (highest)
2. .rabbitholerc in current directory
3. .rabbitholerc in home directory
4. 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.

$3

Create a .rabbitholerc file:

`json
{
"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
}
}
]
}
`

$3

Two Types of SSL:

1. 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

2. 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

$3

1. Open the dashboard in your browser
2. Go to Settings (gear icon in sidebar)
3. Click Add Connection
4. 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)
5. Click Test Connection to verify
6. Click Save

$3

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

$3

#### 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
`

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

No CORS configuration needed on RabbitMQ!

API Endpoints

The RabbitHole server exposes:

$3

`bash
GET /health

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

$3

`bash
GET /api/proxy/

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

Development

$3

`bash


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
`

$3

`
@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

$3

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

$3

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

$3

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

$3

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

Troubleshooting

$3

`bash
Error: Port 4152 is already in use
`

Solution: Use a different port

`bash
rabbithole --port 8080
`

$3

`bash
Failed to connect to RabbitMQ
`

Check:

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

$3

Enable debug mode to see detailed logs:

`bash
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.

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

Support

- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: im.code.parth@gmail.com

Acknowledgments

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

---

Made with ❤️ for the RabbitMQ community