---
# === IDENTITY ===
id: software/devops/docker-rabbitmq/2026
canonical_question: "Docker Compose reference: RabbitMQ"
aliases:
  - "RabbitMQ Docker Compose setup"
  - "docker-compose rabbitmq management plugin"
  - "RabbitMQ container configuration"
  - "RabbitMQ Docker clustering"
  - "rabbitmq docker-compose.yml example"
  - "RabbitMQ Docker health check"
  - "run RabbitMQ in Docker"
  - "RabbitMQ Docker environment variables"
entity_type: software_reference
domain: software > devops > Docker RabbitMQ
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === VERIFICATION ===
last_verified: 2026-02-27
confidence: 0.94
version: 1.0
first_published: 2026-02-27

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: stable
  last_breaking_change: "RabbitMQ 4.0 (Oct 2024) -- removed classic queue mirroring, added default delivery-limit of 20 for quorum queues, removed queue storage v1"
  next_review: 2026-08-26
  change_sensitivity: moderate

# === CONSTRAINTS ===
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"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "Need Kafka or event streaming, not message queuing"
    use_instead: "software/devops/docker-kafka/2026"
  - condition: "Need Redis pub/sub, not AMQP message broker"
    use_instead: "software/devops/docker-redis/2026"
  - condition: "Need RabbitMQ on Kubernetes, not Docker Compose"
    use_instead: "software/devops/rabbitmq-kubernetes/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: "deployment_mode"
    question: "Do you need a single RabbitMQ node or a cluster?"
    type: choice
    options: ["single_node", "cluster"]
  - key: "rabbitmq_version"
    question: "Which RabbitMQ version are you targeting?"
    type: choice
    options: ["4.0", "3.13", "3.12"]

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/software/devops/docker-rabbitmq/2026"
suggested_citation: "Source: knowledgelib.io -- AI Knowledge Library (verified 2026-02-27)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to:
    - id: "software/devops/docker-redis/2026"
      label: "Docker Compose: Redis"
    - id: "software/devops/docker-postgres/2026"
      label: "Docker Compose: PostgreSQL"
  solves: []
  alternative_to:
    - id: "software/devops/docker-kafka/2026"
      label: "Docker Compose: Apache Kafka"
  often_confused_with:
    - id: "software/devops/docker-redis/2026"
      label: "Docker Compose: Redis (pub/sub vs AMQP)"

# === SOURCES (7 authoritative sources) ===
# Types: official_docs, technical_blog, rfc_spec, academic_paper, community_resource, industry_report
# Reliability: high, moderate_high, moderate, moderate_low, low, authoritative
sources:
  - id: src1
    title: "RabbitMQ Official Docker Image"
    author: Docker Library
    url: https://hub.docker.com/_/rabbitmq
    type: official_docs
    published: 2025-12-01
    reliability: authoritative
  - id: src2
    title: "RabbitMQ Configuration Guide"
    author: RabbitMQ Team
    url: https://www.rabbitmq.com/docs/configure
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src3
    title: "RabbitMQ Clustering Guide"
    author: RabbitMQ Team
    url: https://www.rabbitmq.com/docs/clustering
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src4
    title: "Quorum Queues"
    author: RabbitMQ Team
    url: https://www.rabbitmq.com/docs/quorum-queues
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src5
    title: "How to use RabbitMQ with Docker and Docker Compose"
    author: Geshan Manandhar
    url: https://geshan.com.np/blog/2024/05/rabbitmq-docker/
    type: technical_blog
    published: 2024-05-15
    reliability: moderate_high
  - id: src6
    title: "RabbitMQ 3.13.0 Announcement"
    author: RabbitMQ Team
    url: https://www.rabbitmq.com/blog/2024/03/11/rabbitmq-3.13.0-announcement
    type: official_docs
    published: 2024-03-11
    reliability: high
  - id: src7
    title: "Docker Compose Health Checks for RabbitMQ"
    author: Docker Library
    url: https://github.com/docker-library/rabbitmq/issues/326
    type: community_resource
    published: 2023-08-15
    reliability: moderate_high
---

# 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
<!-- Agents: read this section before recommending any action from this unit.
     These are hard constraints that must not be violated. -->

