- Prerequisites
- Installation
- Logs, stop and start commands
- Upgrading
- Enabling MQTTS (MQTT over SSL/TLS)
- Next steps
This guide will help you to install and start standalone TBMQ using Docker on Windows. If you are looking for a cluster installation instruction, please visit cluster setup page.
Prerequisites
To run TBMQ on a single machine you will need at least 2Gb of RAM.
Installation
Execute the following commands to download the script that will install and start TBMQ:
Note: make sure the downloaded PowerShell scripts are allowed to run on your system.
- Open PowerShell (Run as Administrator).
- (Optional) Get the current execution policy.
It determines the level of security for running scripts on a system. For example, if
Restricted
is returned, it means PowerShell doesn’t execute any scripts.
1
Get-ExecutionPolicy
- (Optional) Change the current execution policy if required.
Set it to the one that will allow you to run PowerShell scripts and the one that suits your security requirements.
For example,
Unrestricted
is the least restrictive setting that allows all scripts to be executed.
1
Set-ExecutionPolicy Unrestricted
- Install TBMQ
1
2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq/release-2.2.0/msa/tbmq/configs/windows/tbmq-install-and-run.ps1" `
-OutFile ".\tbmq-install-and-run.ps1"; .\tbmq-install-and-run.ps1
The script downloads the docker-compose.yml file, creates necessary docker volumes, installs the database for TBMQ, and starts TBMQ. Key configuration points for TBMQ in docker-compose file:
8083:8083
- connect local port 8083 to exposed internal HTTP port 8083;1883:1883
- connect local port 1883 to exposed internal MQTT port 1883;8084:8084
- connect local port 8084 to exposed internal MQTT over WebSockets port 8084;tbmq-redis-data:/bitnami/redis/data
- maps thetbmq-redis-data
volume to TBMQ Redis database data directory;tbmq-postgres-data:/var/lib/postgresql/data
- maps thetbmq-postgres-data
volume to TBMQ Postgres database data directory;tbmq-kafka-data:/bitnami/kafka
- maps thetbmq-kafka-data
volume to Kafka data directory;tbmq-logs:/var/log/thingsboard-mqtt-broker
- maps thetbmq-logs
volume to TBMQ logs directory;tbmq-data:/data
- maps thetbmq-data
volume to TBMQ data directory that contains .firstlaunch file after the DB is installed;tbmq
- friendly local name of this machine;restart: always
- automatically start TBMQ in case of system reboot and restart in case of failure;
Note: In case the TBMQ is being installed on the same host where ThingsBoard is already running, the following issue can be seen:
1
Error response from daemon: ... Bind for 0.0.0.0:1883 failed: port is already allocated
In order to fix this, you need to expose another host’s port for the TBMQ container,
i.e. change the 1883:1883
line in the downloaded docker-compose.yml file with, for example, 1889:1883
. After that re-run the script.
1
.\tbmq-install-and-run.ps1
Once the installation process is complete you can access TBMQ UI by visiting the following URL http://{your-host-ip}:8083
in your browser (e.g. http://localhost:8083).
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.
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 tbmq
To stop the containers:
1
docker compose stop
To start the containers:
1
docker compose start
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 is done using environment variables passed to the upgrade container.
The upgrade script therefore requires a file named .tbmq-upgrade.env
in the same directory as docker-compose.yml
.
This file is used only during upgrade to create the default auth providers.
Make sure the values match what you already run in your tbmq
service (docker-compose.yml → environment:
).
Create the env file (Windows PowerShell)
From the directory containing docker-compose.yml
:
1
2
3
4
5
@'
SECURITY_MQTT_BASIC_ENABLED=true
SECURITY_MQTT_SSL_ENABLED=true
SECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT=false
'@ | Set-Content -Path .tbmq-upgrade.env -Encoding UTF8
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
.
Notes
- Required: If
.tbmq-upgrade.env
is missing, the upgrade script will fail. -
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 created, continue 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.
Add the service definition and volume to your existing docker-compose.yml file
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
tbmq-integration-executor:
restart: always
image: "thingsboard/tbmq-integration-executor:2.1.0"
depends_on:
- kafka
- tbmq
logging:
driver: "json-file"
options:
max-size: "200m"
max-file: "5"
environment:
TB_SERVICE_ID: tbmq-ie
TB_KAFKA_SERVERS: kafka:9092
#JAVA_OPTS: "-Xmx2048M -Xms2048M -Xss384k -XX:+AlwaysPreTouch"
volumes:
- tbmq-ie-logs:/var/log/tbmq-integration-executor
volumes:
tbmq-ie-logs:
external: true
For the complete updated docker-compose.yml
, see the official example here.
Run the following command to create a Docker volume for Integration Executor logs:
1
docker volume create tbmq-ie-logs
After updating your configuration, start the service with:
1
docker compose up -d tbmq-integration-executor --no-deps
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 upgrade process.
Upgrade to 2.0.0
For the TBMQ 2.0.0 release, the installation scripts have been updated to include Redis configuration.
Please update your docker-compose.yml
file to incorporate the Redis settings.
You can review the necessary changes by visiting the following link.
Here is the complete docker compose file with the Redis configuration prior to the upgrade
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
#
# Copyright © 2016-2024 The Thingsboard Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
services:
postgres:
restart: always
image: "postgres:15"
ports:
- "5432"
environment:
POSTGRES_DB: thingsboard_mqtt_broker
POSTGRES_PASSWORD: postgres
volumes:
- tbmq-postgres-data:/var/lib/postgresql/data
kafka:
restart: always
image: "bitnamilegacy/kafka:3.5.1"
ports:
- "9092"
environment:
KAFKA_CFG_NODE_ID: 0
KAFKA_CFG_PROCESS_ROLES: controller,broker
KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: 0@kafka:9093
KAFKA_CFG_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://:9092
KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
KAFKA_CFG_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CFG_INTER_BROKER_LISTENER_NAME: PLAINTEXT
volumes:
- tbmq-kafka-data:/bitnami/kafka
redis:
restart: always
image: "bitnamilegacy/redis:7.0"
environment:
# ALLOW_EMPTY_PASSWORD is recommended only for development.
ALLOW_EMPTY_PASSWORD: "yes"
ports:
- "6379"
volumes:
- tbmq-redis-data:/bitnami/redis/data
tbmq:
restart: always
image: "thingsboard/tbmq:1.4.0"
depends_on:
- postgres
- kafka
- redis
ports:
- "8083:8083"
- "1883:1883"
- "8084:8084"
environment:
TB_SERVICE_ID: tbmq
SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard_mqtt_broker
SPRING_DATASOURCE_USERNAME: postgres
SPRING_DATASOURCE_PASSWORD: postgres
TB_KAFKA_SERVERS: kafka:9092
REDIS_HOST: redis
SECURITY_MQTT_BASIC_ENABLED: "true"
#JAVA_OPTS: "-Xmx2048M -Xms2048M -Xss384k -XX:+AlwaysPreTouch"
volumes:
- tbmq-logs:/var/log/thingsboard-mqtt-broker
- tbmq-data:/data
volumes:
tbmq-postgres-data:
external: true
tbmq-kafka-data:
external: true
tbmq-redis-data:
external: true
tbmq-logs:
external: true
tbmq-data:
external: true
Additionally, add the following line to your tbmq-install-and-run.ps1
script (locate create_volume_if_not_exists
lines) to create a volume for Redis data:
1
create_volume_if_not_exists "tbmq-redis-data"
Or simply create it with the following command:
1
docker volume create tbmq-redis-data
Once this is done, run the script to apply the changes:
1
.\tbmq-install-and-run.ps1
This will restart TBMQ with Redis enabled. Afterward, you can proceed with the upgrade process. Please contact us, so we can answer any questions and provide our help if needed.
Run upgrade
In order to update to the latest version, execute the following commands:
1
2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq/release-2.2.0/msa/tbmq/configs/windows/tbmq-upgrade.ps1" `
-OutFile ".\tbmq-upgrade.ps1"; .\tbmq-upgrade.ps1
NOTE: replace redis_url
, db_url
, db_username
, and db_password
variables in the script with the corresponding values used during DB initialization.
Enabling MQTTS (MQTT over SSL/TLS)
To enable MQTT over SSL/TLS (MQTTS) in TBMQ, you need to provide valid SSL certificates and configure TBMQ to use them.
For details on supported formats and configuration options, see the MQTT over SSL guide.
Prepare SSL Certificates
Obtain a valid SSL certificate and private key. For example:
mqttserver.pem
– Public certificate (may include the full chain)mqttserver_key.pem
– 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 the Container
In your docker-compose.yml
, mount the directory containing the certificates:
1
2
volumes:
- PATH_TO_CERTS:/config/certificates
Replace PATH_TO_CERTS
with the path to your certificate files. Ensure TBMQ has read access to these files.
Configure Environment Variables
Add the following variables to enable SSL in docker-compose.yml
:
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"
Leave
LISTENER_SSL_PEM_KEY_PASSWORD
empty if your private key is not password-protected.
Expose the MQTTS Port
In docker-compose.yml
:
1
2
ports:
- "8883:8883"
Restart TBMQ
Apply the changes by restarting TBMQ:
1
./tbmq-install-and-run.sh
Once restarted, MQTT clients can securely connect to port 8883 using TLS/SSL.
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.