Docker Compose Reference: RabbitMQ

TL;DR

• Bottom line: Use the official rabbitmq:4.0-management-alpine image with a named volume, health check, and custom credentials to run a production-ready RabbitMQ message broker in Docker Compose.
• Key tool/command: docker compose up -d with rabbitmq:4.0-management-alpine image, ports 5672:5672 and 15672:15672
• Watch out for: Data loss from missing volume mounts -- RabbitMQ stores all data in /var/lib/rabbitmq which is ephemeral without a named volume.
• Works with: Docker Compose v2+, Docker Engine 20.10+, RabbitMQ 3.12/3.13/4.0, AMQP 0-9-1, AMQP 1.0.

Constraints

• ALWAYS set RABBITMQ_ERLANG_COOKIE to the same value on all cluster nodes -- mismatched cookies silently prevent clustering
• ALWAYS mount a named volume at /var/lib/rabbitmq -- without it all queues, exchanges, and messages are lost on container restart
• NEVER expose port 15672 (management UI) to the public internet without authentication and TLS
• Set RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS or use rabbitmq.conf -- never run production with default guest/guest credentials
• Pin image tags to specific versions (e.g., rabbitmq:4.0-management) -- never use :latest in production
• For RabbitMQ 4.0+, prefer quorum queues over classic mirrored queues -- classic mirroring was removed in 4.0

Quick Reference

Service Configuration

Key Ports

Environment Variables

Decision Tree

START: What RabbitMQ setup do you need?
├── Single node for development?
│   ├── YES → Use basic docker-compose.yml (Step 1)
│   └── NO ↓
├── Single node for production?
│   ├── YES → Add health check + custom config + TLS (Steps 1-3)
│   └── NO ↓
├── Multi-node cluster?
│   ├── YES → 3-node cluster with quorum queues (Step 4)
│   └── NO ↓
├── Need monitoring?
│   ├── YES → Enable rabbitmq_prometheus plugin + Grafana (Step 5)
│   └── NO ↓
└── DEFAULT → Start with single node + management UI (Step 1)

Step-by-Step Guide

1. Create a basic docker-compose.yml

Start with a single RabbitMQ node with the management plugin enabled. The -management image variant includes the web UI. [src1]

# docker-compose.yml -- RabbitMQ with management UI
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    container_name: rabbitmq
    hostname: rabbitmq
    ports:
      - "5672:5672"
      - "15672:15672"
    environment:
      RABBITMQ_DEFAULT_USER: myuser
      RABBITMQ_DEFAULT_PASS: mypassword
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "check_port_connectivity"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 40s
    restart: unless-stopped

volumes:
  rabbitmq_data:

Verify: docker compose up -d && docker compose ps -- status should show healthy. Open http://localhost:15672.

2. Add custom configuration files

Mount rabbitmq.conf for memory limits, disk thresholds, and logging. [src2]

# rabbitmq.conf -- production configuration (sysctl format)
listeners.tcp.default = 5672
default_user = $(RABBITMQ_DEFAULT_USER)
default_pass = $(RABBITMQ_DEFAULT_PASS)
vm_memory_high_watermark.relative = 0.6
disk_free_limit.absolute = 1GB
log.console = true
log.console.level = info
loopback_users = none
management.tcp.port = 15672

# enabled_plugins
[rabbitmq_management,rabbitmq_prometheus].

Verify: docker compose exec rabbitmq rabbitmq-diagnostics environment | grep vm_memory -- should show 0.6.

3. Configure TLS encryption

Enable TLS on AMQP and management ports for production. [src2]

# rabbitmq.conf -- TLS section
listeners.ssl.default = 5671
ssl_options.cacertfile = /etc/rabbitmq/certs/ca.pem
ssl_options.certfile = /etc/rabbitmq/certs/server.pem
ssl_options.keyfile = /etc/rabbitmq/certs/server-key.pem
ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = false
management.ssl.port = 15671
management.ssl.cacertfile = /etc/rabbitmq/certs/ca.pem
management.ssl.certfile = /etc/rabbitmq/certs/server.pem
management.ssl.keyfile = /etc/rabbitmq/certs/server-key.pem

