Master RocketMQ 5.x with Docker: From Zero to Production with Proxy

Architecture Overview and Role of Proxy

RocketMQ 5.x introduces a Proxy component that becomes a first‑class citizen. The recommended data path is Producer → Proxy → Broker . Proxy provides a unified API, gRPC support, multi‑language access, load‑balancing, and shields clients from broker routing changes.

Docker Deployment Options

Docker Compose (recommended) – one‑command startup of NameServer, Broker, Proxy and Dashboard, ideal for development, testing and quick demos.

Step‑by‑step docker run commands – more flexible and suitable for production environments where fine‑grained customization is required.

Docker Compose Full Example

Create a docker-compose.yml file with the following content:

version: '3.8'
services:
  namesrv:
    image: apache/rocketmq:5.3.1
    container_name: rmqnamesrv
    ports:
      - "9876:9876"
    networks:
      - rocketmq
    command: sh mqnamesrv
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9876"]
      interval: 10s
      retries: 3
      timeout: 5s

  broker:
    image: apache/rocketmq:5.3.1
    container_name: rmqbroker
    depends_on:
      - namesrv
    ports:
      - "10909:10909"
      - "10911:10911"
    environment:
      - NAMESRV_ADDR=rmqnamesrv:9876
      - JAVA_OPTS=-server -Xms2g -Xmx2g -Xmn1g -XX:+UseG1GC
    networks:
      - rocketmq
    volumes:
      - ./conf/broker.conf:/opt/rocketmq/conf/broker.conf
      - ./store:/home/rocketmq/store
      - ./logs:/home/rocketmq/logs
    command: sh mqbroker -c /opt/rocketmq/conf/broker.conf
    healthcheck:
      test: ["CMD", "nc", "-z", "localhost", "10911"]
      interval: 10s
      retries: 3
      timeout: 5s

  proxy:
    image: apache/rocketmq:5.3.1
    container_name: rmqproxy
    depends_on:
      - broker
      - namesrv
    ports:
      - "8080:8080"   # HTTP
      - "8081:8081"   # gRPC
    environment:
      - NAMESRV_ADDR=rmqnamesrv:9876
      - ROCKETMQ_PROXY_MODE=PRIMARY
      - PROXY_CLUSTER_NAME=DefaultCluster
    networks:
      - rocketmq
    command: sh mqproxy

  dashboard:
    image: apacherocketmq/rocketmq-dashboard:latest
    container_name: rocketmq-dashboard
    depends_on:
      - namesrv
    ports:
      - "9000:8080"
    environment:
      - JAVA_OPTS=-Drocketmq.namesrv.addr=rmqnamesrv:9876
    networks:
      - rocketmq

networks:
  rocketmq:
    driver: bridge

Broker Configuration (broker.conf)

brokerClusterName = DefaultCluster
brokerName = broker-a
brokerId = 0
deleteWhen = 04
fileReservedTime = 48
brokerRole = ASYNC_MASTER
flushDiskType = ASYNC_FLUSH
# The IP address that clients will use to reach the broker. Use the host's real LAN or public IP, never 127.0.0.1 or the container's internal IP.
brokerIP1 = <em>host_real_ip</em>
listenPort = 10911
autoCreateTopicEnable = true
autoCreateSubscriptionGroup = true

Starting the Cluster

Run the compose file: docker-compose up -d Check the containers and logs:

docker ps
docker logs -f rmqnamesrv
docker logs -f rmqbroker
docker logs -f rmqproxy

Successful startup prints messages such as “Name Server boot success...” and “The broker boot success...”.

Message Send/Receive Verification

Enter the broker container and run the official quick‑start examples:

docker exec -it rmqbroker bash
sh tools.sh org.apache.rocketmq.example.quickstart.Producer
sh tools.sh org.apache.rocketmq.example.quickstart.Consumer

Cross‑Host / Public Network Deployment

When the broker runs on a machine that clients access remotely, brokerIP1 must be set to the machine’s reachable LAN or public IP. An incorrect value is the most common cause of the error “connect to broker failed”.

Data Persistence Directories

store/commitlog

– message data files store/consumequeue – queue index files store/index – message index files logs – Broker and Proxy logs

Mount these directories in the compose file (as shown in the volumes section) to avoid data loss across container restarts.

JVM Optimization for Production

Broker performance relies heavily on the OS page cache. Allocate roughly 4 GB of heap on a 16 GB machine, leaving the remainder for the page cache.

environment:
  - JAVA_OPTS=-server -Xms4g -Xmx4g -Xmn1g -XX:+UseG1GC

Production guideline: on a server with 16 GB RAM, configure the broker JVM with 4 GB heap.

Monitoring Stack

The Dashboard service is included in the compose file and can be accessed at http://<em>host_ip</em>:9000. An optional Prometheus exporter can be started with:

docker run -d -p 9090:9090 rocketmq-exporter

Common Errors and Fixes

No route info for topic – Create the topic before producing or consuming:

./mqadmin updateTopic -t YourTopic -n rmqnamesrv:9876 -c DefaultCluster

connect to broker failed – Verify that brokerIP1 is set to the host’s real IP.

High send latency – Use asynchronous disk flush (set flushDiskType=ASYNC_FLUSH).

Message duplication – RocketMQ guarantees at‑least‑once delivery. Use transactional messages or deduplicate with a unique business identifier.

Custom Docker Image (When Extensions Are Needed)

FROM eclipse-temurin:17-jre
ENV ROCKETMQ_VERSION=5.3.1
RUN wget https://archive.apache.org/dist/rocketmq/${ROCKETMQ_VERSION}/rocketmq-${ROCKETMQ_VERSION}-bin-release.zip \
    && unzip rocketmq-${ROCKETMQ_VERSION}-bin-release.zip \
    && mv rocketmq-${ROCKETMQ_VERSION} /opt/rocketmq \
    && rm *.zip
WORKDIR /opt/rocketmq
COPY broker.conf /opt/rocketmq/conf/broker.conf
CMD ["sh", "mqbroker", "-c", "/opt/rocketmq/conf/broker.conf"]

Key Takeaways for Production‑Ready RocketMQ 5.x

Deploy the Proxy component; clients must not connect directly to a broker.

Set brokerIP1 to the host’s real LAN or public IP.

Use Docker Compose for the simplest full‑stack startup.

Mount store and logs directories to persist data.

Allocate JVM memory wisely and keep enough RAM for the OS page cache.

Monitor the cluster with the built‑in Dashboard and optionally a Prometheus exporter.

Approximately 90 % of connection failures stem from an incorrect brokerIP1 setting.