DocumentationCommerceCommerce on Cloud Guide

[PaaS only]{class="badge informative" title="Applies to Adobe Commerce on Cloud projects (Adobe-managed PaaS infrastructure) and on-premises projects only."}

Set up RabbitMQ service

Last update: Fri Nov 07 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

The Message Queue Framework (MQF) is a system within Adobe Commerce that allows a module to publish messages to queues. It also defines the consumers that receive the messages asynchronously.

The MQF uses RabbitMQ as the messaging broker, which provides a scalable platform for sending and receiving messages. It also includes a mechanism for storing undelivered messages. RabbitMQ is based on the Advanced Message Queuing Protocol (AMQP) 0.9.1 specification.

NOTE
Adobe Commerce on cloud infrastructure also supports ActiveMQ Artemis as an alternative message queue service using the STOMP protocol.
IMPORTANT
If you prefer using an existing AMQP-based service, like RabbitMQ, instead of relying on Adobe Commerce on cloud infrastructure to create it for you, use the QUEUE_CONFIGURATION environment variable to connect it to your site.

Use the following instructions for service setup on Pro Integration environments and Starter environments, including the master branch.

NOTE
Submit an Adobe Commerce Support ticket to change the service configuration on Pro Production and Staging environments.

To enable RabbitMQ:

  1. Add the required name, type, and disk value (in MB) to the .magento/services.yaml file along with the installed RabbitMQ version.

    code language-yaml 
    rabbitmq:
    type: rabbitmq:<version>
    disk: 1024

  2. Configure the relationships in the .magento.app.yaml file.

    code language-yaml 
    relationships:
    rabbitmq: "rabbitmq:rabbitmq"

  3. Add, commit, and push your code changes.

    code language-bash 
    git add .magento/services.yaml .magento.app.yaml
    code language-bash 
    git commit -m "Enable RabbitMQ service"
    code language-bash 
    git push origin <branch-name>

  4. Verify the service relationships.

TIP
After initial service setup, you can change the software version for an installed service by updating the services.yaml and .magento.app.yaml configuration files. See Change service version for guidance on upgrading or downgrading a service.

Connect to RabbitMQ for debugging

For debugging purposes, it is useful to directly connect to a service instance in one of the following ways:

  • Connect from your local development environment
  • Connect from the application
  • Connect from your PHP application

Connect from your local development environment

  1. Log in to the magento-cloud CLI and project:

    code language-bash 
    magento-cloud login

  2. Check out the environment with RabbitMQ installed and configured.

    code language-bash 
    magento-cloud environment:checkout <environment-id>

  3. Use SSH to connect to the Cloud environment:

    code language-bash 
    magento-cloud ssh

  4. Retrieve the RabbitMQ connection details and login credentials from the $MAGENTO_CLOUD_RELATIONSHIPS variable:

    code language-bash 
    echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 -d | json_pp

    or

    code language-bash 
    php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"])));'

    In the response, find the RabbitMQ information, for example:

    code language-json 
    {
   "rabbitmq" : [
      {
         "password" : "guest",
         "ip" : "246.0.129.2",
         "scheme" : "amqp",
         "port" : 5672,
         "host" : "rabbitmq.internal",
         "username" : "guest"
      }
   ]
}

  5. Enable local port forwarding to RabbitMQ (if your project is located on a different region such as US-3, EU-5, or AP-3 region, substitute us-3/eu-5/ap-3 for us)

    code language-bash 
    ssh -L <port-number>:rabbitmq.internal:<port-number> <project-ID>-<branch-ID>@ssh.us.magentosite.cloud

    An example for accessing the RabbitMQ management web interface at http://localhost:15672 is:

    code language-bash 
    ssh -L 15672:rabbitmq.internal:15672 <project-ID>-<branch-ID>@ssh.us.magentosite.cloud

  6. While the session is open, you can start a RabbitMQ client of your choice from your local workstation, configured to connect to the localhost:<portnumber> using the port number, username, and password information from the MAGENTO_CLOUD_RELATIONSHIPS variable.

Connect from the application

To connect to RabbitMQ running in an application, install a client, such as amqp-utils, as a project dependency in your .magento.app.yaml file.

For example,

dependencies:
    ruby:
        amqp-utils: "0.5.1"

When you log in to your PHP container, you enter any amqp- command available to manage your queues.

Connect from your PHP application

To connect to RabbitMQ using your PHP application, add a PHP library to your source tree.

Troubleshooting the RabbitMQ service

See Unable to connect to RabbitMQ in Adobe Commerce Cloud.

Upgrading the RabbitMQ service

For upgrade instructions, see Change service version.

recommendation-more-help
7c2b03ac-000c-497d-aba3-2c6dc720a938