Installing TBMQ using Docker (Linux or Mac OS)

• Prerequisites
• Installation
• Logs, stop and start commands
• Upgrading
  • Backup and restore (Optional)
  • Upgrade to 2.1.0
    • Add Integration Executor microservice
    • Update third-party services
  • Upgrade to 2.0.0
  • Run upgrade
• Next steps

This guide will help you to install and start standalone TBMQ using Docker on Linux or macOS. 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.

• Install Docker

Don’t forget to add your linux user to the docker group. See Manage Docker as a non-root user.

Installation

Execute the following commands to download the script that will install and start TBMQ:

1
2
wget https://raw.githubusercontent.com/thingsboard/tbmq/release-2.1.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 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 the tbmq-redis-data volume to TBMQ Redis database data directory;
• tbmq-postgres-data:/var/lib/postgresql/data - maps the tbmq-postgres-data volume to TBMQ Postgres database data directory;
• tbmq-kafka-data:/bitnami/kafka - maps the tbmq-kafka-data volume to Kafka data directory;
• tbmq-logs:/var/log/thingsboard-mqtt-broker - maps the tbmq-logs volume to TBMQ logs directory;
• tbmq-data:/data - maps the tbmq-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;
• SECURITY_MQTT_BASIC_ENABLED: "true" - enables MQTT basic security. Note: by default security is disabled.

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

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:

1
[email protected]

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

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.

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.

We do not provide step-by-step upgrade instructions for third-party services. For such procedures, please refer to the official documentation of the respective platform or, in the case of managed services, consult your service provider’s resources. Note: simply changing the image tag is not enough and may not be the correct or safe way to upgrade third-party services.

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.

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: "bitnami/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: "bitnami/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.sh 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.sh

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
wget -O tbmq-upgrade.sh https://raw.githubusercontent.com/thingsboard/tbmq/release-2.1.0/msa/tbmq/configs/tbmq-upgrade.sh &&
sudo chmod +x tbmq-upgrade.sh && ./tbmq-upgrade.sh

NOTE: replace redis_url, db_url, db_username, and db_password variables in the script with the corresponding values used during DB initialization.

If you need to upgrade to a specific version, such as TBMQ v2.0.0, replace the release branch in the command above with the target branch name, e.g., release-2.0.0.

Next steps

• Getting started guide - This guide provide quick overview of TBMQ.

• Security guide - Learn how to enable authentication and authorization of 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.