Skip to content

Deploy with Docker

This section guides you through the quick installation and running of NanoMQ using the official Docker image. You'll also learn how to load custom configurations in the Docker deployment mode. This section uses the latest version of NanoMQ as an example. If you're interested in trying out other versions, head over to the NanoMQ Download Page.

Docker Images

NanoMQ currently provides three Docker deployment versions, each with distinct functionalities as detailed in the table below:

FunctionNanoMQ Basic Version (default)NanoMQ Slim VersionNanoMQ Full Version
MQTT Broker Function
Rule Engine
MQTT over TCP Bridging
MQTT over QUIC Bridging
AWS Bridging *
ZMQ Gateway
SOME/IP Gateway
DDS Gateway
Bench Benchmark Tools

[^*]: AWS bridging is currently unavailable with Docker deployment. To use AWS bridging, please build NanoMQ from the source code.

Based on your requirements, you can select the Docker image to download. For instance, using latest in the command below will download the most recent basic deployment version.

docker pull emqx/nanomq:latest

To get the Slim or Full version of a certain release, don't forget to include the release number.

For the Slim version:

docker pull emqx/nanomq:0.18.2-slim

or Full version

docker pull emqx/nanomq:0.18.2-full

For more information about the official NanoMQ image, please visit Docker Hub - nanomq.

Run NanoMQ with Docker

To start NanoMQ, execute the following command:

docker run -d --name nanomq -p 1883:1883 -p 8083:8083 -p 8883:8883 emqx/nanomq:latest

Load Custom Configurations

NanoMQ also allows loading custom configurations through a configuration file or environment variables.

Load through Configuration File

If you wish to start NanoMQ via a configuration file:

  • Modify /etc/nanomq.conf in the Docker container

  • Copy the modified configuration file from your local machine to the Docker container's /etc/nanomq.conf path using the docker cp command:

    docker cp nanomq.conf nanomq:/etc/nanomq.conf

Here's an example configuration for enabling MQTT bridging with TLS connection. For more explanations on NanoMQ's configurations, please refer to the Configuration Guide:

bash {
	server = "mqtt-tcp://"
	proto_ver = 4
	clean_start = true
	keepalive = 60s
	forwards = [
			remote_topic = "fwd/topic1"
			local_topic = "topic1"
			qos = 1
			remote_topic = "fwd/topic2"
			local_topic = "topic2"
			qos = 2
	subscription = [
			remote_topic = "cmd/topic1"
			local_topic = "topic3"
			qos = 1
			remote_topic = "cmd/topic2"
			local_topic = "topic4"
			qos = 2
	max_parallel_processes = 2 
	max_send_queue_len = 1024
	max_recv_queue_len = 1024

After updating the configuration file, you can start NanoMQ with the following command:

docker run -d -p 1883:1883 -v {YOU LOCAL PATH}: /etc \
            --name nanomq  emqx/nanomq:latest

Load through Environment Variables

NanoMQ also supports custom configurations through environment variables. Here is a list of supported environment variables:

VariablesData TypeDescription
NANOMQ_DAEMONBooleanDaemon mode (default: False)
NANOMQ_NUM_TASKQ_THREADIntegerNumber of task queue threads (range: 0 ~ 256)
NANOMQ_MAX_TASKQ_THREADIntegerMaximum task queue threads (range: 0 ~ 256)
NANOMQ_PARALLELLongNumber of parallel operations
NANOMQ_PROPERTY_SIZEIntegerMaximum property length
NANOMQ_MSQ_LENIntegerQueue length
NANOMQ_QOS_DURATIONIntegerQoS message interval
NANOMQ_ALLOW_ANONYMOUSBooleanAllow anonymous login (default: True)
NANOMQ_WEBSOCKET_ENABLEBooleanEnable WebSocket listening (default: True)

NANOMQ_HTTP_SERVER_ENABLEBooleanEnable HTTP server listening (default: False)
NANOMQ_HTTP_SERVER_PORTIntegerHTTP server listening port (default: 8081)
NANOMQ_HTTP_SERVER_USERNAMEStringUsername to access HTTP service
NANOMQ_HTTP_SERVER_PASSWORDStringPassword to access HTTP service
NANOMQ_TLS_ENABLEBooleanEnable TLS listening (default: False)
NANOMQ_TLS_CA_CERT_PATHStringPath to TLS CA certificate data
NANOMQ_TLS_CERT_PATHStringPath to TLS Cert certificate data
NANOMQ_TLS_KEY_PATHStringPath to TLS private key data
NANOMQ_TLS_KEY_PASSWORDStringPassword for TLS private key
NANOMQ_TLS_VERIFY_PEERBooleanVerify client certificate (default: False)
NANOMQ_TLS_FAIL_IF_NO_PEER_CERTBooleanDeny connection without a certificate, used with tls.verify_peer (default: False)
NANOMQ_LOG_TOStringLog output types, separated by vertical line `
NANOMQ_LOG_LEVELStringLog level: trace, debug, info, warn, error, fatal
NANOMQ_LOG_DIRStringPath to store log files (effective when output is file)
NANOMQ_LOG_FILEStringLog file name (effective when output is a file)
NANOMQ_LOG_ROTATION_SIZEStringMaximum occupied space per log file;

Unit: `KB
NANOMQ_LOG_ROTATION_COUNTIntegerMaximum number of rotated log files;
Default: 5
NANOMQ_CONF_PATHStringNanoMQ configuration file path (default: /etc/nanomq.conf)

Example: Specify the configuration file path through environment variables

docker run -d -p 1883:1883 -e NANOMQ_CONF_PATH="/usr/local/etc/nanomq.conf" \
            [-v {LOCAL PATH}:{CONTAINER PATH}] \
            --name nanomq emqx/nanomq:0.18.2-slim

Performance Tunning

To achieve better performance, you can adjust the following configurations in the nanomq.conf file:

Configuration ItemTypeDescription
system.num_taskq_threadIntegerNumber of task queue threads used, recommended to match the number of CPU cores.
system.max_taskq_threadIntegerMaximum number of task queue threads that can be used, recommended to match the number of CPU cores.
system.parallelLongNumber of parallel processing tasks, recommended to match the number of CPU cores.
mqtt.session.msq_lenIntegerLength of the Inflight window/queue for resending messages. It's recommended (depending on the memory) to set it to the maximum value: 65535.


Suppose you are working with a 4-core operating system, you can set as follows for optimized performance. The updates will take effect after NanoMQ restarts.

system.num_taskq_thread = 4
system.max_taskq_thread = 4
system.parallel = 8
mqtt.session.msq_len = 65535