> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# RabbitMQ

> Ready-to-run RabbitMQ container template you can run directly or inherit to integrate a message broker into your stack.

## Overview

This template provides a production‑ready RabbitMQ instance as a Monk runnable. You can:

* Run it directly to get a managed RabbitMQ container with sensible defaults
* Inherit it in your own runnable to seamlessly add a message broker to your stack

It exposes RabbitMQ on multiple ports (AMQP, management UI, streaming), persists data to a host volume, and includes configuration files for customization.

## What this template manages

* RabbitMQ container (`rabbitmq` image, configurable tag with management plugin)
* Network services on multiple ports (AMQP, management UI, clustering)
* Persistent volumes for data and configuration
* Configuration files for RabbitMQ, advanced settings, and environment variables
* Optional Nginx reverse proxy for the management UI

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run RabbitMQ with defaults

```bash theme={null}
monk run rabbitmq/rabbitmq
```

3. Run the full stack with Nginx reverse proxy

```bash theme={null}
monk run rabbitmq/stack
```

Once started, connect to:

* AMQP: `localhost:5672` (or the runnable hostname inside Monk networks)
* Management UI: `localhost:15672` (or `localhost:8080` if using the stack with Nginx)
* Default credentials: `guest` / `guest`

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  rabbitmq-image-tag: "3.10-management"  # container image tag
  nginx-listen-port: 8080                # Nginx proxy port (when using stack)
  nginx-image-tag: "latest"              # Nginx image version
```

Data is persisted under `${monk-volume-path}/rabbitmq:/var/lib/rabbitmq/` on the host.

## Configuration files

RabbitMQ uses three configuration files that can be customized:

* **rabbitmq.conf**: Primary configuration file (sysctl/ini-like format) at `/etc/rabbitmq/rabbitmq.conf`
* **advanced.config**: Erlang-based config for advanced settings at `/etc/rabbitmq/advanced.config`
* **rabbitmq-env.conf**: Environment variables at `/etc/rabbitmq/rabbitmq-env.conf`

These files are located in the `files/` directory of this repository and are mounted into the container.

## Use by inheritance (recommended for apps)

Inherit the RabbitMQ runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
broker:
  defines: runnable
  inherits: rabbitmq/rabbitmq
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    messagequeue:
      runnable: broker
      service: rabbitmq-amqp-1
  variables:
    rabbitmq-host:
      value: <- connection-hostname("messagequeue")
    rabbitmq-port:
      value: <- connection-port("messagequeue")
    rabbitmq-user:
      value: "guest"
    rabbitmq-password:
      value: "guest"
```

Then run your app group:

```bash theme={null}
monk run myapp/api
```

## Ports and connectivity

RabbitMQ exposes multiple services:

* Service: `rabbitmq-amqp-1` on TCP port `5672` (AMQP protocol)
* Service: `rabbitmq-amqp-2` on TCP port `5671` (AMQP with TLS)
* Service: `rabbitmq-ui-2` on TCP port `15672` (Management UI)
* Service: `rabbitmq-ui-1` on TCP port `15671` (Management UI with TLS)
* Service: `rabbitmq-stream-1` on TCP port `5551` (Stream protocol)
* Service: `rabbitmq-stream-2` on TCP port `5552` (Stream protocol)
* Service: `rabbitmq-erl-epmd-port` on TCP port `4369` (Erlang port mapper)
* Service: `rabbitmq-cli` on TCP port `25672` (CLI tools)

From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the broker host.

## Persistence and configuration

* Data path: `${monk-volume-path}/rabbitmq:/var/lib/rabbitmq/`
* Config files are mounted from the `files/` directory in this repository
* Modify the config files before loading the template to customize RabbitMQ behavior

## Stack deployment

The `rabbitmq/stack` process group includes:

* RabbitMQ server (`rabbitmq/rabbitmq`)
* Nginx reverse proxy (`rabbitmq/nginx`) for the management UI on port 8080

This provides a complete setup with load balancing and proxy capabilities.

## Default credentials

The default administrator username and password are:

* Username: `guest`
* Password: `guest`

**Important**: Change these credentials in production by modifying the configuration files or environment variables.

## Troubleshooting

* Check that the host volumes are writable by the container user
* Verify that ports 5672 and 15672 are not already in use
* View RabbitMQ logs:

```bash theme={null}
monk logs -l 500 -f rabbitmq/rabbitmq
```

* View Nginx logs (when using stack):

```bash theme={null}
monk logs -l 500 -f rabbitmq/nginx
```

* Access container shell:

```bash theme={null}
monk shell rabbitmq/rabbitmq
```

## Related resources

* RabbitMQ Documentation: [https://www.rabbitmq.com/documentation.html](https://www.rabbitmq.com/documentation.html)
* AMQP Protocol: [https://www.amqp.org/](https://www.amqp.org/)
* Management Plugin Guide: [https://www.rabbitmq.com/management.html](https://www.rabbitmq.com/management.html)