Docker (Windows)
This guide covers installing and starting a standalone TBMQ instance using Docker on Windows. For cluster installation, see the cluster setup page.
Prerequisites
Section titled “Prerequisites”- At least 2 GB of RAM.
- Docker Desktop for Windows installed.
Installation
Section titled “Installation”Open PowerShell as Administrator and run the install script.
Execute the following command to download and run the install script:
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq/release-2.3.0/msa/tbmq/configs/windows/tbmq-install-and-run.ps1" `-OutFile ".\tbmq-install-and-run.ps1"; .\tbmq-install-and-run.ps1The script downloads the docker-compose.yml file, creates the necessary Docker volumes, installs the database, and starts TBMQ.
Key configuration points in the docker-compose.yml:
8083:8083— exposes the HTTP UI on port 8083;1883:1883— exposes the MQTT port 1883;8084:8084— exposes MQTT over WebSockets on port 8084;tbmq-valkey-data:/data— Valkey data volume;tbmq-postgres-data:/var/lib/postgresql/data— PostgreSQL data volume;tbmq-kafka-data:/var/lib/kafka/data— Kafka data volume;tbmq-logs:/var/log/thingsboard-mqtt-broker— TBMQ logs volume;tbmq-data:/data— TBMQ data directory (contains.firstlaunchafter DB installation);tbmq— Docker service name;restart: always— auto-restarts TBMQ on system reboot or failure.
Once installation completes, open http://{your-host-ip}:8083 in your browser (e.g. http://localhost:8083).
You should see the TBMQ login page. Use the default System Administrator credentials:
Username:
Password:
sysadminOn first login, you are prompted to change the default password and re-login with the new credentials.
Logs, stop, and start commands
Section titled “Logs, stop, and start commands”To view TBMQ logs:
docker compose logs -f tbmqTo stop the containers:
docker compose stopTo start the containers:
docker compose startUpgrading
Section titled “Upgrading”- Check the version-specific notes below for any preparation your target version requires.
- Back up your database (optional but recommended).
- Run the upgrade command.
For full version history and supported upgrade paths, see the upgrade instructions page. If the documentation does not cover your specific upgrade path, contact us for guidance.
If there are no version-specific notes for your upgrade path, skip directly to Run upgrade.
Backup and restore (optional)
Section titled “Backup and restore (optional)”Backing up your PostgreSQL database before upgrading is highly recommended but optional. For guidance, follow the backup and restore instructions.
Upgrade to 2.3.0
Section titled Upgrade to 2.3.0This release migrates all third-party components from Bitnami images to official open-source alternatives. Review the third-party component updates for full details.
The upgrade script requires a .tbmq-upgrade.env file. If it does not already exist from a previous upgrade, create an empty one:
New-Item -Path .tbmq-upgrade.env -ItemType File -ForceThen proceed with the upgrade.
Upgrade to 2.2.0
Section titled Upgrade to 2.2.0This release migrates MQTT authentication from YAML/env configuration into the database.
The upgrade script requires a .tbmq-upgrade.env file in the same directory as docker-compose.yml. The values must match the authentication settings in your tbmq service environment.
Create the env file
@'SECURITY_MQTT_BASIC_ENABLED=trueSECURITY_MQTT_SSL_ENABLED=trueSECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT=false'@ | Set-Content -Path .tbmq-upgrade.env -Encoding UTF8Notes
- Required: If
.tbmq-upgrade.envis 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, proceed with the upgrade.
Upgrade to 2.1.0
Section titled Upgrade to 2.1.0This release adds the Integration Executor microservice and updates third-party service versions.
Add Integration Executor microservice
Add the Integration Executor service definition and volume to your docker-compose.yml ( full example):
Service definition and volume
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: trueCreate the log volume and start the service:
docker volume create tbmq-ie-logsdocker compose up -d tbmq-integration-executor --no-depsUpdate third-party services
This release updates third-party dependency versions ( pull request):
| Service | Previous version | Updated version |
|---|---|---|
| Redis | 7.0 | 7.2.5 |
| PostgreSQL | 15.x | 16.x |
| Kafka | 3.5.1 | 3.7.0 |
After addressing third-party service versions, proceed with the upgrade.
Upgrade to 2.0.0
Section titled Upgrade to 2.0.0This release adds Redis configuration to the Docker Compose setup.
Update your docker-compose.yml to include the Redis service ( pull request diff).
Complete Docker Compose file prior to the upgrade
## 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: trueCreate the Redis data volume:
docker volume create tbmq-redis-dataThen run the script to apply the changes:
.\tbmq-install-and-run.ps1Afterward, proceed with the upgrade.
Run upgrade
Section titled “Run upgrade”To upgrade to the latest version, run:
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq/release-2.3.0/msa/tbmq/configs/windows/tbmq-upgrade.ps1" `-OutFile ".\tbmq-upgrade.ps1"; .\tbmq-upgrade.ps1Enabling MQTTS (MQTT over SSL/TLS)
Section titled “Enabling MQTTS (MQTT over SSL/TLS)”To enable MQTT over SSL/TLS in TBMQ, provide valid SSL certificates and configure TBMQ to use them. For 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
Mount certificates into the container
In docker-compose.yml, add a volume mount:
volumes: - PATH_TO_CERTS:/config/certificatesReplace PATH_TO_CERTS with the path to your certificate files and ensure TBMQ has read access.
Configure environment variables
Add the following to the tbmq service environment in docker-compose.yml:
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 has no password.
Expose the MQTTS port
In docker-compose.yml:
ports: - "8883:8883"Restart TBMQ
.\tbmq-install-and-run.ps1Once restarted, MQTT clients can connect securely on port 8883.