Verify: openssl s_client -connect localhost:5671 -- should complete TLS handshake.

4. Set up a 3-node cluster

Deploy a RabbitMQ cluster with quorum queues. All nodes must share the same Erlang cookie. [src3]

Full script: docker-compose-cluster.yml (72 lines)

Verify: docker compose exec rabbitmq1 rabbitmqctl cluster_status -- should show all 3 nodes.

5. Add Prometheus monitoring

Enable the rabbitmq_prometheus plugin to expose metrics. [src2]

[rabbitmq_management,rabbitmq_prometheus].

Verify: curl http://localhost:15692/metrics -- should return Prometheus-format metrics.

Code Examples

Python: Producer and Consumer with pika

Full script: python-pika-producer-consumer.py (58 lines)

# Input:  RabbitMQ at localhost:5672
# Output: Messages sent to and received from "task_queue"
import pika  # pika==1.3.2

credentials = pika.PlainCredentials('myuser', 'mypassword')
params = pika.ConnectionParameters(
    host='localhost', port=5672,
    credentials=credentials,
    heartbeat=600,
    blocked_connection_timeout=300,
)
conn = pika.BlockingConnection(params)
ch = conn.channel()
ch.queue_declare(queue='task_queue', durable=True,
                 arguments={'x-queue-type': 'quorum'})

Node.js: Producer and Consumer with amqplib

Full script: nodejs-amqplib-producer-consumer.js (56 lines)

// Input:  RabbitMQ at localhost:5672
// Output: Messages sent to and received from "task_queue"
const amqplib = require('amqplib');  // [email protected]

const RABBITMQ_URL = 'amqp://myuser:mypassword@localhost:5672';
const conn = await amqplib.connect(RABBITMQ_URL);
const ch = await conn.createChannel();
await ch.assertQueue('task_queue', {
  durable: true,
  arguments: { 'x-queue-type': 'quorum' },
});

Docker Compose: Full Production Stack

Full script: docker-compose-production.yml (45 lines)

# Input:  rabbitmq.conf + enabled_plugins in same directory
# Output: Production-ready RabbitMQ with monitoring
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    hostname: rabbitmq
    ports:
      - "5672:5672"
      - "15672:15672"
      - "15692:15692"
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
      - ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro
      - ./enabled_plugins:/etc/rabbitmq/enabled_plugins:ro

Shell: RabbitMQ Management CLI Operations

# List all queues with message counts
docker compose exec rabbitmq rabbitmqctl list_queues name messages consumers type

# Declare a durable quorum queue
docker compose exec rabbitmq rabbitmqadmin declare queue \
  name=orders durable=true \
  arguments='{"x-queue-type":"quorum"}' \
  --username=myuser --password=mypassword

# Export all definitions (backup)
docker compose exec rabbitmq rabbitmqctl export_definitions /tmp/definitions.json

Anti-Patterns

Wrong: No volume mount for data persistence

# BAD -- all data lost when container restarts
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    ports:
      - "5672:5672"
    # No volumes defined

Correct: Named volume for data persistence

# GOOD -- data persists across container restarts
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    hostname: rabbitmq
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
volumes:
  rabbitmq_data:

Wrong: Default guest credentials in production

# BAD -- guest/guest accessible from any host
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    ports:
      - "15672:15672"
    # No RABBITMQ_DEFAULT_USER/PASS set

Correct: Custom credentials with environment variables

# GOOD -- custom credentials set via environment
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    environment:
      RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-admin}
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASS:?Set RABBITMQ_PASS}

Wrong: Missing hostname causing data directory mismatch

# BAD -- hostname changes on every container recreate
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    # No hostname set
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq

Correct: Fixed hostname for stable data directory

