The Homebrew RabbitMQ Formula

Overview

Homebrew is a popular package manager for macOS and Linux. A RabbitMQ formula is available from Homebrews core tap (out of the box). The formula maintained by Homebrew community and not Team RabbitMQ.

A recent supported Erlang/OTP version will be installed as a dependency.

Please read this short guide from start to finish. The formula is has its caveats, some of which may render a node unupgradable to RabbitMQ 3.12 and later versions because of disabled stable feature flags.

Installation

Before installing make sure the taps are up-to-date:

brew update

Then, install RabbitMQ server with:

brew install rabbitmq

Installing the RabbitMQ formula will install key dependencies such as a supported Erlang/OTP version.

However, installing the formula will not start the service (a RabbitMQ node). See Running and Managing the Node below.

Locations

Both RabbitMQ server scripts and CLI tools are installed into the sbin directory under /usr/local/Cellar/rabbitmq/{version}/ for Intel Macs or /opt/homebrew/Cellar/rabbitmq/{version}/ for Apple Silicon Macs.

They should be accessible from /usr/local/opt/rabbitmq/sbin for for Intel Macs or /opt/homebrew/opt/rabbitmq/sbin for Apple Silicon Macs. Links to binaries have been created under /usr/local/sbin for Intel Macs or /opt/homebrew/sbin for Apple Silicon ones.

To find out locations for your installation, use:

brew info rabbitmq

Effective OS User

With Homebrew, the node and CLI tools will use the logged in user OS account by default. This is optimal for development environments and means that the same shared secret file is used by both RabbitMQ nodes and CLI tools.

Running and Managing the Node

Unlike some other installation methods, namely the Debian and RPM packages, RabbitMQ Homebrew formula uses generic UNIX binary builds and does not require sudo.

Starting the Server

Starting a Node In the Foreground

To start a node in the foreground, run:

CONF_ENV_FILE="/opt/homebrew/etc/rabbitmq/rabbitmq-env.conf" /opt/homebrew/opt/rabbitmq/sbin/rabbitmq-server

After starting a node, we recommend enabling all feature flags on it:

# highly recommended: enable all feature flags on the running node
/opt/homebrew/sbin/rabbitmqctl enable_feature_flag all

Starting a Node In the Background

To start a node in the background, use brew services start:

# starts a local RabbitMQ node
brew services start rabbitmq

# highly recommended: enable all feature flags on the running node
/opt/homebrew/sbin/rabbitmqctl enable_feature_flag all

Stopping the Server

To stop a running node, use:

# stops the locally running RabbitMQ node
brew services stop rabbitmq

or CLI tools directly:

/opt/homebrew/sbin/rabbitmqctl shutdown
```bash

The command will wait for the node process to stop. If the target node is not running,
it will exit with a warning.


## Using RabbitMQ CLI Tools with Homebrew \{#cli}

The formula sets up links to CLI tools under `/usr/local/sbin` for Intel Macs or `/opt/homebrew/sbin` for Apple Silicon Macs.

In case that directory is not in `PATH`, it is recommended to append it:

```bash
# for macOS Intel
export PATH=$PATH:/usr/local/sbin
# for Apple Silicon
export PATH=$PATH:/opt/homebrew/sbin

Add the above export to the shell profile (such as ~/.bashrc for bash or ~/.zshrc for zsh) to have PATH updated for every new shell, including OS restarts.

Enabling Feature Flags

The Homebrew formula does not enable feature flags after installation. To enable all feature flags after installation (this is very important both to get access to certain features and for future release compatibility), use

/opt/homebrew/sbin/rabbitmqctl enable_feature_flag all

Configuring a Homebrew-installed RabbitMQ Node

File and directory locations used by Homebrew differ from Intel Macs to Apple Silicon ones. To find out locations for your installation, use:

brew info rabbitmq

On Apple Silicon Macs, RabbitMQ configuration file located at /opt/homebrew/etc/rabbitmq/rabbitmq.conf. The file does not exist by default and must be created by the user. The node then must be restarted so that it picks up the new configuration file on boot.

It is possible to use environment variables to control certain settings. rabbitmq-env.conf is located at /opt/homebrew/etc/rabbitmq/rabbitmq-env.conf

See RabbitMQ configuration guide to learn more.

Reinstalling the Formula

To reinstall the formula, for example, if an older installation cannot be upgraded because it did not proactively enable all feature flags, uninstall it, then remove all node data files:

brew services stop rabbitmq

brew uninstall rabbitmq

# Now delete all node's data directories and configuration files.
# This assumes that Homebrew root is at /opt/homebrew
rm -rf /opt/homebrew/etc/rabbitmq/
rm -rf /opt/homebrew/opt/rabbitmq/
rm -rf /opt/homebrew/var/lib/rabbitmq/
# the launch agent file
rm -f $HOME/Library/LaunchAgents/homebrew.mxcl.rabbitmq.plist

# re-install
brew install rabbitmq

## start the service if necessary
# brew services start rabbitmq

## after starting the service, enable all feature flags
# /opt/homebrew/sbin/rabbitmqctl enable_feature_flag all