🦦 OtterMQ

OtterMQ is a high-performance message broker written in Go, inspired by RabbitMQ. It aims to provide a reliable, scalable, and easy-to-use messaging solution for distributed systems. OtterMQ is being developed with the goal of full compliance with the AMQP 0.9.1 protocol, ensuring compatibility with existing tools and workflows. It also features a modern management UI built with SvelteKit.

OtterMq already supports basic interoperability with RabbitMQ clients, including:

• .NET RabbitMQ.Client
• github.com/rabbitmq/amqp091-go

🐾 About the Name

The name "OtterMQ" comes from my son's nickname and is a way to honor him. He brings joy and inspiration to my life, and this project is a reflection of that. And, of course, it is also a pun on RabbitMQ.

✨ Features

• AMQP-style Message Queuing
• Exchanges and Bindings (Direct, Fanout, Topic)
• Dead Letter Exchange (DLX) - RabbitMQ-compatible error handling
• Quality of Service (QoS) with prefetch limits
• Transactions (TX class) - Atomic commit/rollback
• Channel Flow Control for backpressure management
• Message TTL (per-message and per-queue)
• Queue Length Limits with drop-head strategy
• Priority Queues (0–255 range)
• Virtual Hosts with multi-tenant isolation
• Pluggable Persistence Layer (JSON files, Memento WAL planned)
• User & Permission Management (SQLite + JWT)
• Internal Metrics (ring buffers, per-queue/channel/exchange rates)
• Prometheus /metrics exporter
• Management Interface (SvelteKit) with real-time charts
• ottermqadmin CLI tool (Cobra-based)
• Docker Support via docker-compose
• RabbitMQ Client Compatibility

⚙️ Installation

git clone https://github.com/ottermq/ottermq.git
cd ottermq
make build-all && make install

🚀 Usage

Development Mode (UI runs separately)

# Run the broker:
make run-dev

# In another terminal, run the UI (http://localhost:5173, proxies /api to :3000):
cd web/ui
npm install
npm run dev
# If the broker's web API listens elsewhere:
# OTTERMQ_API_URL=http://localhost:3100 npm run dev

Production Mode (Integrated UI)

# Build everything (UI + broker + CLI):
make build-all

# Run the integrated server:
make run

Available Commands

make build           # Build broker only
make build-admin     # Build ottermqadmin only
make build-all       # Build UI, broker, and CLI
make install-admin   # Install ottermqadmin into GOPATH/bin
make run            # Run broker (with embedded UI if built)
make test-cli       # Run focused CLI tests
make run-dev        # Run broker in development mode
make test           # Run all tests
make lint           # Run code quality checks
make clean          # Clean all build artifacts
make docs           # Generate API documentation

OtterMq uses:

• Port 5672 for the AMQP broker

• Port 3000 for the management UI

🖥️ CLI Admin Tool

OtterMQ now includes ottermqadmin, a Cobra-based admin CLI that talks to the same HTTP management API used by the web UI.

Build and Install

make build-admin
make install-admin

Or run it directly from the repo:

go run ./cmd/ottermqadmin --help

Quick Start

go run ./cmd/ottermqadmin overview --username guest --password guest
go run ./cmd/ottermqadmin queues list --username guest --password guest
go run ./cmd/ottermqadmin exchanges list --username guest --password guest
go run ./cmd/ottermqadmin bindings list --username guest --password guest

Example Commands

go run ./cmd/ottermqadmin queues create / jobs --durable --username guest --password guest
go run ./cmd/ottermqadmin publish / "" --routing-key jobs --body "hello" --username guest --password guest
go run ./cmd/ottermqadmin queues get-messages / jobs --count 5 --ack-mode ack --username guest --password guest
go run ./cmd/ottermqadmin connections list --username guest --password guest
go run ./cmd/ottermqadmin channels list --username guest --password guest
go run ./cmd/ottermqadmin consumers list --username guest --password guest

Notes:

• ottermqadmin targets the management API, so the OtterMQ web API must be enabled and reachable.
• The default management URL is http://localhost:3000.
• Use "" or "(AMQP default)" as the exchange argument when publishing to the AMQP default exchange.
• Add --json to any command for machine-readable output.

