Stand with Ukraine flag
Try it now Pricing
MQTT Broker
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Installation > Cluster setup with Docker Compose
Getting Started Documentation
Architecture API FAQ
On this page

Cluster setup using Docker Compose

This guide will help you to set up TBMQ in cluster mode using Docker Compose.

Prerequisites

doc warn icon

Don’t forget to add your linux user to the docker group. See Manage Docker as a non-root user.

Step 1. Pull TBMQ Image

Make sure your have logged in to docker hub using command line.

1

docker pull thingsboard/tbmq-node:2.0.0

Step 2. Clone TBMQ repository

1
2

git clone -b release-2.0.0 https://github.com/thingsboard/tbmq.git
cd tbmq/docker

Step 3. Installation

Execute the following command to create necessary volumes for all the services and to update the haproxy config in the created volume.

1

./scripts/docker-create-volumes.sh

Execute the following command to run installation:

1

./scripts/docker-install-tbmq.sh

Step 4. Running

Execute the following command to start services:

1

./scripts/docker-start-services.sh

After a while when all services will be successfully started you can make requests to http://{your-host-ip}:8083 in you browser (e.g. http://localhost:8083) and connect clients using MQTT protocol on 1883 port.

You should see TBMQ login page. Use the following default credentials for System Administrator:

Username:

1

[email protected]

Password:

1

sysadmin

On the first user log-in you will be asked to change the default password to the preferred one and then re-login using the new credentials.

Step 5. Logs, stop and start commands

In case of any issues you can examine service logs for errors. For example to see TBMQ logs execute the following command:

1

docker compose logs -f tbmq1

Or use the following command to see the state of all the containers.

1

docker compose ps

Use next command to inspect the logs of all running services.

1

docker compose logs -f

See docker compose logs command reference for more details.

Execute the following command to stop services:

1

./scripts/docker-stop-services.sh

Execute the following command to stop and completely remove deployed docker containers:

1

./scripts/docker-remove-services.sh

In case you want to remove docker volumes for all the containers, execute the following command. Note: it will remove all your data, so be careful before executing it.

1

./scripts/docker-remove-volumes.sh

It could be useful to update logs (enable DEBUG/TRACE logs) in runtime or change TBMQ or Haproxy configs. In order to do this you need to make changes, for example, to the haproxy.cfg or logback.xml file. Afterward, execute the next command to apply the changes for the container:

1

./scripts/docker-refresh-config.sh

Upgrading

Review the release notes and upgrade instruction for detailed information on the latest changes.

Backup and restore (Optional)

While backing up your PostgreSQL database is highly recommended, it is optional before proceeding with the upgrade. For further guidance, follow the next instructions.

Upgrade to 1.3.0

For the TBMQ 1.3.0 version, the installation scripts were updated to contain a new 8084 port for MQTT over WebSockets. This is needed for the correct work with the WebSocket client page.

Please pull the v1.3.0 configuration files or modify your existing ones to include a new port entry. To find more details please visit the following link.

Once the required changes are made, you should be able to connect the MQTT client on the WebSocket client page. Otherwise, please contact us, so we can answer any questions and provide our help if needed.

Run upgrade

In case you would like to upgrade, please pull the recent changes from the latest release branch:

1

git pull origin release-2.0.0

Note: Make sure custom changes of yours if available are not lost during the merge process. Make sure TBMQ_VERSION in .env file is set to the target version (e.g., set it to 2.0.0 if you are upgrading to the latest).

If you encounter conflicts during the merge process that are not related to your changes, we recommend accepting all the new changes from the remote branch.

You could revert the merge process by executing the following:

1

git merge --abort

And repeat the merge by accepting theirs changes.

1

git pull origin release-2.0.0 -X theirs

There are several useful options for the default merge strategy:

  • -X ours - this option forces conflicting hunks to be auto-resolved cleanly by favoring our version.
  • -X theirs - this is the opposite of ours. See more details here.

After that execute the following commands:

1
2
3

./scripts/docker-stop-services.sh
./scripts/docker-upgrade-tbmq.sh --fromVersion=FROM_VERSION
./scripts/docker-start-services.sh

Where FROM_VERSION - from which version upgrade should be started. See Upgrade Instructions for valid fromVersion values.

Generate certificate for HTTPS

We are using HAproxy for proxying traffic to containers and for web UI by default we are using 8083 and 443 ports. For using HTTPS with a valid certificate, execute these commands:

1
2

docker exec haproxy-certbot certbot-certonly --domain your_domain --email your_email
docker exec haproxy-certbot haproxy-refresh

Note: Valid certificate is used only when you visit web UI by domain in URL.

Next steps