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

Message broker (ActiveMQ Artemis)

Adobe Commerce also supports the ActiveMQ Artemis open-source message broker through the Simple Text Oriented Messaging Protocol (STOMP). It delivers a reliable and scalable messaging system, offering flexibility for STOMP-based integrations.

Message queues provide an asynchronous communications mechanism in which the sender and the receiver of a message do not contact each other. Nor do they need to communicate with the message queue at the same time. When a sender places a message in a queue, it is stored until the recipient receives them.

The message queue system must be established before you install Adobe Commerce. The basic sequence is:

Install Apache ActiveMQ Artemis

You can install ActiveMQ Artemis using either Docker (recommended for development) or manual installation (recommended for production).

Option 1: Docker Installation (recommended for development)

Prerequisites

Ensure Docker is installed and running on your system.

Installation steps

Docker management commands

# Check container status
docker ps | grep artemis

# View logs
docker logs artemis

# Stop the container
docker stop artemis

# Start the container
docker start artemis

# Remove the container
docker rm artemis

Accessing services

Once the Docker container is running, you can access:

Option 2: Manual installation on Ubuntu/CentOS

Prerequisites

Ensure Java 17 or higher is installed (required for ActiveMQ Artemis 2.42.0+).

Installation steps

Configure ActiveMQ Artemis

Review the official ActiveMQ Artemis documentation to configure and manage the broker. Pay attention to the following items:

Key Configuration Files

Enable STOMP Protocol

Check /var/lib/artemis-instance/etc/broker.xml to ensure STOMP acceptor is configured:

<acceptors>
   <acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;amqpMinLargeMessageSize=102400;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE;useEpoll=true;amqpCredits=1000;amqpLowCredits=300;amqpDuplicateDetection=true</acceptor>
   <acceptor name="stomp">tcp://0.0.0.0:61613?protocols=STOMP</acceptor>
   <acceptor name="stomp-ssl">tcp://0.0.0.0:61617?protocols=STOMP;sslEnabled=true;keyStorePath=/path/to/keystore.jks;keyStorePassword=password</acceptor>
</acceptors>

To enable SSL on STOMP you must add the stomp-ssl acceptor explicitly.

Install with ActiveMQ Artemis and connect

If you install Adobe Commerce after you install ActiveMQ Artemis, add the following command-line parameters during installation:

--stomp-host="<hostname>" --stomp-port="61613" --stomp-user="<user_name>" --stomp-password="<password>"

Where:

Connect ActiveMQ Artemis

If you already have an Adobe Commerce instance with RabbitMQ (AMQP) configuration in the <install_directory>/app/etc/env.php file and you want to connect it to ActiveMQ, replace the queue section with the STOMP so that it is similar to the following:

'queue' =>
  array (
    'stomp' =>
    array (
      'host' => 'activemq.example.com',
      'port' => '61613',  // SSL STOMP port (default 61617, non-SSL is 61613)
      'user' => 'magento',
      'password' => 'magento',
      // Performance tuning options
      'heartbeat_send' => 10000,     // 10 seconds // Optional
      'heartbeat_receive' => 10000,  // 10 seconds // Optional
      'read_timeout' => 250000       // 250ms // Optional
     ),
  ),

You can also set ActiveMQ configuration values using the bin/magento setup:config:set command (remove the AMQP configuration if it exists in the app/etc/env.php file):

bin/magento setup:config:set --stomp-host="activemq.example.com" --stomp-port="61613" --stomp-user="magento" --stomp-password="magento"

After running the command or updating the <install_directory>/app/etc/env.php file with STOMP configuration values, run bin/magento setup:upgrade to apply the changes and create the required queues in ActiveMQ.

Configure SSL

To configure support for SSL, edit the ssl and ssl_options parameters in the <install_directory>/app/etc/env.php file so that they are similar to the following:

'queue' =>
  array (
    'stomp' =>
    array (
      'host' => 'activemq.example.com',
      'port' => '61617',  // SSL STOMP port (default 61617, non-SSL is 61613)
      'user' => 'magento',
      'password' => 'magento',
      'ssl' => 'true',
      'ssl_options' => [
            'cafile' => '/etc/pki/tls/certs/DigiCertCA.crt',
            'local_cert' => '/path/to/magento/app/etc/ssl/test-activemq.crt', // Optional: Client certificate for mutual SSL
            'local_pk' => '/path/to/magento/app/etc/ssl/test-activemq.key', // Optional: Client private key for mutual SSL
            'passphrase' => 'client_key_password', // Optional: Passphrase for client private key
            'verify_peer' => true,
            'verify_peer_name' => true,
            'allow_self_signed' => false
       ],
      // Performance tuning options
      'heartbeat_send' => 10000,     // 10 seconds // Optional
      'heartbeat_receive' => 10000,  // 10 seconds // Optional
      'read_timeout' => 250000       // 250ms // Optional
     ),
  ),

SSL Configuration Options

Development SSL Configuration

For development environments, you can use relaxed SSL settings:

'ssl_options' => [
    'verify_peer' => false,
    'verify_peer_name' => false,
    'allow_self_signed' => true
]

Performance tuning

ActiveMQ Artemis offers several performance tuning options:

'queue' =>
  array (
    'stomp' =>
    array (
      'host' => 'activemq.example.com',
      'port' => '61613',
      'user' => 'artemis',
      'password' => 'artemis',
      // Performance options
      'heartbeat_send' => 10000,      // Send heartbeat every 10 seconds
      'heartbeat_receive' => 10000,   // Expect heartbeat every 10 seconds
      'read_timeout' => 250000,       // 250ms read timeout
     ),
  ),

Monitoring and management

Web console

ActiveMQ Artemis provides a web-based management console accessible at:

Troubleshooting

Common issues

Verify STOMP connection

Test STOMP connection using telnet:

telnet localhost 61613

You should see a connection established. To test with a STOMP command:

# Test basic STOMP connection
echo -e "CONNECT\nhost:localhost\n\n\x00" | telnet localhost 61613

Expected output should show connection established and STOMP protocol response.

Start the message queue consumers

After you have connected Adobe Commerce and ActiveMQ Artemis, you must start the message queue consumers. See Configure message queues for details.