Skip to content

docs: clarify EMQX broker dependency and dependent features #7759

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dimitrieh wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs: clarify EMQX broker dependency and dependent features #7759

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fe0eaab
docs: clarify EMQX broker dependency and dependent features
dimitrieh Jul 6, 2026
cbce4c8
docs: address broker review feedback
dimitrieh Jul 6, 2026
8253eed
docs: keep broker options table at its original location
dimitrieh Jul 6, 2026
5f9c8a6
docs: trim implementation detail from broker docs
dimitrieh Jul 6, 2026
700c4f4
Merge branch 'main' into docs-broker-emqx-clarification
dimitrieh Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 18 additions & 15 deletions docs/install/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,18 +113,6 @@ Option | Description
`driver.options.customHostname.ingressClass` | The name of the Ingress Class that should be used for the custom hostname. Default: not set
`driver.options.customHostname.certManagerIssuer` | The name of the CertManager ClusterIssuer to provision HTTPS certificates for custom hostnames. Default: not set

## MQTT Broker configuration

By default, the platform runs without an MQTT broker. This restricts some features
in the platform, such as the Project Nodes, Device Actions and Remote Device Editing.

If a broker has been setup in the platform, the following configuration is required:

Option | Description
--------------|------------
`broker.url` | The url for the platform to access the broker. For example: `mqtt://localhost:4800`.
`broker.public_url` | The url used by devices to connect to the broker, if different to `broker.url`. For example, this may require devices to use WebSockets instead: `ws://localhost:4881`.

Comment on lines -123 to -127

@hardillb hardillb Jul 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These configuration options are still valid. why have you removed them?

## Email configuration

By default, email is disabled. This restricts some features in the platform around
Expand Down Expand Up @@ -218,11 +206,26 @@ Option | Description

## MQTT Broker configuration

The platform depends on the [Mosquitto MQTT Broker](https://mosquitto.org/) to
provide real-time messaging between devices and the platform.
The platform uses an MQTT broker to provide real-time messaging between devices,
Node-RED instances and the platform. The broker shipped with the platform's
Docker Compose and Kubernetes installations is [EMQX](https://www.emqx.io/): the
Docker Compose installation includes it by default, and the Helm chart deploys it
when the broker is enabled (`forge.broker.enabled`), which requires the
[EMQX Operator](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html#install-emqx-operator)
to be installed on the cluster.

This is currently an *optional* component - the platform will work without the
broker, but some features will not be available.
broker, but some features will not be available:

- Without a broker: Project Nodes, Device Actions and Remote Device Editing are unavailable.
- The following features additionally require the platform broker to be EMQX:
the [Team Broker](/docs/user/teambroker.md), [FlowFuse Expert](/docs/user/expert/)
and live device log and performance views in the platform UI.

[Mosquitto](https://mosquitto.org/) is supported at a legacy level for existing
installations that manage their own broker: core platform messaging works, but the
EMQX-dependent features listed above are unavailable. Replacing the platform broker
with a different customer-supplied broker is not supported.

Option | Description
---------------|--------------
Expand Down
2 changes: 1 addition & 1 deletion docs/install/kubernetes/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ Before you begin, ensure you have the following:
- [Digital Ocean](digital-ocean.md)
- MicroK8s
5. **Ingress Controller:** [The Traefik](https://doc.traefik.io/traefik/) installed on the cluster.
6. **EMQX Operator:** This is required to install the required MQTT broker when the Team Broker features are enabled. Instructions for installing the operator can be found [here](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html#install-emqx-operator)
6. **EMQX Operator:** This is required to install the platform's MQTT broker when the broker is enabled. Instructions for installing the operator can be found [here](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html#install-emqx-operator)

For a production-ready environment, we also recommend:
* **Database:** Prepare dedicated database on a external database server (see [FAQ](#how-to-use-external-database-server%3F) for more details)
Expand Down
14 changes: 14 additions & 0 deletions docs/upgrade/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,20 @@ Details of how to upgrade can be found for each deployment model:
To upgrade the version of Node-RED your Instances run (for example, moving to
Node-RED 5.0), see [Upgrading the Node-RED version](./nodered-version.md).

### Upgrading to 2.31.2

#### Kubernetes: MQTT broker is now EMQX

From Helm chart v2.78.0 (FlowFuse 2.31.2), the chart deploys [EMQX](https://www.emqx.io/)
as the platform MQTT broker, replacing Mosquitto. The migration happens automatically as
part of upgrading the chart; it is not possible to stay on Mosquitto when using the Helm
chart. If the broker is enabled, the
[EMQX Operator](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html)
must be installed on the cluster before upgrading, otherwise the upgrade will fail.

See [MQTT Broker configuration](../install/configuration.md#mqtt-broker-configuration)
for which platform features depend on the broker.

### Upgrading to 2.6.0

#### Required AWS EKS configuration change
Expand Down
2 changes: 2 additions & 0 deletions docs/user/expert/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ FlowFuse Expert is the AI built into FlowFuse and the Node-RED editor. It is not

**FlowFuse Expert is automatically installed and available in all hosted and remote instances running within or connected to FlowFuse**, no manual installation or configuration required. For self-hosted Enterprise customers, FlowFuse Expert can be enabled on request. [Contact us](https://flowfuse.com/contact-us/) to get it set up on your infrastructure.

> **Note:** On self-hosted installations, FlowFuse Expert requires an Enterprise license and the platform's EMQX-based MQTT broker with the Team Broker capability enabled in the platform configuration (see [MQTT Broker configuration](/docs/install/configuration.md#mqtt-broker-configuration)); installations running without EMQX cannot enable Expert.

## Managing AI Features

**Team owners** can enable or disable all AI features for their team from the team settings page. When disabled, the Expert chat panel with all AI feature will get removed for that team. Running instances need to be restarted for the change to take full effect.
Expand Down
4 changes: 3 additions & 1 deletion docs/user/teambroker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ navTitle: Team Broker

When FlowFuse is deployed with an Enterprise license from v2.11.0 onwards comes with the option to enable a MQTT broker for each Team.

This is a single shared MQTT broker, but each team has their own separate topic space and the ability to provision credentials for clients.
This is a single shared MQTT broker, but each team has their own separate topic space and the ability to provision credentials for clients. It removes the need to install and manage a broker of your own.

If your company already operates its own MQTT broker, that broker can also be connected to FlowFuse as an external broker to browse its topic hierarchy alongside the Team Broker.

@dimitrieh dimitrieh Jul 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might be unnecessary 🤔

@dimitrieh dimitrieh Jul 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If your company already operates its own MQTT broker, that broker can also be connected to FlowFuse as an external broker to browse its topic hierarchy alongside the Team Broker.


## Foreword
FlowFuse offers zero config MQTT integration with the Team Broker via the [FlowFuse MQTT Nodes](/docs/user/mqtt-nodes/) that greatly simplifies the whole process by removing the need for manual configuration.
Expand Down
Loading