- 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 | Image | Ports | Volumes | Key Env |
|---|---|---|---|---|
| rabbitmq | `rabbitmq:4.0-management-alpine` | `5672:5672` (AMQP), `15672:15672` (mgmt UI) | `rabbitmq_data:/var/lib/rabbitmq` | `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS` |
| rabbitmq (TLS) | `rabbitmq:4.0-management` | `5671:5671` (AMQPS), `15671:15671` (mgmt TLS) | `rabbitmq_data:/var/lib/rabbitmq`, `./certs:/etc/rabbitmq/certs:ro` | `RABBITMQ_SSL_CERTFILE`, `RABBITMQ_SSL_KEYFILE` |
| rabbitmq (cluster) | `rabbitmq:4.0-management` | `5672`, `15672`, `25672` (inter-node) | `rabbitmq_data_N:/var/lib/rabbitmq` | `RABBITMQ_ERLANG_COOKIE`, `RABBITMQ_NODENAME` |

**Key Configuration Files (inside container):**

| File | Path | Purpose |
|---|---|---|
| `rabbitmq.conf` | `/etc/rabbitmq/rabbitmq.conf` | Main config (sysctl format: `key = value`) |
| `enabled_plugins` | `/etc/rabbitmq/enabled_plugins` | Plugin list (Erlang term format) |
| `definitions.json` | `/etc/rabbitmq/definitions.json` | Pre-configured users, vhosts, queues, exchanges |
| `.erlang.cookie` | `/var/lib/rabbitmq/.erlang.cookie` | Cluster auth (set via `RABBITMQ_ERLANG_COOKIE`) |

**Key Ports:**

| Port | Protocol | Purpose |
|---|---|---|
| 5672 | AMQP 0-9-1 / AMQP 1.0 | Message broker (primary) |
| 5671 | AMQPS | TLS-encrypted AMQP |
| 15672 | HTTP | Management UI + HTTP API |
| 15692 | HTTP | Prometheus metrics (rabbitmq_prometheus plugin) |
| 25672 | TCP | Erlang distribution (inter-node clustering) |
| 4369 | TCP | EPMD (Erlang Port Mapper Daemon) |
| 61613 | STOMP | STOMP protocol (rabbitmq_stomp plugin) |
| 1883 | MQTT | MQTT protocol (rabbitmq_mqtt plugin) |

**Environment Variables:**

| Variable | Default | Purpose |
|---|---|---|
| `RABBITMQ_DEFAULT_USER` | `guest` | Initial admin username |
| `RABBITMQ_DEFAULT_PASS` | `guest` | Initial admin password |
| `RABBITMQ_DEFAULT_VHOST` | `/` | Default virtual host |
| `RABBITMQ_ERLANG_COOKIE` | (random) | Cluster authentication secret |
| `RABBITMQ_NODENAME` | `rabbit@hostname` | Node identifier (critical for data directory) |
| `RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS` | (empty) | Extra Erlang VM args |
| `RABBITMQ_CONFIG_FILES` | (empty) | Directory for additional .conf files |

## 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 -> Need high availability?
|   |   +-- YES -> 3-node cluster with quorum queues (Step 4)
|   |   +-- NO -> 2-node cluster with classic queues
|   +-- 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]

```yaml
# docker-compose.yml -- RabbitMQ with management UI
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    container_name: rabbitmq
    hostname: rabbitmq  # Fixed hostname prevents data dir mismatch
    ports:
      - "5672:5672"     # AMQP
      - "15672:15672"   # Management UI
    environment:
      RABBITMQ_DEFAULT_USER: myuser
      RABBITMQ_DEFAULT_PASS: mypassword
      RABBITMQ_DEFAULT_VHOST: /
    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:
    driver: local
```

**Verify**: `docker compose up -d && docker compose ps` -- status should show `healthy`. Open `http://localhost:15672` and log in with `myuser`/`mypassword`.

### 2. Add custom configuration files

For production, mount a `rabbitmq.conf` file to control memory limits, disk thresholds, and logging. [src2]

```ini
# rabbitmq.conf -- production configuration (sysctl format)
# Listeners
listeners.tcp.default = 5672

# Default credentials (override via env vars)
default_user = $(RABBITMQ_DEFAULT_USER)
default_pass = $(RABBITMQ_DEFAULT_PASS)
default_vhost = /

# Resource limits
vm_memory_high_watermark.relative = 0.6
vm_memory_high_watermark_paging_ratio = 0.5
disk_free_limit.absolute = 1GB

# Logging
log.console = true
log.console.level = info
log.file = false

# Security -- disable guest loopback for production
loopback_users = none

# Management plugin
management.tcp.port = 15672
management.cors.allow_origins.1 = *
```

