Apache RocketMQ on AWS User Guide

Overview

Apache RocketMQ is an open-source distributed messaging and streaming platform built for low-latency, high-throughput, financial-grade reliability. It powers asynchronous decoupling, event streaming and transactional messaging across microservices. The cloudimg image installs RocketMQ 5.3.3 under /opt/rocketmq and runs it in a single-node topology as a dedicated rocketmq system user under OpenJDK 17: one NameServer (the routing registry) and one Broker (the message store and serve engine), plus the RocketMQ Dashboard (a Spring Boot web UI) fronted by nginx on TCP 80 with HTTP Basic auth. The message store lives on a dedicated EBS data volume, and a unique Dashboard password is generated on the first boot of every instance. Backed by 24/7 cloudimg support.

What is included:

• Apache RocketMQ 5.3.3 (NameServer + Broker) under /opt/rocketmq, run as the rocketmq system user
• OpenJDK 17 (headless), with the broker and nameserver JVM heaps tuned to fit the recommended instance size
• The RocketMQ Dashboard web UI, fronted by nginx on :80
• nginx HTTP Basic auth (the Dashboard has no public-facing auth) with a per-instance password in a root-only file
• A dedicated EBS data volume at /var/lib/rocketmq holding the message store, separate from the OS disk and re-provisioned with every instance
• rocketmq-namesrv.service, rocketmq-broker.service, rocketmq-dashboard.service and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

Before you deploy this image you need:

• An AWS account where you can launch EC2 instances and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access
• A VPC and subnet, with a security group allowing inbound 22/tcp from your management network and 80/tcp for the Dashboard; to connect remote producers and consumers also allow 9876/tcp (NameServer) and 10911/tcp (Broker) from the networks your clients use
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

m5.large (2 vCPU / 8 GiB RAM) is a good starting point; scale up for higher message throughput.

Connecting to your instance

SSH in as the default login user for the OS variant you launched. The cloudimg RocketMQ listing currently ships one variant:

ssh ubuntu@<instance-public-ip>

Step 1: Launch the instance from the AWS Marketplace

Sign in to the AWS Marketplace, search for Apache RocketMQ by cloudimg, and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch. Pick your Region, the recommended instance type, your VPC and subnet, and a security group that allows inbound 22 and 80 (and 9876 + 10911 if remote clients will connect). Select your EC2 key pair and launch.

Step 2: Launch from the AWS CLI

aws ec2 run-instances \
  --image-id <ami-id-from-marketplace> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <your-sg-id> \
  --subnet-id <your-subnet-id> \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=rocketmq}]'

The <ami-id-from-marketplace> is shown on the listing's launch page for your Region after you subscribe.

Step 3: Confirm the services are running

systemctl is-active rocketmq-namesrv.service rocketmq-broker.service rocketmq-dashboard.service nginx.service

All four services report active. The NameServer starts in seconds; the Broker takes a little longer as it initialises its commit log on first boot.

Step 4: Retrieve your Dashboard password

The Dashboard password is generated uniquely on the first boot of your instance and written to a root-only file:

sudo cat /root/apache-rocketmq-credentials.txt

This file contains ROCKETMQ_DASHBOARD_USER (admin) and ROCKETMQ_DASHBOARD_PASSWORD, plus the Dashboard URL and the NameServer/Broker addresses. Store the password somewhere safe.

Step 5: Check the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/health

It returns ok and is exempt from the Basic auth, so probes do not need credentials. The Dashboard itself returns 401 without credentials and 200 with the admin password:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost/

Step 6: Open the web Dashboard

Browse to http://<instance-public-ip>/ and sign in as admin with the password from Step 4. The Dashboard view shows the broker overview and live message throughput:

The Cluster view shows the broker, its address, version (V5_3_3) and produce/consume counters:

The OPS view manages the NameServer address list, the VIP-channel flag and TLS for the Dashboard's own admin client:

Step 7: Send and receive a message from the command line

RocketMQ ships a tools.sh launcher with built-in quickstart producer and consumer classes. Point them at the local NameServer and send a batch of messages:

