Skip to content

Docs: warn macOS users against installing RabbitMQ via Homebrew #7267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
r0hansaxena wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Docs: warn macOS users against installing RabbitMQ via Homebrew #7267

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16e11aa
Docs: warn macOS users against installing RabbitMQ via Homebrew
r0hansaxena Mar 5, 2026
8775cce
Merge remote-tracking branch 'origin/main' into issue_7232_discourage…
r0hansaxena Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/source/installation/guide_complete.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,33 @@ Although it is possible to run AiiDA without a daemon it does provide significan

The service has to manually be started each time the machine reboots.

.. warning::

The ``brew install`` can sometimes install a version of Erlang that is incompatible with the installed version of RabbitMQ, causing ``rabbitmq-server`` to crash on startup with no clear error message.
Copy link
Copy Markdown
Member

@mbercx mbercx Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The ``brew install`` can sometimes install a version of Erlang that is incompatible with the installed version of RabbitMQ, causing ``rabbitmq-server`` to crash on startup with no clear error message.
Homebrew can sometimes install a version of Erlang that is incompatible with the installed version of RabbitMQ.

If you run into this issue, verify that your installed versions of Erlang and RabbitMQ are `compatible <https://www.rabbitmq.com/docs/which-erlang>`__, or consider one of the alternative installation methods below.
Copy link
Copy Markdown
Member

@mbercx mbercx Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you run into this issue, verify that your installed versions of Erlang and RabbitMQ are `compatible <https://www.rabbitmq.com/docs/which-erlang>`__, or consider one of the alternative installation methods below.
If you run into issues, verify that your installed versions of Erlang and RabbitMQ are `compatible <https://www.rabbitmq.com/docs/which-erlang>`__, or consider one of the alternative installation methods below.

See the :ref:`troubleshooting section <installation:troubleshooting:installation:rabbitmq>` for more details.
Copy link
Copy Markdown
Member

@mbercx mbercx Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The troubleshooting section actually doesn't discuss this?


**Alternative installation methods:**
Copy link
Copy Markdown
Member

@mbercx mbercx Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd just have 3 sections, i.e. also add a Homebrew header at the top and remove this line. I also prefer boldface for the "headers".

Suggested change
**Alternative installation methods:**


*Using the generic binary build:*

#. Download the latest `generic binary build <https://www.rabbitmq.com/docs/install-generic-unix>`__ from the RabbitMQ website.
#. Extract the archive and follow the included installation instructions.
Copy link
Copy Markdown
Member

@mbercx mbercx Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if you checked, but the "included installation instructions" simply say:

Please see https://www.rabbitmq.com/docs/download for installation
guides.

I haven't tried this installation method, but the instructions on the RabbitMQ website also mention to "Make Sure Erlang/OTP is Installed". We definitely don't want to look up those instructions and add them here, however. So my suggestion would be to simply link to the generic binary installation instructions for this method. They explain the steps pretty well there.

#. Start the server:

.. code-block:: console

/path/to/rabbitmq_server-<version>/sbin/rabbitmq-server -detached

*Using Docker:*

#. Install `Docker Desktop <https://www.docker.com/products/docker-desktop/>`__.
#. Start a RabbitMQ container:

.. code-block:: console

docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management

.. tab-item:: Other

For all other cases, please refer to the `official documentation <https://www.rabbitmq.com/docs/download>`_ of RabbitMQ.
Expand Down