# GOOD -- fixed hostname ensures same data dir
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    hostname: rabbitmq
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq

Wrong: No health check -- dependent services start before RabbitMQ is ready

# BAD -- app starts before RabbitMQ accepts connections
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
  app:
    depends_on:
      - rabbitmq  # Only waits for container start

Correct: Health check with service_healthy condition

# GOOD -- app waits until RabbitMQ is actually ready
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "check_port_connectivity"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 40s
  app:
    depends_on:
      rabbitmq:
        condition: service_healthy

Common Pitfalls

• Data directory mismatch: RabbitMQ stores data under /var/lib/rabbitmq/mnesia/rabbit@<hostname>. If hostname changes on recreate, the node sees an empty data directory. Fix: Always set hostname: rabbitmq. [src1]
• Erlang cookie mismatch: Nodes fail to join cluster with "Connection attempt from disallowed node" errors. Fix: Set RABBITMQ_ERLANG_COOKIE to the same value on all nodes. [src3]
• Memory alarm blocks publishing: When memory exceeds vm_memory_high_watermark (default 0.4), all publishers are blocked. Fix: Set vm_memory_high_watermark.relative = 0.6 and monitor. [src2]
• Disk alarm blocks publishing: When free disk drops below disk_free_limit (default 50MB), all publishers are blocked. Fix: Set disk_free_limit.absolute = 1GB for production. [src2]
• Guest user restricted to localhost: Default guest/guest can only connect from localhost. From another container, auth fails. Fix: Create a non-guest user or set loopback_users = none. [src2]
• Management plugin not enabled: Base rabbitmq image has no web UI. Fix: Use rabbitmq:4.0-management-alpine or mount enabled_plugins. [src1]
• Port 15672 exposed to internet: Management UI exposed without TLS allows credential sniffing. Fix: Use TLS or restrict via reverse proxy. [src2]
• Classic mirrored queues in 4.0+: Classic queue mirroring removed in 4.0. ha-mode policies silently ignored. Fix: Migrate to quorum queues. [src4]

Diagnostic Commands

# Check container status and health
docker compose ps
docker compose logs rabbitmq --tail=50

# Check RabbitMQ node status
docker compose exec rabbitmq rabbitmqctl status

# Check cluster status
docker compose exec rabbitmq rabbitmqctl cluster_status

# List queues with message counts
docker compose exec rabbitmq rabbitmqctl list_queues name messages consumers type

# List connections
docker compose exec rabbitmq rabbitmqctl list_connections user peer_host state

# Check alarms (memory/disk)
docker compose exec rabbitmq rabbitmqctl node_health_check

# Check effective configuration
docker compose exec rabbitmq rabbitmq-diagnostics environment

# Test AMQP connectivity
docker compose exec rabbitmq rabbitmq-diagnostics check_port_connectivity

# Export definitions (backup)
docker compose exec rabbitmq rabbitmqctl export_definitions /tmp/definitions.json

Version History & Compatibility

Docker Image Tags

When to Use / When Not to Use

Important Caveats

• RabbitMQ 4.0 removed classic queue mirroring entirely -- existing ha-mode / ha-params policies are silently ignored after upgrade; you must migrate to quorum queues for HA
• The guest user can only connect from localhost by default -- containers connecting from a different network namespace need a dedicated user
• Environment variables like RABBITMQ_DEFAULT_USER only apply on first boot when the Mnesia database is empty -- changing them on existing volumes has no effect; use rabbitmqctl or definitions import instead
• RabbitMQ uses Erlang's distribution protocol for clustering (port 25672) which is unencrypted by default -- in untrusted networks, enable Erlang distribution over TLS
• Alpine-based images are smaller (~75MB vs ~175MB) but may have compatibility issues with certain Erlang NIFs -- test thoroughly before production use
• The management UI HTTP API at port 15672 exposes full broker control -- always protect with strong credentials, TLS, and network restrictions