RabbitHole - A beautiful, self-hosted dashboard for monitoring RabbitMQ with multi-connection support and built-in CORS proxy
npm install @code-parth/rabbitholeA beautiful, self-hosted dashboard for monitoring RabbitMQ with multi-connection support and built-in CORS proxy.
- π 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
``bash`
bunx @code-parth/rabbithole
That's it! The dashboard will start on http://localhost:4152
`bash`
npm install -g @code-parth/rabbithole
rabbithole
`bashCustom port
rabbithole --port 8080
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 dashboard2. 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 HTTPSPer-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 authenticationSecurity 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 addedNo CORS configuration needed on RabbitMQ!
API Endpoints
The RabbitHole server exposes:
$3
`bash
GET /healthResponse:
{
"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 rabbitholeInstall dependencies
bun installBuild the static site
bun run buildRun the server locally
bun run startOr 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`)- π Issues: GitHub Issues
- π¬ Discussions: GitHub Discussions
- π§ Email: im.code.parth@gmail.com
- Built with Next.js
- UI components from shadcn/ui
- Topology visualization with ReactFlow
- Icons from Lucide
---
Made with β€οΈ for the RabbitMQ community