RabbitMQ Setup

Configure RabbitMQ for Mantis message queuing and deployment orchestration.

Requirements

Requirement	Minimum	Recommended
RabbitMQ	4.x	4.3+
Erlang/OTP	26	27+
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

Import the RabbitMQ signing keys, then add the signed repositories. The file below is for EL9 and later; the upstream instructions give the EL8 variant.

sudo rpm --import https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc
sudo rpm --import https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key
sudo rpm --import https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key

sudo tee /etc/yum.repos.d/rabbitmq.repo >/dev/null <<'EOF'
[modern-erlang]
name=modern-erlang
baseurl=https://yum1.rabbitmq.com/erlang/el/9/$basearch
        https://yum2.rabbitmq.com/erlang/el/9/$basearch
repo_gpgcheck=1
gpgcheck=1
enabled=1
sslverify=1
gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key

[modern-erlang-noarch]
name=modern-erlang-noarch
baseurl=https://yum1.rabbitmq.com/erlang/el/9/noarch
        https://yum2.rabbitmq.com/erlang/el/9/noarch
repo_gpgcheck=1
gpgcheck=1
enabled=1
sslverify=1
gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-erlang.E495BB49CC4BBE5B.key
       https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc

[rabbitmq-el9]
name=rabbitmq-el9
baseurl=https://yum1.rabbitmq.com/rabbitmq/el/9/$basearch
        https://yum2.rabbitmq.com/rabbitmq/el/9/$basearch
repo_gpgcheck=1
gpgcheck=1
enabled=1
sslverify=1
gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key
       https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc

[rabbitmq-el9-noarch]
name=rabbitmq-el9-noarch
baseurl=https://yum1.rabbitmq.com/rabbitmq/el/9/noarch
        https://yum2.rabbitmq.com/rabbitmq/el/9/noarch
repo_gpgcheck=1
gpgcheck=1
enabled=1
sslverify=1
gpgkey=https://github.com/rabbitmq/signing-keys/releases/download/3.0/cloudsmith.rabbitmq-server.9F4587F226208342.key
       https://github.com/rabbitmq/signing-keys/releases/download/3.0/rabbitmq-release-signing-key.asc
EOF

sudo dnf install -y erlang rabbitmq-server

Docker

services:
  rabbitmq:
    image: rabbitmq:4.3.6-management
    hostname: rabbitmq
    environment:
      RABBITMQ_DEFAULT_USER: mantis
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD}
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
      - ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf
      # The conf above names these; without the mount the node cannot start its listener.
      - ./certs:/etc/rabbitmq/certs:ro
    # Its own uid, so the entrypoint does not start as root and drop privileges --
    # that drop discards group_add and leaves the group-readable key unreadable.
    user: '999:999'
    group_add:
      - '${MANTIS_CERT_GID:-1000}'
    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

# TLS itself needs no plugin: the listener comes from listeners.ssl.default below.
# rabbitmq_auth_mechanism_ssl is deliberately NOT enabled -- it only adds the EXTERNAL
# SASL mechanism, and Mantis authenticates with a username and password.

Create Virtual Host

Mantis runs on /mantis, not the default /. The vhost has to exist before any permission can be granted on it, so this step comes first.

sudo rabbitmqctl add_vhost /mantis

Create User

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

# Set permissions on the vhost created above
sudo rabbitmqctl set_permissions -p /mantis mantis ".*" ".*" ".*"

# Read access to the management API, which `mantisctl` and the health checks in
# Monitoring use. Mantis needs no more: `administrator` would hand the
# application's credential control of the whole broker.
sudo rabbitmqctl set_user_tags mantis monitoring

# Remove default guest user
sudo rabbitmqctl delete_user guest

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

# TLS material. The node will not start its listener without these.
ssl_options.cacertfile = /etc/rabbitmq/certs/ca-cert.pem
ssl_options.certfile = /etc/rabbitmq/certs/server-cert.pem
ssl_options.keyfile = /etc/rabbitmq/certs/server-key.pem
ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = true