```ini
# enabled_plugins -- Erlang term format
[rabbitmq_management,rabbitmq_prometheus].
```

Update docker-compose.yml volumes to mount these files:

```yaml
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
      - ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro
      - ./enabled_plugins:/etc/rabbitmq/enabled_plugins:ro
```

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

### 3. Configure TLS encryption

For production deployments, enable TLS on both the AMQP and management ports. [src2]

```ini
# rabbitmq.conf -- TLS section (append to existing config)
# TLS for AMQP
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

# TLS for management UI
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 -CAfile certs/ca.pem` -- should complete TLS handshake.

### 4. Set up a 3-node cluster

For high availability, deploy a RabbitMQ cluster with quorum queues. All nodes must share the same Erlang cookie. [src3]

> Full script: [docker-compose-cluster.yml](scripts/docker-compose-cluster.yml) (72 lines)

```yaml
# docker-compose-cluster.yml -- 3-node RabbitMQ cluster (excerpt)
services:
  rabbitmq1:
    image: rabbitmq:4.0-management-alpine
    hostname: rabbitmq1
    environment:
      RABBITMQ_ERLANG_COOKIE: "shared-secret-cookie-value"
      RABBITMQ_NODENAME: rabbit@rabbitmq1
      RABBITMQ_DEFAULT_USER: admin
      RABBITMQ_DEFAULT_PASS: secretpass
    # ... (see full script)
```

**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 for Grafana dashboards. [src2]

```ini
# Add to enabled_plugins
[rabbitmq_management,rabbitmq_prometheus].
```

```yaml
    ports:
      - "5672:5672"
      - "15672:15672"
      - "15692:15692"   # Prometheus metrics
```

**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](scripts/python-pika-producer-consumer.py) (58 lines)

```python
# Input:  RabbitMQ connection 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
)
# ... (see full script)
```

### Node.js: Producer and Consumer with amqplib

> Full script: [nodejs-amqplib-producer-consumer.js](scripts/nodejs-amqplib-producer-consumer.js) (56 lines)

```javascript
// Input:  RabbitMQ connection at localhost:5672
// Output: Messages sent to and received from "task_queue"
const amqplib = require('amqplib');  // amqplib@0.10.4

const RABBITMQ_URL = 'amqp://myuser:mypassword@localhost:5672';
const QUEUE = 'task_queue';
// ... (see full script)
```

### Docker Compose: Full Production Stack

> Full script: [docker-compose-production.yml](scripts/docker-compose-production.yml) (45 lines)

```yaml
# Input:  rabbitmq.conf + enabled_plugins in same directory
# Output: Production-ready RabbitMQ with monitoring
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    hostname: rabbitmq
    # ... (see full script)
```

### Shell: RabbitMQ Management CLI Operations

```bash
# Input:  Running RabbitMQ container named "rabbitmq"
# Output: Queue/exchange/user management via rabbitmqadmin

# List all queues
docker compose exec rabbitmq rabbitmqadmin list queues \
  --username=myuser --password=mypassword

# 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

# Publish a test message
docker compose exec rabbitmq rabbitmqadmin publish \
  exchange=amq.default routing_key=orders \
  payload='{"order_id":123}' \
  --username=myuser --password=mypassword

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

## Anti-Patterns

### Wrong: No volume mount for data persistence

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

### Correct: Named volume for data persistence

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

volumes:
  rabbitmq_data:
    driver: local
```

### Wrong: Using default guest credentials in production

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

### Correct: Custom credentials with environment variables

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

### Wrong: Missing hostname causing data directory mismatch

```yaml
# BAD -- hostname changes on every container recreate
# RabbitMQ data dir is /var/lib/rabbitmq/mnesia/rabbit@<hostname>
# New hostname = new empty data dir = data "loss"
services:
  rabbitmq:
    image: rabbitmq:4.0-management-alpine
    # No hostname set -- defaults to random container ID
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
```

### Correct: Fixed hostname for stable data directory

