Docker (Linux & macOS)

This guide describes how to install and start a standalone TBMQ instance using Docker on Linux or macOS. For cluster installation, see the cluster setup page.

• At least 2 GB of RAM.
• Docker installed.

Run the following commands to download and run the TBMQ install script:

wget https://raw.githubusercontent.com/thingsboard/tbmq/release-2.3.0/msa/tbmq/configs/tbmq-install-and-run.sh &&
sudo chmod +x tbmq-install-and-run.sh && ./tbmq-install-and-run.sh

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:

• 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.

Once installation is complete, access the TBMQ UI at 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 further guidance, follow the backup and restore instructions.

This 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:

touch .tbmq-upgrade.env

Then proceed with the upgrade.

cat > .tbmq-upgrade.env <<'EOF'
SECURITY_MQTT_BASIC_ENABLED=true
SECURITY_MQTT_SSL_ENABLED=true
SECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT=false
EOF

  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

docker volume create tbmq-ie-logs
docker compose up -d tbmq-integration-executor --no-deps

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

docker volume create tbmq-redis-data

./tbmq-install-and-run.sh

To update to the latest version, run the following commands:

wget -O tbmq-upgrade.sh https://raw.githubusercontent.com/thingsboard/tbmq/release-2.3.0/msa/tbmq/configs/tbmq-upgrade.sh &&
sudo chmod +x tbmq-upgrade.sh && ./tbmq-upgrade.sh

To enable MQTT over SSL/TLS (MQTTS) in TBMQ, 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

Mount certificates into the container

In your docker-compose.yml, mount the directory containing the certificates:

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

Expose the MQTTS port

In docker-compose.yml:

ports:
  - "8883:8883"

Restart TBMQ

./tbmq-install-and-run.sh

Once restarted, MQTT clients can securely connect to port 8883 using TLS/SSL.