- Prerequisites
- Step 1. Pull TBMQ Image
- Step 2. Clone TBMQ repository
- Step 3. Installation
- Step 4. Running
- Step 5. Logs, stop and start commands
- Upgrading
- Generate certificate for HTTPS
- Enable MQTTS (MQTT over SSL/TLS)
- Next steps
This guide will help you to set up TBMQ in cluster mode using Docker Compose.
Prerequisites
Step 1. Pull TBMQ Image
Make sure your have logged in to docker hub using command line.
1
docker pull thingsboard/tbmq-node:2.2.0
Step 2. Clone TBMQ repository
1
2
git clone -b release-2.2.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}
in you browser (e.g. http://localhost) and connect clients using MQTT protocol on 1883 port.
You should see TBMQ login page. Use the following default credentials for System Administrator:
Username:
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
To reload HAProxy’s configuration without restarting the Docker container you can send the HUP signal to this process (PID 1):
1
docker exec -it haproxy-certbot sh -c "kill -HUP 1"
Upgrading
Review the release notes and upgrade instruction for detailed information on the latest changes.
If there are no Upgrade to x.x.x notes for your version, you can proceed directly with the general upgrade instructions.
If the documentation does not cover the specific upgrade instructions for your case, please contact us so we can provide further guidance.
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 2.2.0
In this release, the MQTT authentication mechanism was migrated from YAML/env configuration into the database. During upgrade, TBMQ needs to know which authentication providers are enabled in your deployment. This information is provided through environment variables passed to the upgrade container.
The upgrade script requires a file named tb-mqtt-broker.env
that explicitly defines these variables.
Environment variables from your docker-compose.yml
file are not applied during the upgrade — only the values in tb-mqtt-broker.env
will be used.
Tips If you use only Basic authentication, set
SECURITY_MQTT_SSL_ENABLED=false
. If you use only X.509 authentication, setSECURITY_MQTT_BASIC_ENABLED=false
andSECURITY_MQTT_SSL_ENABLED=true
.
Supported variables
SECURITY_MQTT_BASIC_ENABLED
(true|false
)SECURITY_MQTT_SSL_ENABLED
(true|false
)SECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT
(true|false
) — usuallyfalse
.
Once the file is prepared and the values verified, proceed with the upgrade process.
Upgrade to 2.1.0
TBMQ v2.1.0 introduces enhancements, including a new Integration Executor microservice and bumped versions for third-party services.
Add Integration Executor microservice
This release adds support for external integrations via the new Integration Executor microservice.
For the complete updated docker-compose.yml
, see the official example here.
To retrieve the latest configuration files, including those for Integration Executors, pull the updates from the release branch. Follow the steps outlined in the run upgrade instructions up to the execution of the upgrade script (do not execute .sh commands yet).
After successfully pulling the updates, create Docker volumes to store Integration Executor logs by running:
1
./scripts/docker-create-volumes.sh
Upon running the command, you should see output similar to the following:
1
2
3
4
5
user@user:~/tbmq/docker$ ./scripts/docker-create-volumes.sh
tbmq-ie1-logs
tbmq-ie2-logs
tbmq-ie-config
Update third-party services
With v2.1.0, TBMQ updates the versions of key third-party dependencies, including Redis, PostgreSQL, and Kafka. You can review the changes by visiting the following link.
Service | Previous Version | Updated Version |
---|---|---|
Redis | 7.0 | 7.2.5 |
PostgreSQL | 15.x | 16.x |
Kafka | 3.5.1 | 3.7.0 |
We recommend aligning your environment with the updated third-party versions to ensure full compatibility with this release. Alternatively, you may proceed without upgrading, but compatibility is only guaranteed with the recommended versions.
After addressing third-party service versions as needed, you can continue with the remaining steps of the upgrade process.
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.2.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.2.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.2.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:
|
Where |
Generate certificate for HTTPS
We are using HAproxy for proxying traffic to containers and for web UI by default we are using 80 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.
Enable MQTTS (MQTT over SSL/TLS)
MQTTS allows clients to connect to TBMQ over an encrypted TLS/SSL channel, ensuring the confidentiality and integrity of MQTT messages in transit. There are two common deployment options:
- Two-way MQTTS (Mutual TLS) – TBMQ terminates TLS, and clients must present valid certificates for authentication.
- One-way MQTTS (TLS termination at Load Balancer) – HAProxy or another load balancer handles TLS termination, and forwards plain MQTT traffic to TBMQ over a trusted internal network.
Both approaches protect external connections with encryption, but two-way MQTTS adds client certificate verification for higher security, while one-way MQTTS simplifies broker configuration and can reuse existing HTTPS certificates on the load balancer.
Two-way MQTTS
In this configuration, TBMQ itself handles TLS termination and (optionally) client certificate authentication. This approach is suitable when you want the broker to fully control SSL/TLS and mutual authentication without relying on a load balancer for security.
To enable MQTT over SSL (MQTTS), you need to provide valid SSL certificates and configure TBMQ to use them.
For more information on supported certificate formats and options, refer to the MQTT over SSL documentation.
Provide SSL Certificates
Obtain a valid SSL certificate and private key. For example:
mqttserver.pem
– your public certificate (may include full chain);mqttserver_key.pem
– your private key.
Self-signed certificates are supported for testing, but we recommend using certificates from a trusted Certificate Authority for production environments.
Mount Certificates into Containers
Open your docker-compose.yml
file and uncomment the volume line that mounts the certificate files:
1
2
volumes:
- PATH_TO_CERTS:/config/certificates
Replace PATH_TO_CERTS
with the path to the folder containing your certificate files. Make sure TBMQ can access those file.
Configure Environment Variables
Edit the tb-mqtt-broker.env
file and uncomment/configure the following lines to enable SSL:
1
2
3
4
LISTENER_SSL_ENABLED=true
LISTENER_SSL_PEM_CERT=/config/certificates/mqttserver.pem
LISTENER_SSL_PEM_KEY=/config/certificates/mqttserver_key.pem
LISTENER_SSL_PEM_KEY_PASSWORD=server_key_password
Adjust the file paths and password as needed. If your private key is not password-protected, you can leave
LISTENER_SSL_PEM_KEY_PASSWORD
empty.
Restart Services
Apply the changes by restarting TBMQ services:
1
./scripts/docker-start-services.sh
Once started, your MQTT clients will be able to securely connect to port 8883 using TLS/SSL.
One-way MQTTS
In this setup, TLS is terminated at the load balancer (HAProxy). Clients connect securely to HAProxy over MQTTS (port 8883), and HAProxy forwards plain MQTT (unencrypted) to TBMQ over the internal network (port 1883). You can reuse the same certificate you already use for HTTPS.
Point HAProxy to your certificate bundle (PEM with full chain + private key). If you reuse the HTTPS cert, reference the same bundle. Locate and update the haproxy.cfg file:
1
2
3
4
5
6
7
8
9
10
listen mqtts-in
bind *:${MQTTS_PORT} ssl crt /usr/local/etc/haproxy/certs.d/fullchain-and-key.pem
mode tcp
option clitcpka # For TCP keep-alive
timeout client 3h
timeout server 3h
option tcplog
balance leastconn
server tbMqtt1 tbmq1:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4
server tbMqtt2 tbmq2:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4
Note: Replace fullchain-and-key.pem with the actual filename of your certificate bundle.
Next steps
-
Getting started guide - This guide provide quick overview of TBMQ.
-
Security guide - Learn how to enable authentication and authorization for MQTT clients.
-
Configuration guide - Learn about TBMQ configuration files and parameters.
-
MQTT client type guide - Learn about TBMQ client types.
-
Integration with ThingsBoard - Learn about how to integrate TBMQ with ThingsBoard.