DocumentationCommerceUpgrade Guide

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

Migrating to ActiveMQ

Last update: Thu Dec 11 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin
  • Developer

ActiveMQ (Apache ActiveMQ Artemis) is a high-performance, multi-protocol message broker that provides an alternative to RabbitMQ for handling message queues in Adobe Commerce.

As of 2.4.8-p3, 2.4.7-p8, 2.4.6-p13 and 2.4.5-p16, Adobe Commerce supports ActiveMQ as a message queue broker. This provides additional flexibility for on-premises installations to choose between RabbitMQ and ActiveMQ based on their infrastructure requirements and expertise.

Before you begin

Before starting the migration, ensure the following:

  1. Review your current RabbitMQ configuration in app/etc/env.php.
  2. Take a complete backup of your database and codebase.
  3. Ensure your installation meets the system requirements for ActiveMQ.
  4. Plan for a maintenance window to complete the migration.

Migration path

Migrating to ActiveMQ is a straightforward process, but it’s essential to ensure that all pending messages are processed before switching brokers.

These migration instructions assume that Adobe Commerce is the sole application utilizing the message queue broker.

Step 1: Place the site in Maintenance Mode

  1. Place the site in Maintenance Mode:

    code language-bash 
    bin/magento maintenance:enable

  2. Verify maintenance mode is enabled:

    code language-bash 
    bin/magento maintenance:status

Step 2: Check RabbitMQ message counts

Before proceeding, verify that all messages in RabbitMQ have been processed. Use one of the following methods:

Method A: Using RabbitMQ Management Dashboard

  1. Access the RabbitMQ Management UI at http://<host>:15672

  2. Default credentials: guest/guest

  3. Navigate to the Queues tab

  4. Verify all queues show 0 messages

    RabbitMQ Management Dashboard

Method B: Using rabbitmqctl command line

  1. Check all queues and their message counts:

    code language-bash 
    rabbitmqctl list_queues name messages consumers

    RabbitMQ CLI Output {width="500"}

  2. Check detailed queue information:

    code language-bash 
    rabbitmqctl list_queues name messages messages_ready messages_unacknowledged consumers

    RabbitMQ CLI Detailed Output {width="500"}

Step 3: Process pending messages

If messages are pending in any queues, process them before proceeding.

  1. Get the list of available consumers:

    code language-bash 
    bin/magento queue:consumers:list

  2. Process consumers as a group, or by individual message queue:

    • Process consumers as a group

      code language-bash 
      bin/magento cron:run --group=consumers
      note note
      NOTE
      If cron is already running in your system, you do not need to run bin/magento cron:run --group=consumers manually. Instead, verify that messages are getting processed by checking the message counts using the commands from Step 2.

    • Process a specific message queue

      code language-bash 
      bin/magento queue:consumers:start <consumer_name> --max-messages=<number>

      For example, to process async operations:

      code language-bash 
      bin/magento queue:consumers:start async.operations.all --max-messages=1000
      note note
      NOTE
      The --max-messages parameter limits the number of messages to process before the consumer stops. Adjust this value based on your queue size.

    • Monitor message processing

      Continuously check message counts until all queues are empty:

      code language-bash 
      # Check every few seconds until 0 messages remain
watch -n 5 "rabbitmqctl list_queues name messages | grep -v '^Listing' | grep -v '0$'"

Step 4: Verify that all messages are processed

Before proceeding to the next step, ensure all queues show 0 messages. Run the verification commands from Step 2 again.

WARNING
Do not proceed to the next step if any messages remain unprocessed. Data loss may occur if you switch brokers while messages are still pending.

Step 5: Stop consumers and cron jobs

  1. Stop all running message queue consumers:

    code language-bash 
    # If using supervisor
supervisorctl stop all

# Or manually kill consumer processes
pkill -f "queue:consumers:start"

  2. Disable cron jobs:

    code language-bash 
    bin/magento cron:remove

  3. Verify cron jobs are removed:

    code language-bash 
    crontab -l

Step 6: Backup current configuration

Create a backup of your current configuration:

cp app/etc/env.php app/etc/env.php.backup.rabbitmq

Step 7: Optionally uninstall RabbitMQ

You can uninstall RabbitMQ if it is not required anymore.

Step 8: Install and configure ActiveMQ in Adobe Commerce

To complete ActiveMQ installation and configuration tasks such as configuring the STOMP protocol and verifying the connection, see the Installation and Configuration Guide.

Step 9: Reinstall cron jobs

  1. After testing completes successfully, reinstall cron jobs:

    code language-bash 
    bin/magento cron:install

  2. Verify that cron jobs are scheduled:

    code language-bash 
    crontab -l

Step 10: Disable Maintenance Mode

  1. After verifying everything is working correctly, disable maintenance mode:

    code language-bash 
    bin/magento maintenance:disable

  2. Verify that maintenance mode is disabled:

    code language-bash 
    bin/magento maintenance:status

Step 11: Monitor the system

Monitor your system for 24-48 hours after migration to ensure that all queue operations are functioning correctly:

  • Check the ActiveMQ Web Console regularly for message throughput
  • Monitor application logs for queue-related errors
  • Verify that async operations (config saves, exports, and so on) are working
  • Check cron logs to ensure that consumers are running
# Monitor system logs for queue activity
tail -f var/log/system.log | grep -i queue

# Monitor cron logs
tail -f var/log/cron.log

# Check running consumer processes
ps aux | grep "queue:consumers:start"

Rollback

If issues occur during or after migration, you can rollback to RabbitMQ:

  1. Enable maintenance mode:

    code language-bash 
    bin/magento maintenance:enable

  2. Stop all consumers and disable cron:

    code language-bash 
    pkill -f "queue:consumers:start"
bin/magento cron:remove

  3. Restore the previous configuration:

    code language-bash 
    cp app/etc/env.php.backup.rabbitmq app/etc/env.php

  4. Start RabbitMQ (if stopped):

    code language-bash 
    sudo systemctl start rabbitmq-server

  5. Clear cache:

    code language-bash 
    bin/magento cache:flush

  6. Reinstall cron:

    code language-bash 
    bin/magento cron:install

  7. Disable maintenance mode:

    code language-bash 
    bin/magento maintenance:disable

No further configuration value changes are necessary after completing the migration.

recommendation-more-help
83a60e0e-8849-4685-a8cd-c129ecd795ea