Install the Woow EMQX add-on

Why this matters

The Home Assistant add-on store does not carry Woow EMQX by default, so before you can install it you have to add the WoowTech repository to your Home Assistant. The process is not hard, but if you have not sorted out three keywords first — "host_network mode", "ports 1883/18083" and "Ingress" — what usually happens is that the add-on will not start, and you are left in front of the log with no idea why.

By the end of this chapter you will be able to do the whole thing yourself: add the repository → install → start → log in for the first time with admin/public → change the default password. You will also know what each of the five ports is for, and what to do when Mosquitto has taken a port you need.

Core concepts

Woow EMQX is a Home Assistant add-on that WOOWTECH maintains as a fork of hassio-addons/addon-emqx. It ships EMQX 5.8.9 (Open Source) on the Erlang/OTP runtime, with a built-in SQLite store for its settings. The add-on runs with host_network: true, which means it does not seal its networking into a small virtual network inside the container; it sends and receives MQTT on the ports of the Home Assistant host itself.

The upside is that other browsers, phone apps and external devices can reach ports such as 1883 and 8883 on your host directly, with nothing in between. The cost is that you now have to care about who is holding a port: if you keep Home Assistant's Mosquitto add-on, both use 1883, so the two cannot start at the same time.

The add-on also serves its admin interface through ingress mode: you can open the EMQX Dashboard straight from the Home Assistant sidebar, with no need to remember http://<host>:18083. The add-on's config.yaml already sets both ingress_port: 18083 and host_network: true.

Terms at a glance

One repo address matters here: https://github.com/WOOWTECH/Woow_ha_emqx — that is the repository source you are about to add to Home Assistant.

Hands-on

1. Add the WoowTech repository

   In Home Assistant, go to Settings → Add-ons → Add-on store, open the ⋯ menu at the top right → Add repository, paste in https://github.com/WOOWTECH/Woow_ha_emqx and click Add.

2. Install Woow EMQX

   Refresh the store, find Woow EMQX, open it and click Install (the download can take a while).

3. Start the add-on

   Check that host_network is enabled on the add-on page, then click Start. Afterwards read the log and confirm there is no "port already in use" error.

4. Open the Web UI and log in for the first time

   Click Open Web UI and log in with the user name admin and the password public. If you are asked to change the password, change it there and then to <your-new-password>, and do not use public again before you create real MQTT accounts in a later chapter.

The five ports clients connect on

Because of host_network, these five ports are open on the Home Assistant host itself. The add-on README lists the following defaults.

Day to day you only need two of them: 1883 for devices and Home Assistant, and 18083 to open the Dashboard. The rest are WebSocket and TLS options. If another service is holding one of the ports — WebRTC uses 8083, for example — you have to stop the conflicting side first, then change the port on the Dashboard's Listeners page.

First login and changing the password

The default account for the EMQX Dashboard is admin/public. The official documentation is explicit about this: the first time you log in with the default credentials, EMQX detects that you are still on the default password and forces you to change it; the new password cannot be the same as the old one, and keeping public for real use is not recommended.

This is an important first step in protecting the admin surface: the Dashboard is the way in to controlling the whole broker, so anyone who guesses admin/public can rewrite all of your authentication and authorization. In Chapter 6 you will create real MQTT accounts for your devices and Home Assistant; in this chapter you only have to change the Dashboard login password.

If you forget the new password, EMQX gives you the CLI command emqx ctl admins passwd <username> <new-password> to reset it; Chapter 18 covers the details under diagnostics and the API.

Troubleshooting

• You added the repository but Woow EMQX does not show up in the store: refresh the page, or leave the store and come back in; check that you pasted the whole URL, including the trailing Woow_ha_emqx.
• It will not start, and the log says a port is in use: the most likely cause is that the Mosquitto add-on or WebRTC is running at the same time, and both hold 1883 or 8083. Stop the conflicting service first, then start EMQX.
• The Dashboard will not open: get in through Ingress (the EMQX icon in the sidebar), or use http://<home-assistant-host>:18083 instead. Check that nothing else is holding 18083.
• Once you have changed it, really stop using public: if you were not asked to change the password on first login, this is not a fresh install; if you are still on the default credentials, change them by hand in the Dashboard's user settings.

FAQ

Official sources

• Woow EMQX add-on README (pinned commit: install, ports, first-time setup, conflicts)
• Woow EMQX config.yaml (host_network, ingress, version)
• Woow EMQX CHANGELOG.md (changes in add-on 5.9.0)
• Woow EMQX DOCS.md (user documentation)