Docker (Windows)

This guide covers installing and starting a standalone TBMQ instance using Docker on Windows. For cluster installation, see the cluster setup page.

• At least 2 GB of RAM.
• Docker Desktop for Windows installed.

Before proceeding, ensure you have an active TBMQ license. If you don't have one yet, visit the Pricing page, choose a pay-as-you-go subscription or a perpetual license, and use the calculator to size your deployment — session and throughput limits, production and development instances, and any add-ons — to obtain your license key.

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-pe-docker-compose/release-2.3.0/basic/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 the necessary Docker volumes, installs the database, and starts TBMQ. Key configuration points in the docker-compose.yml:

• TBMQ_LICENSE_SECRET: YOUR_LICENSE_KEY_HERE — placeholder for the PE license key (see below);
• TBMQ_LICENSE_INSTANCE_DATA_FILE: /data/tbmq-instance-license.data — path to the auto-generated instance data file used to identify this TBMQ instance;
• 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 .firstlaunch after DB installation);
• tbmq — Docker service name;
• restart: always — auto-restarts TBMQ on system reboot or failure.

Open the downloaded docker-compose.yml, find TBMQ_LICENSE_SECRET, and replace YOUR_LICENSE_KEY_HERE with your actual license key. Then re-run the script to apply the change:

.\tbmq-install-and-run.ps1

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:

[email protected]

Password:

sysadmin

On first login, you are prompted to change the default password and re-login with the new credentials.

To view TBMQ logs:

docker compose logs -f tbmq

To stop the containers:

docker compose stop

To start the containers:

docker compose start

1. Check the version-specific notes below for any preparation your target version requires.
2. Back up your database (optional but recommended).
3. 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.

Backing up your PostgreSQL database before upgrading is highly recommended but optional. For guidance, follow the backup and restore instructions.

This is a standard upgrade from v2.2.0. No third-party component changes are required — the official images are already in use since v2.2.0.

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 -Force

Then proceed with the upgrade.

CE-to-PE migration is supported for the same version only. If you are on an earlier CE version, upgrade TBMQ CE to the latest version first. For all supported paths, see the upgrade instructions.

Before upgrading, update your docker-compose.yml to include the PE-specific environment variables:

• TBMQ_LICENSE_SECRET — your license key from the license step;
• TBMQ_LICENSE_INSTANCE_DATA_FILE — path to the auto-generated instance data file (e.g. /data/tbmq-instance-license.data).

Then create the required .tbmq-upgrade.env file:

@'
JAVA_TOOL_OPTIONS=-Dinstall.upgrade.from_version=ce
'@ | Set-Content -Path .tbmq-upgrade.env -Encoding UTF8

Then proceed with the upgrade.

To upgrade to the latest version, run:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq-pe-docker-compose/release-2.3.0/basic/windows/tbmq-upgrade.ps1" `
-OutFile ".\tbmq-upgrade.ps1"; .\tbmq-upgrade.ps1

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/certificates

Replace 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.ps1

Once restarted, MQTT clients can connect securely on port 8883.