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.xml directly under your HiveMQ home directory.
1. In your HiveMQ home directory, create a folder named pulse.
2. Inside the pulse folder, create a sub-folder named conf.
3. Inside pulse/conf, create a file named config.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/hivemq
```
A 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, ls returns No 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.

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:
1. Run the following commands. Replace <container_name> with your container name. Replace YOUR_PLATFORM_CONNECTION_STRING with 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> EOF
  Do not add spaces inside the <connection-string>…</connection-string> element value.
  
  Do not run ./bin/run.sh inside the container. The script starts a second broker instance that conflicts with the running broker on the same ports.
2. 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). Replace YOUR_PLATFORM_CONNECTION_STRING with 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>
EOF
```
Do 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 -v flag mounts <HOST_PULSE_DIR> (the directory from step 1) into the pulse subdirectory 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:latest
```
You can now edit config.xml directly 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.