{"id":13587493,"url":"https://github.com/emqx/emqx-docker","last_synced_at":"2025-10-09T00:11:14.796Z","repository":{"id":38206705,"uuid":"404922749","full_name":"emqx/emqx-docker","owner":"emqx","description":"An Open-Source, Cloud-Native, Distributed MQTT Message Broker for IoT.","archived":false,"fork":false,"pushed_at":"2025-09-04T09:09:30.000Z","size":95,"stargazers_count":41,"open_issues_count":3,"forks_count":16,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-29T22:58:33.539Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emqx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-09-10T01:44:42.000Z","updated_at":"2025-09-25T14:53:17.000Z","dependencies_parsed_at":"2024-03-08T01:27:40.955Z","dependency_job_id":"5d7f1fa0-67e0-402b-b2ed-7fa6aa78873f","html_url":"https://github.com/emqx/emqx-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/emqx/emqx-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emqx%2Femqx-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emqx%2Femqx-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emqx%2Femqx-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emqx%2Femqx-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emqx","download_url":"https://codeload.github.com/emqx/emqx-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emqx%2Femqx-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000745,"owners_count":26082879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:06:14.196Z","updated_at":"2025-10-09T00:11:14.780Z","avatar_url":"https://github.com/emqx.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# EMQX\n\n## Quick reference\n\n+ **Where to get help**:\n\n\u003chttps://emqx.io\u003e or \u003chttps://github.com/emqx/emqx\u003e\n\n+ **Where to file issues:**\n\n\u003chttps://github.com/emqx/emqx/issues\u003e\n\n+ **Supported architectures**\n\n  `amd64`, `arm64v8`\n\n+ **Supported Docker versions**:\n\n  [the latest release](https://github.com/docker/docker-ce/releases/latest)\n\n## What is EMQX\n\n[EMQX](https://emqx.io/) is the world's most scalable open-source MQTT broker with a high performance that connects 100M+ IoT devices in 1 cluster, while maintaining 1M message per second throughput and sub-millisecond latency.\n\nEMQX supports multiple open standard protocols like MQTT, HTTP, QUIC, and WebSocket. It's 100% compliant with MQTT 5.0 and 3.x standard, and secures bi-directional communication with MQTT over TLS/SSL and various authentication mechanisms.\n\nWith the built-in powerful SQL-based rules engine, EMQX can extract, filter, enrich and transform IoT data in real-time. In addition, it ensures high availability and horizontal scalability with a masterless distributed architecture, and provides ops-friendly user experience and great observability.\n\nEMQX boasts more than 20K+ enterprise users across 50+ countries and regions, connecting 100M+ IoT devices worldwide, and is trusted by over 400 customers in mission-critical scenarios of IoT, IIoT, connected vehicles, and more, including over 70 Fortune 500 companies like HPE, VMware, Verifone, SAIC Volkswagen, and Ericsson.\n\n## How to use this image\n\n### Run EMQX\n\nExecute some command under this docker image\n\n```console\n$ docker run -d --name emqx emqx/emqx:${tag}\n```\n\nFor example\n\n```console\n$ docker run -d --name emqx -p 18083:18083 -p 1883:1883 emqx/emqx:latest\n```\n\nThe EMQX broker runs as Linux user `emqx` in the docker container.\n\n### Configuration\n\nAll EMQX Configuration in [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/apps/emqx/etc/emqx.conf) can be configured via environment variables.\n\nBy default, the environment variables with `EMQX_` prefix are mapped to key-value pairs in configuration files.\n\nYou can change the prefix by overriding `HOCON_ENV_OVERRIDE_PREFIX`.\n\nExample:\n\n```bash\nEMQX_LISTENERS__SSL__DEFAULT__ACCEPTORS \u003c--\u003e listeners.ssl.default.acceptors\nEMQX_ZONES__DEFAULT__MQTT__MAX_PACKET_SIZE \u003c--\u003e zones.default.mqtt.max_packet_size\n```\n\n+ Prefix `EMQX_` is removed\n+ All upper case letters is replaced with lower case letters\n+ `__` is replaced with `.`\n\nIf `HOCON_ENV_OVERRIDE_PREFIX=DEV_` is set:\n\n```bash\nDEV_LISTENER__SSL__EXTERNAL__ACCEPTORS \u003c--\u003e listener.ssl.external.acceptors\nDEV_MQTT__MAX_PACKET_SIZE              \u003c--\u003e mqtt.max_packet_size\nDEV_LISTENERS__TCP__DEFAULT__BIND      \u003c--\u003e listeners.tcp.default.bind\n```\n\nFor example, set MQTT TCP port to 1883\n\n```console\n$ docker run -d --name emqx -e DEV_LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 emqx/emqx:latest\n```\n\nPlease read more about EMQX configuration in the [official documentation](https://www.emqx.io/docs/en/v5.0/admin/cfg.html).\n\n#### EMQX node name configuration\n\n| Options                    | Default            | Mapped                    | Description                           |\n| ---------------------------| ------------------ | ------------------------- | ------------------------------------- |\n| `EMQX_NAME`                | container name     | none                      | EMQX node short name                  |\n| `EMQX_HOST`                | container IP       | none                      | EMQX node host, IP or FQDN            |\n\nThese environment variables are used during container startup phase only in [docker-entrypoint.sh](./docker-entrypoint.sh).\n\nIf `EMQX_NAME` and `EMQX_HOST` are set, and `EMQX_NODE_NAME` is not set, `EMQX_NODE_NAME=$EMQX_NAME@$EMQX_HOST`.\nOtherwise `EMQX_NODE_NAME` is taken verbatim.\n\n### Cluster\n\nEMQX supports a variety of clustering methods, see our [documentation](https://www.emqx.io/docs/en/latest/deploy/cluster/intro.html) for details.\n\nLet's create a static node list cluster from docker-compose.\n\n+ Create `docker-compose.yaml`:\n\n  ```yaml\n  version: '3'\n\n  services:\n    emqx1:\n      image: emqx/emqx:latest\n      environment:\n      - \"EMQX_NAME=emqx\"\n      - \"EMQX_HOST=node1.emqx.io\"\n      - \"EMQX_CLUSTER__DISCOVERY_STRATEGY=static\"\n      - \"EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]\"\n      networks:\n        emqx-bridge:\n          aliases:\n          - node1.emqx.io\n\n    emqx2:\n      image: emqx/emqx:latest\n      environment:\n      - \"EMQX_NAME=emqx\"\n      - \"EMQX_HOST=node2.emqx.io\"\n      - \"EMQX_CLUSTER__DISCOVERY_STRATEGY=static\"\n      - \"EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]\"\n      networks:\n        emqx-bridge:\n          aliases:\n          - node2.emqx.io\n\n  networks:\n    emqx-bridge:\n      driver: bridge\n  ```\n\n+ Start the docker-compose cluster\n\n  ```bash\n  docker-compose -p my_emqx up -d\n  ```\n\n+ View cluster\n\n  ```bash\n  $ docker exec -it my_emqx_emqx1_1 sh -c \"emqx_ctl cluster status\"\n  Cluster status: #{running_nodes =\u003e ['emqx@node1.emqx.io','emqx@node2.emqx.io'],\n                    stopped_nodes =\u003e []}\n  ```\n\n### Persistence\n\nIf you want to persist the EMQX docker container, you need to keep the following directories:\n\n+ `/opt/emqx/data`\n+ `/opt/emqx/etc`\n+ `/opt/emqx/log`\n\nSince data in these folders are partially stored under the `/opt/emqx/data/mnesia/${node_name}`, the user also needs to reuse the same node name to see the previous state. In detail, one needs to specify the two environment variables: `EMQX_NAME` and `EMQX_HOST`, `EMQX_HOST` set as `127.0.0.1` or network alias would be useful.\n\nIn if you use docker-compose, the configuration would look something like this:\n\n```YAML\nvolumes:\n  vol-emqx-data:\n    name: foo-emqx-data\n  vol-emqx-etc:\n    name: foo-emqx-etc\n  vol-emqx-log:\n    name: foo-emqx-log\n\nservices:\n  emqx:\n    image: emqx/emqx:latest\n    restart: always\n    environment:\n      EMQX_NAME: foo_emqx\n      EMQX_HOST: 127.0.0.1\n    volumes:\n      - vol-emqx-data:/opt/emqx/data\n      - vol-emqx-etc:/opt/emqx/etc\n      - vol-emqx-log:/opt/emqx/log\n```\n\nNote that `/opt/emqx/etc` contains some essential configuration files. If you want to mount a host directory in the container to persist configuration overrides, you will need to bootstrap it with [default configuration files](https://github.com/emqx/emqx/tree/master/apps/emqx/etc).\n\n### Kernel Tuning\n\nUnder Linux host machine, the easiest way is [Tuning guide](https://www.emqx.io/docs/en/latest/deploy/tune.html).\n\nIf you want tune Linux kernel by docker, you must ensure your docker is latest version (\u003e=1.12).\n\n```bash\ndocker run -d --name emqx -p 18083:18083 -p 1883:1883 \\\n    --sysctl fs.file-max=2097152 \\\n    --sysctl fs.nr_open=2097152 \\\n    --sysctl net.core.somaxconn=32768 \\\n    --sysctl net.ipv4.tcp_max_syn_backlog=16384 \\\n    --sysctl net.core.netdev_max_backlog=16384 \\\n    --sysctl net.ipv4.ip_local_port_range=1000 65535 \\\n    --sysctl net.core.rmem_default=262144 \\\n    --sysctl net.core.wmem_default=262144 \\\n    --sysctl net.core.rmem_max=16777216 \\\n    --sysctl net.core.wmem_max=16777216 \\\n    --sysctl net.core.optmem_max=16777216 \\\n    --sysctl net.ipv4.tcp_rmem=1024 4096 16777216 \\\n    --sysctl net.ipv4.tcp_wmem=1024 4096 16777216 \\\n    --sysctl net.ipv4.tcp_max_tw_buckets=1048576 \\\n    --sysctl net.ipv4.tcp_fin_timeout=15 \\\n    emqx/emqx:latest\n```\n\n\u003e REMEMBER: DO NOT RUN EMQX DOCKER PRIVILEGED OR MOUNT SYSTEM PROC IN CONTAINER TO TUNE LINUX KERNEL, IT IS UNSAFE.\n\n### Thanks\n\n+ [@je-al](https://github.com/emqx/emqx-docker/issues/2)\n+ [@RaymondMouthaan](https://github.com/emqx/emqx-docker/pull/91)\n+ [@zhongjiewu](https://github.com/emqx/emqx/issues/3427)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femqx%2Femqx-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femqx%2Femqx-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femqx%2Femqx-docker/lists"}