```yaml
# GOOD -- fixed hostname ensures same data dir across restarts
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

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

### Correct: Health check with service_healthy condition

```yaml
# 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 the container hostname changes on recreate, the node sees an empty data directory even with a volume mount. Fix: Always set `hostname: rabbitmq` in docker-compose.yml. [src1]
- **Erlang cookie mismatch in cluster**: 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 RabbitMQ memory usage exceeds `vm_memory_high_watermark` (default 0.4 of system RAM), all publishers are blocked. Fix: Set `vm_memory_high_watermark.relative = 0.6` and monitor with `rabbitmqctl status`. [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**: By default, `guest`/`guest` can only connect from localhost (127.0.0.1). When connecting from another container, authentication fails. Fix: Create a non-guest user or set `loopback_users = none` in rabbitmq.conf. [src2]
- **Management plugin not enabled**: Using base `rabbitmq` image (without `-management` suffix) has no web UI. Fix: Use `rabbitmq:4.0-management-alpine` or mount `enabled_plugins` file. [src1]
- **Port 15672 exposed to internet**: Management UI exposed without TLS allows credential sniffing. Fix: Use TLS or restrict access via reverse proxy / firewall. [src2]
- **Classic mirrored queues in RabbitMQ 4.0+**: Classic queue mirroring was removed in 4.0. Policies with `ha-mode` are silently ignored. Fix: Migrate to quorum queues (`x-queue-type: quorum`). [src4]

## Diagnostic Commands

```bash
# Check RabbitMQ 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 all queues with message counts
docker compose exec rabbitmq rabbitmqctl list_queues name messages consumers type

# List all exchanges
docker compose exec rabbitmq rabbitmqctl list_exchanges name type

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

# Check memory usage
docker compose exec rabbitmq rabbitmqctl status | grep -A 5 "Memory"

# 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 from host
docker compose exec rabbitmq rabbitmq-diagnostics check_port_connectivity

# Check Erlang cookie value
docker compose exec rabbitmq cat /var/lib/rabbitmq/.erlang.cookie

# Export current definitions (backup users, vhosts, queues, exchanges, policies)
docker compose exec rabbitmq rabbitmqctl export_definitions /tmp/definitions.json
```

## Version History & Compatibility

| Version | Status | Breaking Changes | Migration Notes |
|---|---|---|---|
| 4.0.x | Current (Oct 2024) | Classic queue mirroring removed; default delivery-limit of 20 on quorum queues; queue storage v1 removed | Migrate HA policies to quorum queues before upgrading; can run alongside 3.13.x nodes |
| 3.13.x | LTS until 2025-12 | Classic queue v2 default; Khepri metadata store (opt-in) | Last version supporting classic mirrored queues |
| 3.12.x | EOL | Stream filtering; classic queues v2 opt-in | Upgrade to 3.13 before jumping to 4.0 |

**Docker Image Tags:**

| Tag Pattern | Example | Notes |
|---|---|---|
| `rabbitmq:X.Y` | `rabbitmq:4.0` | Base image, no management UI |
| `rabbitmq:X.Y-management` | `rabbitmq:4.0-management` | Includes management plugin + web UI |
| `rabbitmq:X.Y-alpine` | `rabbitmq:4.0-alpine` | Alpine Linux base (smaller image) |
| `rabbitmq:X.Y-management-alpine` | `rabbitmq:4.0-management-alpine` | Alpine + management (recommended for production) |

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Need reliable async message delivery between services | Need simple in-memory pub/sub | Redis pub/sub |
| Need message persistence, routing, and dead-letter queues | Need event streaming with replay/retention | Apache Kafka |
| Need work queue pattern (distribute tasks to workers) | Need real-time WebSocket communication | Socket.IO / native WebSockets |
| Need flexible routing (topic, fanout, headers exchanges) | Need simple point-to-point only | AWS SQS or cloud-native queues |
| Need cross-language support (AMQP, STOMP, MQTT) | Need sub-millisecond latency | ZeroMQ or shared memory |

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

## Related Units
<!-- Generated from related_kos frontmatter -->

- [Docker Compose: Redis](/software/devops/docker-redis/2026)
- [Docker Compose: PostgreSQL](/software/devops/docker-postgres/2026)
- [Docker Compose: Apache Kafka](/software/devops/docker-kafka/2026)