# Management (TLS)
management.ssl.port = 15671
management.ssl.cacertfile = /etc/rabbitmq/certs/ca-cert.pem
management.ssl.certfile = /etc/rabbitmq/certs/server-cert.pem
management.ssl.keyfile = /etc/rabbitmq/certs/server-key.pem

# Limits
channel_max = 2047
heartbeat = 60

# Memory
vm_memory_high_watermark.relative = 0.7

# 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}
  ]}
].

The management listener is not set here: configure it with the management.ssl.* keys in rabbitmq.conf.

Environment Variables

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

# Names here are written without the RABBITMQ_ prefix. Set NODENAME only on a fresh
# node: the data directory is named after it, so changing it on a live broker orphans
# every vhost, user and queue. USE_LONGNAME needs a fully qualified host part.
NODENAME=rabbit@rabbitmq.example.com
USE_LONGNAME=true

Memory Management

Memory Watermark

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

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

vm_memory_high_watermark_paging_ratio is not available on 4.x — an unknown key in rabbitmq.conf stops the node booting.

Memory Alarms

When memory exceeds watermark:

Publishers are blocked
Consumers continue processing
Messages page to disk

Monitor with:

sudo rabbitmqctl status | grep memory

Disk Management

Disk Free Limit

# 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 went with the classic-queue
# v1 index and is not a valid 4.x key.
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. mantis.commands.priority.{high,normal,low} are declared with x-max-priority, a classic-queue argument RabbitMQ refuses on a quorum queue, so the declaration names x-queue-type: classic alongside it. A broker-wide default_queue_type = quorum is therefore harmless: it applies only to declarations that do not name a type.

The real hazard is a queue that is already quorum — a quorum policy scoped over ^mantis\., or a queue hand-declared as quorum before Mandible first ran. Re-declaring it with different arguments fails with PRECONDITION_FAILED and the platform does not come up. Scope any quorum policy to exclude those three queues.

High Availability

Classic queue mirroring (ha-mode) was removed in RabbitMQ 4.x and does not apply. For HA, run a RabbitMQ cluster. Mantis declares its own queues at startup, so do not hand-declare them, and see the queue-type constraint above before applying a quorum policy over ^mantis\..

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

[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 = "<the mantis broker user's password>"
vhost = "/mantis"  # defaults to "/", where the mantis user has no permissions
# The shipped broker sets fail_if_no_peer_cert, so these are required too:
client_cert_path = "/etc/mantis/certs/rabbitmq-client-cert.pem"
client_key_path = "/etc/mantis/certs/rabbitmq-client-key.pem"
prefetch_count = 10
reconnect_delay_secs = 5

With TLS Client Certificates

The bundled broker sets ssl_options.fail_if_no_peer_cert = true, so a client certificate is required, not optional — client_cert_path and client_key_path must both be set. A broker built by hand from Manual Installation uses the same setting, and TLS Configuration covers issuing the client certificates:

[queue]
enabled = true
host = "rabbitmq.example.com"
port = 5671
username = "mantis"
password = "<the mantis broker user's password>"
vhost = "/mantis"  # defaults to "/", where the mantis user has no permissions
prefetch_count = 10
ca_cert_path = "/etc/mantis/certs/rabbitmq-ca.pem"
client_cert_path = "/etc/mantis/certs/rabbitmq-client-cert.pem"
client_key_path = "/etc/mantis/certs/rabbitmq-client-key.pem"

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 -p /mantis 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

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

Authentication Failed

Verify user exists: rabbitmqctl list_users
Check password
Verify permissions: rabbitmqctl list_permissions -p /mantis

Memory Alarm

Check memory usage: rabbitmqctl status
Consume pending messages
Increase watermark or add memory

Disk Alarm

Check disk usage: df -h
Clean old data
Increase disk space

Next Steps

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