RabbitMQ Setup

RabbitMQ Setup

Configure RabbitMQ for Mantis message queuing and deployment orchestration.

Requirements

Requirement	Minimum	Recommended
RabbitMQ	3.12	3.13+
Erlang/OTP	25	26+
Memory	512 MB	2+ GB
Storage	5 GB	20+ GB

Installation

Ubuntu/Debian

# Add RabbitMQ signing key
curl -1sLf "https://keys.openpgp.org/vks/v1/by-fingerprint/0A9AF2115F4687BD29803A206B73A36E6026DFCA" | sudo gpg --dearmor -o /usr/share/keyrings/com.rabbitmq.team.gpg

# Add Erlang repository
curl -1sLf "https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key" | sudo gpg --dearmor -o /usr/share/keyrings/rabbitmq.E495BB49CC4BBE5B.gpg

# Add RabbitMQ repository
curl -1sLf "https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key" | sudo gpg --dearmor -o /usr/share/keyrings/rabbitmq.9F4587F226208342.gpg

# Add repository sources
sudo tee /etc/apt/sources.list.d/rabbitmq.list <<EOF
deb [signed-by=/usr/share/keyrings/rabbitmq.E495BB49CC4BBE5B.gpg] https://ppa1.novemberain.com/rabbitmq/rabbitmq-erlang/deb/ubuntu jammy main
deb [signed-by=/usr/share/keyrings/rabbitmq.9F4587F226208342.gpg] https://ppa1.novemberain.com/rabbitmq/rabbitmq-server/deb/ubuntu jammy main
EOF

# Install
sudo apt update
sudo apt install rabbitmq-server -y

RHEL/Rocky/Alma

# Add repository
curl -s https://packagecloud.io/install/repositories/rabbitmq/rabbitmq-server/script.rpm.sh | sudo bash
curl -s https://packagecloud.io/install/repositories/rabbitmq/erlang/script.rpm.sh | sudo bash

# Install
sudo dnf install rabbitmq-server -y

Docker

services:
  rabbitmq:
    image: rabbitmq:3.13-management-alpine
    hostname: rabbitmq
    environment:
      RABBITMQ_DEFAULT_USER: mantis
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD}
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
      - ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf
    ports:
      # Plain AMQP (5672) is intentionally NOT exposed — TLS is mandatory
      - '5671:5671' # AMQPS (TLS)
      - '15671:15671' # Management UI (TLS)

Initial Configuration

Enable Plugins

# Enable management plugin
sudo rabbitmq-plugins enable rabbitmq_management

# Enable TLS plugin
sudo rabbitmq-plugins enable rabbitmq_auth_mechanism_ssl

Create User

# Create mantis user
sudo rabbitmqctl add_user mantis 'secure-password'

# Set permissions
sudo rabbitmqctl set_permissions -p / mantis ".*" ".*" ".*"

# Set administrator tag
sudo rabbitmqctl set_user_tags mantis administrator

# Remove default guest user
sudo rabbitmqctl delete_user guest

Create Virtual Host (Optional)

# Create vhost
sudo rabbitmqctl add_vhost mantis

# Set permissions
sudo rabbitmqctl set_permissions -p mantis mantis ".*" ".*" ".*"

Configuration

Basic Configuration

Create /etc/rabbitmq/rabbitmq.conf:

# Listeners
# SECURITY: plain AMQP is disabled — TLS (AMQPS, 5671) is mandatory
listeners.tcp = none
listeners.ssl.default = 5671

# Management (TLS)
management.ssl.port = 15671

# Limits
channel_max = 2047
heartbeat = 60

# Memory
vm_memory_high_watermark.relative = 0.7
vm_memory_high_watermark_paging_ratio = 0.5

# Disk
disk_free_limit.relative = 2.0

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

Advanced Configuration

Create /etc/rabbitmq/advanced.config for complex settings:

[
  {rabbit, [
    {tcp_listeners, []},
    {ssl_listeners, [5671]},
    {num_ssl_acceptors, 10},
    {channel_max, 2047},
    {heartbeat, 60}
  ]},
  {rabbitmq_management, [
    {listener, [{port, 15671}, {ssl, true}]}
  ]}
].

Environment Variables

Create /etc/rabbitmq/rabbitmq-env.conf:

NODENAME=rabbit@hostname
NODE_IP_ADDRESS=0.0.0.0
RABBITMQ_USE_LONGNAME=true

Memory Management

Memory Watermark

/etc/rabbitmq/rabbitmq.conf

# Absolute limit (recommended for production)
vm_memory_high_watermark.absolute = 2GB

# Or relative (percentage of system memory)
vm_memory_high_watermark.relative = 0.7

# Paging threshold
vm_memory_high_watermark_paging_ratio = 0.5

Memory Alarms

When memory exceeds watermark:

1. Publishers are blocked
2. Consumers continue processing
3. Messages page to disk

Monitor with:

