Connect a Broker or Edge with the Platform
A broker or edge becomes part of the platform only after you connect it to the platform. Deploying or running a broker is not enough on its own. To connect it, you generate a connection string in the platform, apply the string to your deployment, and restart the broker. The instance then reports to the platform and appears in Connect.
Use this task for a broker you just deployed (see Deploy a Broker) or a broker you were already running before you adopted the platform.
Before You Begin
Before you connect a broker or an edge to the platform, you must have:
-
A running HiveMQ broker or edge, version HiveMQ 4.53 or later.
-
Filesystem access to the deployment, so that you can create configuration files and restart the broker.
Step 1: Generate a Connection String
-
On Connect, click Get Broker or Edge.
-
On How do you want to get started?, select Connect what you already run.
-
Select HiveMQ Broker or HiveMQ Edge, then click Continue.
-
Enter a name and an optional description. The name is the display name shown in the broker and edge list.
-
Click Generate connection string. A generated string value displays.
-
In Connection string, copy the generated string value. In the next step, you add this value to your deployment.
| When you generate the connection string, the instance appears in the Network view on the Connect page with a Data Intelligence state Ready to connect. This state shows that the instance is eligible for Data Intelligence, but the Data Intelligence connection is not yet completed. For more details about each state, see Connect Network Reference. |
Step 2: Add a Connection String to Your Deployment
A broker connects to the platform through a configuration file that is not part of the default HiveMQ distribution. You create this configuration file within your HiveMQ deployment. The configuration file location and the way you persist the file depend on how the broker runs.
Local install
-
Create
pulse/conf/config.xmldirectly under your HiveMQ home directory.-
In your HiveMQ home directory, create a folder named
pulse. -
Inside the
pulsefolder, create a sub-folder namedconf. -
Inside
pulse/conf, create a file namedconfig.xml. Use the following structure and paste the connection string you copied into the<connection-string>element:<HIVEMQ_HOME>/pulse/conf/config.xml<pulse> <enabled>true</enabled> <bootstrap>true</bootstrap> <agent> <connection-string>YOUR_PLATFORM_CONNECTION_STRING</connection-string> </agent> </pulse>Do not add spaces inside the <connection-string>…</connection-string>element value.
-
-
Save the file.
The resulting layout inside your HiveMQ home directory is:
<HIVEMQ_HOME>/ └── pulse/ └── conf/ └── config.xml -
Restart the broker.
./bin/run.sh
Docker
In the official HiveMQ Docker image, the HiveMQ home directory is /opt/hivemq.
To connect a Docker deployment to the platform, you create a pulse/conf/config.xml configuration file under the HiveMQ home directory inside the deployment container.
To add the configuration file to the container, complete the following steps:
-
Confirm the HiveMQ home directory exists inside the container:
docker exec <container_name> ls /opt/hivemqA successful listing confirms the path:
audit backup bin conf data extensions license log README.txt third-party-licenses tools
If the path does not exist,
lsreturnsNo such file or directory. -
Choose how to persist your configuration.
You can add the configuration file in two ways:
Method When to Use Edit files inside the running container
Use for quick tests or validation in a temporary or development container. Docker discards your changes when you remove or recreate the container.
Bind-mount from the host (Recommended)
Use in any environment where you redeploy or rebuild the container, including production and CI/CD workflows.
-
To edit files inside the running container:
-
Run the following commands. Replace
<container_name>with your container name. ReplaceYOUR_PLATFORM_CONNECTION_STRINGwith the connection string that you generated from the HiveMQ Platform:docker exec <container_name> mkdir -p /opt/hivemq/pulse/conf docker exec -i <container_name> sh -c 'cat > /opt/hivemq/pulse/conf/config.xml' <<'EOF' <pulse> <enabled>true</enabled> <bootstrap>true</bootstrap> <agent> <connection-string>YOUR_PLATFORM_CONNECTION_STRING</connection-string> </agent> </pulse> EOFDo not add spaces inside the <connection-string>…</connection-string>element value.Do not run ./bin/run.shinside the container. The script starts a second broker instance that conflicts with the running broker on the same ports. -
Restart the container to restart the broker:
docker restart <container_name>
-
-
To Bind-mount from the host (Recommended):
Docker cannot attach a volume mount to a container after the container starts. To use this method on a running container, replace the running container with a new container that has the mount in place from startup.
-
Create the folder structure on the host. Replace
<HOST_PULSE_DIR>with a directory path on your host (for example,~/hivemq-pulse). ReplaceYOUR_PLATFORM_CONNECTION_STRINGwith the connection string that you generated from the HiveMQ Platform:mkdir -p <HOST_PULSE_DIR>/conf cat > <HOST_PULSE_DIR>/conf/config.xml <<'EOF' <pulse> <enabled>true</enabled> <bootstrap>true</bootstrap> <agent> <connection-string>YOUR_PLATFORM_CONNECTION_STRING</connection-string> </agent> </pulse> EOFDo not add spaces inside the <connection-string>element. -
Stop, inspect, and then remove the running container. Docker requires this step to attach the new mount:
The new container must repeat every option from your original Docker run command: environment variables, data and license volumes, cluster settings, and port mappings. If the original container stored broker data without a volume, that data is lost when you remove the container. Inspect your original container and ensure that the new container includes these options before you remove your original one. docker stop <container_name> docker inspect <container_name> docker rm <container_name> -
Start a new container with your original options plus the Pulse mount. The
-vflag mounts<HOST_PULSE_DIR>(the directory from step 1) into thepulsesubdirectory of the HiveMQ home directory:docker run -d --name <container_name> \ -p 8080:8080 -p 1883:1883 \ -v <HOST_PULSE_DIR>:/opt/hivemq/pulse \ hivemq/hivemq4:latestYou can now edit
config.xmldirectly on the host. The broker applies your changes after you restart the container (for example,docker restart <container_name>).
-
-
To learn more about HiveMQ clustering with Docker, see Run HiveMQ on Docker.
Kubernetes
Provide the Pulse configuration to the HiveMQ Platform Operator. The operator manages the configuration as a Kubernetes Secret.
For the pulse configuration options (inline data, an existing Secret by name, or overridePulseConfig from a file), see HiveMQ Pulse Configuration Options.
Step 3: Confirm the Result
When the broker restarts, it connects to the platform with the configured connection string. Upon successful connection, the instance status in Connect changes from Ready to connect to Connected. If the instance does not connect, check the path to the configuration file, check the connection string, and confirm that the broker restarted.
For more information about each state shown in the Network view on Connect, see the Connect Network Reference.
Next Steps
-
Get a License: if you have a Software broker that you have not yet licensed.
-
Contextualize: Structure the data now streams through your connected broker.