# 🐰 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)

```bash
bunx @code-parth/rabbithole
```

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

### Install Globally

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

### With Custom Options

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

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

### Example Configuration

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
      }
    }
  ]
}
```

### SSL Configuration

**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

### Adding a RabbitMQ Connection

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**

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

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:

### Health Check

```bash
GET /health

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

### Proxy Endpoint

```bash
GET /api/proxy/<rabbitmq-endpoint>

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

## Development

### Building from Source

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

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

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

### Port Already in Use

```bash
Error: Port 4152 is already in use
```

**Solution:** Use a different port

```bash
rabbithole --port 8080
```

### Cannot Connect to RabbitMQ

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

### Debug Mode

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](https://github.com/code-parth/rabbithole/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/code-parth/rabbithole/discussions)
- 📧 **Email**: im.code.parth@gmail.com

## Acknowledgments

- Built with [Next.js](https://nextjs.org/)
- UI components from [shadcn/ui](https://ui.shadcn.com/)
- Topology visualization with [ReactFlow](https://reactflow.dev/)
- Icons from [Lucide](https://lucide.dev/)

---

**Made with ❤️ for the RabbitMQ community**