sudo rabbitmqctl status | grep memory

Disk Management

Disk Free Limit

/etc/rabbitmq/rabbitmq.conf

# Absolute (recommended)
disk_free_limit.absolute = 5GB

# Or relative to RAM
disk_free_limit.relative = 2.0

Message Store

# Message store settings
queue_index_embed_msgs_below = 4096
msg_store_file_size_limit = 16777216

High Availability

Clustering

On each node:

# Stop app
sudo rabbitmqctl stop_app

# Join cluster
sudo rabbitmqctl join_cluster rabbit@node1

# Start app
sudo rabbitmqctl start_app

# Check cluster status
sudo rabbitmqctl cluster_status

Queue Durability

Mantis declares durable (classic) queues — they survive broker restarts. The application does not set a quorum queue type. If you want quorum queues for multi-node durability, that is an optional RabbitMQ-side default you can enable yourself (Mantis does not depend on it):

# /etc/rabbitmq/rabbitmq.conf — OPTIONAL operator hardening, not required by Mantis
default_queue_type = quorum

Mirrored Queues (Classic)

For classic queue mirroring:

# Set HA policy
sudo rabbitmqctl set_policy ha-all "^mantis\." '{"ha-mode":"all","ha-sync-mode":"automatic"}'

Start Service

# Enable and start
sudo systemctl enable rabbitmq-server
sudo systemctl start rabbitmq-server

# Check status
sudo systemctl status rabbitmq-server
sudo rabbitmqctl status

Mantis Configuration

Thorax RabbitMQ Settings

thorax.toml

[queue]
enabled = true
ca_cert_path = "/etc/mantis/certs/ca.crt"  # mandatory when enabled = true (TLS is required)
host = "localhost"
port = 5671
username = "mantis"
password = "password"
prefetch_count = 10
reconnect_delay_secs = 5

With TLS Client Certificates

thorax.toml

[queue]
enabled = true
host = "rabbitmq.example.com"
port = 5671
username = "mantis"
password = "password"
prefetch_count = 10
ca_cert_path = "/etc/mantis/certs/ca.crt"

Configuration source

Thorax reads RabbitMQ settings — host, port (5671/AMQPS), username, password, vhost, prefetch_count, and the TLS certificate paths — from the [queue] table of thorax.toml (shown above). All fields can also be set or overridden via environment variables using the THORAX__QUEUE__<FIELD> convention, for example:

Environment variable	TOML field
THORAX__QUEUE__ENABLED	enabled
THORAX__QUEUE__HOST	host
THORAX__QUEUE__PORT	port
THORAX__QUEUE__USERNAME	username
THORAX__QUEUE__PASSWORD	password
THORAX__QUEUE__VHOST	vhost
THORAX__QUEUE__CA_CERT_PATH	ca_cert_path
THORAX__QUEUE__CLIENT_CERT_PATH	client_cert_path
THORAX__QUEUE__CLIENT_KEY_PATH	client_key_path
THORAX__QUEUE__PREFETCH_COUNT	prefetch_count
THORAX__QUEUE__PUBLISHER_CONFIRMS	publisher_confirms
THORAX__QUEUE__FALLBACK_ON_FAILURE	fallback_on_failure
THORAX__QUEUE__HEALTH_CHECK_INTERVAL_SECS	health_check_interval_secs
THORAX__QUEUE__RECONNECT_DELAY_SECS	reconnect_delay_secs

Environment variables take precedence over TOML values, making them useful for secrets (e.g. THORAX__QUEUE__PASSWORD) and environment-specific overrides in container deployments.

Verification

Check Connection

# List connections
sudo rabbitmqctl list_connections name state

# List channels
sudo rabbitmqctl list_channels connection name state

# List queues
sudo rabbitmqctl list_queues name messages consumers

Test from Application

# Check Thorax connection
docker compose logs thorax | grep -i rabbit

Management UI

Access

Open https://localhost:15671 (the management UI is served over TLS)

Default credentials after setup:

• Username: mantis
• Password: (configured password)

Features

Tab	Purpose
Overview	Cluster status, message rates
Connections	Active connections
Channels	Channel details
Exchanges	Exchange configuration
Queues	Queue status and messages
Admin	User and policy management

Troubleshooting

Connection Refused

1. Check service is running: systemctl status rabbitmq-server
2. Verify the AMQPS port is open: netstat -tlnp | grep 5671
3. Check firewall rules

Authentication Failed

1. Verify user exists: rabbitmqctl list_users
2. Check password
3. Verify permissions: rabbitmqctl list_permissions

Memory Alarm

1. Check memory usage: rabbitmqctl status
2. Consume pending messages
3. Increase watermark or add memory

Disk Alarm

1. Check disk usage: df -h
2. Clean old data
3. Increase disk space

Next Steps

• TLS Configuration - Secure connections
• Queue Topology - Queue structure
• Monitoring - RabbitMQ monitoring