Installation Manual

# Preface

This document is an installation guide for Apusic Distributed Message Queue for MQTT (Apusic Distributed Message Queue, referred to as: ADMQ for MQTT), providing guidance on the installation and deployment process of the product in various deployment modes (including standalone and cluster) across different operating systems and container environments, along with related configuration instructions.

# Target Audience

This document is intended for IT information business leaders, R&D managers, software project managers, software architects, and operations engineers.

To learn more about ADMQ for MQTT, please refer to the following ADMQ for MQTT product documentation set:

No.	Document	Description
1	Apusic Distributed Message Queue for MQTT Quick Start Guide	Briefly introduces how to quickly get started with ADMQ for MQTT.
2	Apusic Distributed Message Queue for MQTT Installation Guide	Details how to install ADMQ for MQTT on various operating systems, as well as service start/stop operations.
3	Apusic Distributed Message Queue for MQTT Message Engine User Manual	Details the use, configuration, and management of ADMQ for MQTT message engine features and supporting tools.
4	Apusic Distributed Message Queue for MQTT Console User Manual	Details the use and operation of the ADMQ for MQTT console.
5	Apusic Distributed Message Queue for MQTT Development Guide	Details how to develop ADMQ for MQTT client applications in various development languages.
6	Apusic Distributed Message Queue for MQTT Migration Guide	Details the migration from MQTT Broker to ADMQ for MQTT.
7	Apusic Distributed Message Queue for MQTT Operations Manual	Details monitoring, operations, and security hardening for ADMQ for MQTT.
8	Apusic Distributed Message Queue for MQTT Performance Optimization Guide	Details performance tuning for ADMQ for MQTT.

# Technical Support

ADMQ for MQTT provides comprehensive technical support services. You can obtain technical support through the following channels:

Website: www.apusic.com
Phone: 400-855-5800
Email: support@apusic.com
Kingdee Cloud Community: https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

When seeking technical support, please provide the following information:

Your name
Company information and contact details
Operating system and its version
Product version number
Detailed information such as logs and screenshots of the exception or error

ADMQ for Kafka supports deployment through the console. Please refer to the "Apusic Distributed Message Queue V2.0.6_Unified Console User Manual.pdf", [Quick Start] section.

# Environment Preparation

# System Requirements

Component	Minimum Requirement	Recommended Configuration
CPU	4 cores	8 cores or more
Memory	8 GB	16 GB or more
Disk	100 GB SSD	500 GB or more SSD
Network	1 Gbps	10 Gbps
Operating System	Linux (CentOS 7+, Ubuntu 18.04+, Kylin, UnionTech)	-

# Dependency Software

Software	Version Requirement	Description
OpenSSL	1.1.1+	SSL/TLS encryption dependency
Java	1.8+	Console runtime dependency (built-in)

# Network Requirements

Port	Purpose	Description
1883	MQTT TCP	Standard MQTT access
8883	MQTT over SSL	Encrypted MQTT access
8083	MQTT over WebSocket	WebSocket access
8084	MQTT over WSS	Encrypted WebSocket access
14567	MQTT over QUIC	QUIC protocol access
18083	MQTT Http API	Management backend API
4370	Inter-node cluster communication	Inter-node cluster communication
5370	Inter-node cluster communication (SSL)	Inter-node cluster communication (SSL)

# Standalone Deployment

# Installing ADMQ for MQTT

1. Modify Hostname

Requires FQDN (Fully Qualified Domain Name): e.g., mqtt.apusic.com

 # View hostname
 hostname
 # Modify hostname
 hostname mqtt.apusic.com

1
2
3
4

2. Extract Installation Package

# Extract installation package
mkdir -p /apusic
tar zxvf ADMQ-V2.0.6.587-MQTT-20260617.tar.gz -C /apusic/
cd /apusic/admq-mqtt

1
2
3
4

3. Modify Node Name, Listener Port, etc. (Optional)

vi config/mqtt.conf
---
# Node name, change name to FQDN
node {
  name = "emqx@mqtt.apusic.com"
  cookie = "mqttpnuvjvgg"
}