⚙️ Configuration

OtterMQ can be configured using environment variables or a .env file. Environment variables take precedence over .env file settings, which in turn take precedence over default values.

Configuration Options

Copy .env.example to .env and customize as needed:

cp .env.example .env

Available configuration options:

Environment Variable	Default	Description
OTTERMQ_BROKER_PORT	5672	AMQP broker port
OTTERMQ_BROKER_HOST	``	Broker bind address (empty = all interfaces)
OTTERMQ_USERNAME	guest	Bootstrap admin user, created on start if it doesn't exist (the password of an existing user is not changed)
OTTERMQ_PASSWORD	guest	Password of the bootstrap admin user
OTTERMQ_LOOPBACK_USERS	guest	Comma-separated users that may only connect from localhost (AMQP and web API); set it empty to restrict nobody. Behind a reverse proxy or TLS terminator on the same host, every client looks local
OTTERMQ_HEARTBEAT_INTERVAL	60	Heartbeat interval in seconds
OTTERMQ_CHANNEL_MAX	2048	Maximum number of channels
OTTERMQ_FRAME_MAX	131072	Maximum frame size in bytes
OTTERMQ_SSL	false	Enable SSL/TLS
OTTERMQ_QUEUE_BUFFER_SIZE	100000	Queue message buffer size
OTTERMQ_WEB_PORT	3000	Web management UI port
OTTERMQ_JWT_SECRET	generated	Key that signs web API tokens, at least 32 bytes. Unset, a random key is generated on first start and kept in <data dir>/jwt.key
OTTERMQ_INSECURE_DEV	false	Accept a weak OTTERMQ_JWT_SECRET (such as secret), for local development only

Example Configuration

Create a .env file in the project root:

OTTERMQ_BROKER_PORT=5672
OTTERMQ_WEB_PORT=8080
OTTERMQ_USERNAME=admin
OTTERMQ_PASSWORD=secure_password
OTTERMQ_QUEUE_BUFFER_SIZE=200000
# Optional; generated in the data dir if unset. At least 32 bytes, e.g. `openssl rand -hex 32`.
# OTTERMQ_JWT_SECRET=

Or use environment variables directly:

export OTTERMQ_BROKER_PORT=15672
export OTTERMQ_WEB_PORT=8080
ottermq

🐳 Docker

Images are published to the GitHub Container Registry: latest from main (the latest release), a version tag (e.g. 0.20.0 and 0.20) for each v* release tag, and edge from dev, which has every merged change but isn't released yet.

docker run -p 5672:5672 -p 3000:3000 \
  -e OTTERMQ_USERNAME=admin -e OTTERMQ_PASSWORD='<choose a password>' \
  ghcr.io/ottermq/ottermq:latest

Set OTTERMQ_USERNAME and OTTERMQ_PASSWORD: the default guest user may only connect from localhost, and connections from the host reach the container from the Docker bridge, not from loopback, so guest is refused there. The broker creates the configured user as an administrator on start if it doesn't exist yet, also on an existing data dir; it doesn't change the password of an existing user.

To build and run from source instead:

docker compose up --build

This uses packaging/docker/Dockerfile and docker-compose.yml. Uncomment and set OTTERMQ_USERNAME/OTTERMQ_PASSWORD in docker.env first, for the same reason.

🚧 Development Status

OtterMq is under active development. All core AMQP 0.9.1 features, RabbitMQ extensions, observability, and the management API are complete. Active work is on finishing the ottermqadmin CLI tool.

Remaining CLI commands: users and permissions (the HTTP API for both already exists).

Longer-term planned work:

• Memento WAL persistence engine (append-only transaction log)
• OpenTelemetry distributed tracing (Phase 3 observability)
• Clustering / Federation (lowest priority)

All core AMQP 0.9.1 message operations are now fully implemented, including:

