# MQTT Broker

Device Agent uses an MQTT Broker to connect real devices, SDKs, and the browser simulator. Before
starting Device Agent, prepare these MQTT settings:

```bash
MQTT_BROKER_URL=
VITE_MQTT_WS_URL=
MQTT_USERNAME=
MQTT_PASSWORD=
```

Use `mqtts://` for MQTT over TLS and `wss://` for WebSocket over TLS. If the browser console and
Device Agent run on different machines, do not use `localhost`; use a host or IP reachable from the
browser.

## Zero EMQX

Use Zero EMQX when you only need to get device connections working quickly. It creates a temporary
MQTT Broker with MQTTS/WSS endpoints and credentials. Zero EMQX is powered by
[EMQX Cloud](https://www.emqx.com/en/cloud), expires automatically, and is not intended for long-term use.

There are three ways to create Zero EMQX:

1. Ask the Agent.

In Device Agent, say:

```text
Create a Zero EMQX MQTT Broker test instance and write the MQTT settings into this workspace.
```

2. Create it from Settings.

Open **Settings > MQTT** and click **Create test broker**.

After creating Zero EMQX from the Agent or Settings, save the MQTT settings page so the running
gateway uses the new configuration.

3. Auto-create from `.env`.

For first deployment or first startup, enable Zero EMQX in the workspace `.env`:

```bash
ZERO_EMQX_ENABLED=true
```

At startup, Zero EMQX is created automatically and the MQTT settings are saved to the configuration.
A workspace that has already created Zero EMQX will not create another one.

Optional: set these only when you need a custom manager endpoint or tag:

```bash
ZERO_EMQX_MANAGER_URL=https://zero.emqx.io
ZERO_EMQX_TAG=device-agent
```

## EMQX

Use EMQX when you want to run an MQTT Broker on your own infrastructure. It is suitable for
production, private networks, local data residency, and self-managed clusters.

Docker:

```bash
docker run -d --name emqx \
  -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083 \
  emqx/emqx-enterprise:latest
```

Quick install script:

```bash
curl -fsSL emqx.sh | bash
emqx start
```

The default EMQX Dashboard is `http://localhost:18083/`.

Without client authentication, start with:

```bash
MQTT_BROKER_URL=mqtt://127.0.0.1:1883
VITE_MQTT_WS_URL=ws://127.0.0.1:8083/mqtt
MQTT_USERNAME=
MQTT_PASSWORD=
```

If authentication or TLS is enabled, copy the username, password, and listener endpoints from the
EMQX Dashboard.

## EMQX Cloud

Use EMQX Cloud when you want a fully managed MQTT Broker with less deployment, upgrade, and
operations work. It is suitable for long-term use, team sharing, and more device connections.

1. Sign in or sign up for [EMQX Cloud](https://www.emqx.com/en/cloud).
2. Create a Serverless, Dedicated Flex, or BYOC deployment.
3. Copy the MQTT and WebSocket endpoints from the deployment Overview page.
4. Create client credentials under **Access Control > Client Authentication**.

Serverless uses TLS by default:

```bash
MQTT_BROKER_URL=mqtts://<deployment-host>:8883
VITE_MQTT_WS_URL=wss://<deployment-host>:8084/mqtt
MQTT_USERNAME=<client-username>
MQTT_PASSWORD=<client-password>
MQTT_TLS_ENABLED=true
MQTT_TLS_REJECT_UNAUTHORIZED=true
```

## EMQX Edge

Use EMQX Edge when Device Agent runs on an on-site gateway, industrial computer, or small edge
device and should stay close to the device network.

Linux:

```bash
curl -fsSL emqx.sh/edge | bash
source /etc/profile.d/emqx-edge.sh && emqx-edge start
```

The default EMQX Edge Dashboard is `http://localhost:8081/`. For Docker deployment, follow the
official docs.

LAN example:

```bash
MQTT_BROKER_URL=mqtt://edge-gateway.local:1883
VITE_MQTT_WS_URL=ws://edge-gateway.local:8083/mqtt
MQTT_USERNAME=
MQTT_PASSWORD=
```

## Choose

| Need | Use |
| --- | --- |
| Quick demo | Zero EMQX |
| Private deployment, self-managed operations, local data residency | EMQX |
| Fully managed broker, less operations work, team sharing | EMQX Cloud |
| On-site gateway, small edge device, device-side network | EMQX Edge |

## Official References

- [EMQX Docker Install](https://docs.emqx.com/en/emqx/latest/deploy/install-docker.html)
- [EMQX Install](https://docs.emqx.com/en/emqx/latest/deploy/install.html)
- [EMQX Cloud: Connect to Deployments](https://docs.emqx.com/en/cloud/latest/connect_to_deployments/deploy_mqtt_broker.html)
- [EMQX Edge Linux Install](https://docs.emqx.com/en/emqx-edge/latest/installation/packages.html)
- [EMQX Edge Docker Deployment](https://docs.emqx.com/en/emqx-edge/v1.4/installation/docker.html)