# MQTT TCP listener
listeners.tcp.default {
  bind = "10.0.0.196:1883"
  max_connections = 1024000
}

# WebSocket listener
listeners.ws.default {
  bind = "10.0.0.196:8083"
  max_connections = 1024000
}

# WebSocket over TLS listener
listeners.wss.default {
  bind = "10.0.0.196:8084"
  max_connections = 512000
}
---

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

4. License Authorization

Upload the obtained license.xml file to the deployment root directory

# Confirm file location
ls -l /apusic/admq-mqtt/license.xml

1
2

5. Start Service

bin/admq-daemon start mqtt server

6. Service Verification

Check Process Status

ps -ef | grep admq-mqtt

Check Port Listening

Use netstat to confirm whether port 1883 is in LISTEN state:

ss -nltp | grep 1883

Expected output:

# Cluster Deployment

# Cluster Architecture Description

ADMQ for MQTT supports the following cluster modes:

Cluster Mode	Node Count	Description
Regular Cluster	3+	Stateless node cluster, supports horizontal scaling
High Availability Cluster	3+	Multi-node deployment, automatic failover

# Cluster Deployment Steps

1. Install ADMQ for MQTT on Each Node

Refer to the standalone installation steps to install ADMQ for MQTT on each node, but do not start yet.

Note: Each node's hostname must be set to a different domain name.

2. Configure hosts File on Each Node

# /etc/hosts
192.168.1.101 mqtt1.apusic.com
192.168.1.102 mqtt2.apusic.com
192.168.1.103 mqtt3.apusic.com

1
2
3
4

3. Configure Erlang Cookie on Each Node

# Create data directory
cd /apusic/admq-mqtt
mkdir -p data
# Set Erlang Cookie
echo "mqttpnuvjvgg" > data/.erlang.cookie

1
2
3
4
5

4. Configure Cluster Discovery on Each Node

Below is a configuration example for one node.

# Node name (different per machine, format: emqx@IP or hostname)
node {
    name = "emqx@mqtt1.apusic.com"
    cookie = "mqttpnuvjvgg"   # Must match the Cookie from the previous step
}

# Cluster configuration (identical on all nodes)
cluster {
    discovery_strategy = static
    static {
        seeds = ["emqx@mqtt1.apusic.com", "emqx@mqtt2.apusic.com", "emqx@mqtt3.apusic.com"]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

5. Start Services on Each Node

bin/admq-daemon start mqtt server

6. Verify Cluster Status

bin/admq mqtt admin ctl cluster status

# Common Issues and Troubleshooting

# Service Startup Failure

Possible Cause	Solution
Port Conflict	Check if ports 1883, 8883, 8083, 8084, 18083 are occupied
Insufficient Permissions	Ensure admq-mqtt directory permissions are correct
Insufficient Memory	Check system memory, ensure minimum requirements are met

# Cluster Join Failure

Possible Cause	Solution
Erlang Cookie Mismatch	Ensure .erlang.cookie content is consistent across all nodes
Network Unreachable	Check network connectivity and firewall settings between nodes
Hostname Resolution Failure	Ensure /etc/hosts or DNS configuration is correct

# Client Connection Failure

Possible Cause	Solution
Listener Not Started	Check the listener management page to confirm the listener is enabled
Authentication Failure	Check username/password and authenticator configuration
Insufficient ACL Permissions	Check if ACL rules allow access to the corresponding topic
Firewall Blocking	Open MQTT-related ports

编辑页面

#Installation Guide

← Technical Specification Quick Start→

Installation Manual

# Preface

# Target Audience

# Related Documents

# Technical Support

# Environment Preparation

# System Requirements

# Dependency Software

# Network Requirements

# Standalone Deployment

# Installing ADMQ for MQTT

# Cluster Deployment

# Cluster Architecture Description

# Cluster Deployment Steps

# Common Issues and Troubleshooting

# Service Startup Failure

# Cluster Join Failure

# Client Connection Failure