• Push-based consumption (basic.consume/basic.deliver)
• Pull-based consumption (basic.get)
• Message acknowledgments (basic.ack, basic.nack, basic.reject)
• Quality of Service controls (basic.qos)
• Message recovery (basic.recover, basic.recover-async)
• Flow control (channel.flow for backpressure management)
• Transactions (tx.select, tx.commit, tx.rollback)

RabbitMQ Extensions (for compatibility):

• Dead Letter Exchanges (DLX) with x-death tracking
• Message TTL and Expiration with per-message and per-queue support
• Queue length limits with dead lettering
• Priority queues
• Consumer cancel notification (consumer_cancel_notify) when a queue is deleted

Basic compatibility with RabbitMQ clients is functional and tested. See ROADMAP.md for detailed development plans.

📚 API Documentation

OtterMq provides a built-in Swagger UI for exploring and testing the API.

Access it at: http://<server-address>/docs

If you make changes to the API and need to regenerate the documentation, run:

make docs

This will update the Swagger spec and refresh the documentation served at /docs.

Management API Examples

OtterMQ provides a comprehensive REST API for managing queues, exchanges, bindings, and monitoring broker state. The API supports all broker features including TTL, DLX, QLL, and QoS.

Queue Management

Create a queue with TTL and DLX:

curl -X POST http://localhost:3000/api/queues/my-vhost/my-queue \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "durable": true,
    "auto_delete": false,
    "arguments": {
      "x-message-ttl": 60000,
      "x-dead-letter-exchange": "dlx-exchange",
      "x-max-length": 10000
    }
  }'

List all queues:

curl http://localhost:3000/api/queues \
  -H "Authorization: Bearer <token>"

Get queue details:

curl http://localhost:3000/api/queues/my-vhost/my-queue \
  -H "Authorization: Bearer <token>"

Exchange Management

Create a topic exchange:

curl -X POST http://localhost:3000/api/exchanges/my-vhost/my-exchange \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "topic",
    "durable": true,
    "auto_delete": false,
    "internal": false
  }'

Binding Management

Bind a queue to an exchange:

curl -X POST http://localhost:3000/api/bindings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "vhost": "my-vhost",
    "source": "my-exchange",
    "destination": "my-queue",
    "routing_key": "events.#"
  }'

Message Operations

Publish a message:

curl -X POST http://localhost:3000/api/exchanges/my-vhost/my-exchange/publish \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "events.user.created",
    "payload": "Hello, OtterMQ!",
    "content_type": "text/plain",
    "delivery_mode": 2,
    "priority": 5
  }'

Get messages from a queue:

curl -X POST http://localhost:3000/api/queues/my-vhost/my-queue/get \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message_count": 10,
    "ack_mode": "ack"
  }'

Monitoring & Statistics

Get broker overview:

curl http://localhost:3000/api/overview \
  -H "Authorization: Bearer <token>"

List active consumers:

curl http://localhost:3000/api/consumers \
  -H "Authorization: Bearer <token>"

List active connections:

curl http://localhost:3000/api/connections \
  -H "Authorization: Bearer <token>"

List channels:

curl http://localhost:3000/api/channels \
  -H "Authorization: Bearer <token>"

For complete API reference, see the Swagger documentation at /docs.

📄 Project Pages (Status & AMQP Compliance)

We publish a live status site that tracks protocol/class/method support, planned work, and compatibility notes—similar to RabbitMQ’s specification page.

• URL: https://ottermq.github.io/ottermq/
• Source location: the site content lives under the /docs folder
• Deployment branch: pages (GitHub Pages is configured to build from pages with /docs as the site root)

Notes:

• The GitHub Pages site is separate from the Swagger UI served at /docs by the running server. The Pages site documents status and specs; the Swagger UI documents the REST API.
• When adding or changing AMQP features (classes/methods), please also update the Pages content under /docs and merge it into the pages branch so the site stays current.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md to get set up. Good places to start:

• Good first issues: small, well-described fixes.
• The production readiness roadmap: the big picture, with a map of the codebase.

⚖️ License

OtterMQ is released under the MIT License. See License for more information.

💬 Contact

For questions, suggestions, or issues, please open an issue in the GitHub repository.