sudo -u rocketmq env NAMESRV_ADDR=127.0.0.1:9876 ROCKETMQ_HOME=/opt/rocketmq \
  /opt/rocketmq/bin/tools.sh org.apache.rocketmq.example.quickstart.Producer 2>&1 | grep SEND_OK | tail -3

Each send prints a SendResult line with sendStatus=SEND_OK and a msgId. Now consume them back. The quickstart consumer is a long-running listener, so this example wraps it in timeout to pull for 20 seconds and then exit cleanly:

OUT=$(sudo -u rocketmq env NAMESRV_ADDR=127.0.0.1:9876 ROCKETMQ_HOME=/opt/rocketmq \
  timeout 20 /opt/rocketmq/bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer 2>&1 || true)
echo "$OUT" | grep 'Receive New Messages' | tail -3

The consumer prints Receive New Messages lines as it pulls the messages you just produced. (Run it without timeout to keep listening, and press Ctrl-C to stop.) This round-trip proves the NameServer, Broker and store are all healthy.

Step 8: Inspect the cluster with mqadmin

The mqadmin CLI talks to the NameServer and reports broker registration, topics and consumer groups:

sudo -u rocketmq env ROCKETMQ_HOME=/opt/rocketmq \
  /opt/rocketmq/bin/mqadmin clusterList -n 127.0.0.1:9876 2>/dev/null

You see the DefaultCluster with broker-a registered, its address, version and queue counts. List topics with topicList -n 127.0.0.1:9876.

Step 9: Connect remote producers and consumers

The NameServer listens on 9876/tcp and the Broker on 10911/tcp. To let external applications publish and subscribe, open those ports in your security group (restrict the source to your application subnet):

aws ec2 authorize-security-group-ingress --group-id <your-sg-id> \
  --protocol tcp --port 9876 --cidr <your-app-subnet-cidr>
aws ec2 authorize-security-group-ingress --group-id <your-sg-id> \
  --protocol tcp --port 10911 --cidr <your-app-subnet-cidr>

Point your client's NAMESRV_ADDR (or rocketmq.namesrv.addr) at <instance-address>:9876. The broker advertises itself to clients using brokerIP1, which this image sets to the instance's private IP automatically on first boot. That address is directly reachable by RocketMQ clients running in the same VPC (the normal deployment). For clients outside the VPC, reach the instance over its private address via VPC peering or a VPN, or edit brokerIP1 in /opt/rocketmq/conf/broker-cloudimg.conf to an address your clients can route to and sudo systemctl restart rocketmq-broker.

Step 10: Confirm data lives on the dedicated volume

The message store is held on the dedicated EBS data volume so it survives OS changes and can be resized independently:

findmnt /var/lib/rocketmq

The mount is backed by a separate EBS volume captured into the AMI and re-provisioned on every instance. The commit log and consume queues live under /var/lib/rocketmq/store.

Enabling HTTPS

The nginx reverse proxy terminates plain HTTP on port 80 for the Dashboard. For public exposure, put a certificate in front of it. The simplest path is to add a DNS name for the instance and use the companion cloudimg nginx-ssl-certbot image as a TLS reverse proxy, or install certbot and extend the existing nginx site with a listen 443 ssl; server block and your certificate paths. Keep the Dashboard itself bound to loopback so the only public web surface is the authenticated, TLS-terminated proxy.

Maintenance

• Configuration: the broker settings (store path, brokerIP1, cluster name, auto-create flags) are in /opt/rocketmq/conf/broker-cloudimg.conf. Edit it and sudo systemctl restart rocketmq-broker to apply changes.
• JVM heap: the broker and nameserver heaps are tuned in /opt/rocketmq/bin/runbroker.sh and runserver.sh. Increase them if you scale the instance up.
• Backups: snapshot the /var/lib/rocketmq EBS volume to capture the message store.
• Upgrades: replace the contents of /opt/rocketmq with a newer release (preserving conf/broker-cloudimg.conf) and restart the services.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.

Apache RocketMQ and the RocketMQ logo are trademarks of the Apache Software Foundation. This image is produced by cloudimg and is not affiliated with or endorsed by the Apache Software Foundation. Apache RocketMQ is distributed under the Apache License 2.0.