EMQX Guide

Standalone Agent Handbook · EMQX 5.8.9

The working spec for researching, writing and delivering the 22-chapter EMQX guide

Hand this handbook straight to a research or writing agent. The factual boundary is fixed: EMQX 5.8.9, the official docs at docs.emqx.com/en/emqx/v5.8, and for the add-on, WOOWTECH/Woow_ha_emqx — specifically its emqx/ directory — is the authority.

Role, audience and hard limits

Your job

  • Write only the claims you can back with the official v5.8 docs, the Woow_ha_emqx source, or read-only observation on a live instance.
  • Write in US English and address the reader as you. Explain the term first, then give a home setup, and write the steps last.
  • Describe the system as an "MQTT broker", not as a "platform that does everything"; keep clustering to concepts and monitoring.
  • Explicitly state the menu path, the default and the maturity of every feature.

What you must not do

  • Do not present the "Modules" and "Data Bridge" of EMQX 4.x as the recommended 5.x wording.
  • Do not treat add-on 5.9.0 as an EMQX version (5.9.0 only adds an ngrok TCP tunnel).
  • Do not run Create, Delete, Save, Kick, Disconnect or any other state-changing action to get a screenshot.
  • Do not expose MQTT passwords, client IDs, API keys, ngrok authtokens, TLS private keys or connection strings.

Source precedence and handling conflicts

  1. Woow_ha_emqx source / README: highest precedence, for add-on install, env_vars, host_network and port facts.
  2. EMQX v5.8 official docs: the user-facing facts — Dashboard modules, defaults, Authentication, ACL, Listener, Rule, Connector and the like.
  3. Read-only observation on a live instance: it proves only "what this one environment shows". On its own it cannot prove that something is generally supported, and you must never create or delete a setting on a live system.
  4. Release notes for the same version: use them for version behavior and limits. Where they disagree with the docs, follow the official source you can reach, and note it.
Conflict rule: do not reconcile the sources yourself. Record the claim, source A, source B, the conclusion you adopted, and what is still unverified; when you cannot resolve it, downgrade the text to a limitation or to something still to be verified.

Working from a feature manifest

Build the feature list before you research, and write the chapters after that. Every row carries at least: feature_id, name, chapter, maturity, source, verification status, limitations and a security note.

feature_id: [stable-id]
version: 5.8.9
channel: [ga | experimental | concept-only]
dashboard_module: [yes | no]
security: [configure in the UI | conceptual]
evidence:
  - [official docs URL]
limitations: [limitations]
redact: [fields to redact]

Read-only screenshots and redaction

  1. Plan: write down the purpose of the screenshot, the page, the UI state it has to prove, and the fields that could be sensitive.
  2. Read-only walkthrough: open only tabs, searches and expandable blocks that have no side effects; no button that changes state.
  3. Isolate the raw files: the first capture goes only into the gitignored artifacts/raw-screenshots/.
  4. Redact: redact MQTT passwords, client IDs, usernames, API keys, ngrok authtokens, TLS private keys, connection strings and private IP addresses.
  5. Two-person check: a second person checks the image, the file name, the EXIF data and the surrounding text at 100% zoom, and only then does it go into the public assets.
Hard line: do not press Create, Delete, Save or Kick for a "better-looking screen". When you have no screenshot, use text and a schematic you can verify; do not imitate the product UI or its logo.

Chapter assignments and the required skeleton

PartChaptersCore deliverable
Basics01–04What it is, installing, the Dashboard, the MQTT mental model.
Access control05–08Connecting, Authentication, Authorization, Listeners and TLS.
Rules and integrations09–13Rule Engine, actions, connectors, sinks and sources, Home Assistant integration.
Operations14–22Clients, monitoring, messages, configuration, Logs/API, ngrok, backup, security, troubleshooting.

The required skeleton for every chapter

Factual, security, editorial and accessibility review

Factual review

  • Mark the verifiable claims and their sources paragraph by paragraph; check versions, defaults and UI paths one by one.
  • Search for "always", "complete", "all", "guaranteed" and "in every case", and ask for evidence or a rewrite.
  • Confirm that add-on version 5.9.0 and EMQX 5.8.9 are named consistently.

Security review

  • Run the sensitive-data scan, then check by hand for passwords, tokens, IP addresses and hostnames.
  • Before any high-risk action there must be a backup, a stated impact, an approval and a rollback.
  • Do not describe authentication as protection against everything; state the risk before exposing 1883.

Editorial review

  • US English, address the reader as you, no emoji, no translationese.
  • Define each technical term on first use, then keep the same wording.
  • Tables and code scroll horizontally on a phone.

Accessibility review

  • Heading levels, landmarks, link text and table headers are semantically correct.
  • Keyboard focus is visible, and interactive targets are at least 44px.
  • At 320/360px the page does not scroll horizontally.

Verification commands and handling failures

node scripts/build_nav.js --check
node scripts/check_links.js
node scripts/check_content.js
node scripts/check_sensitive.js
node scripts/test_checks.js

Deployment and delivery

  1. Freeze the fact baseline: confirm that EMQX 5.8.9, add-on 5.9.0 and the manifest agree.
  2. Full build check: run the navigation, link, content, sensitive-data and manifest checks.
  3. Preview environment: test the root and the project subpath with the same base path GitHub Pages uses.
  4. Human acceptance: a second pass over desktop, 320px, 360px, keyboard use and sensitive content.
  5. Atomic commit: commit only the approved scope, and record the SHA, the summary of the change, the verification output and the rollback.
  6. Post-release smoke test: check the four cards on the home page, the 22-chapter contents, the three handbooks, the OG image, the 404 page and the external sources.

Pinned sources