Installing ThingsBoard on Windows

ThingsBoard team recommends to use PostgreSQL for development and production environments with reasonable load (< 5000 msg/sec). Many cloud vendors support managed PostgreSQL servers which is a cost-effective solution for most of ThingsBoard instances.

PostgreSQL Installation

Download the installation file (PostgreSQL 15 or newer releases) here and follow the installation instructions.

During PostgreSQL installation, you will be prompted for superuser (postgres) password. Don’t forget this password. It will be used later. For simplicity, we will substitute it with “postgres”.

Create ThingsBoard Database

Once installed, launch the “pgAdmin” software and login as superuser (postgres). Open your server and create database “thingsboard” with owner “postgres”.

ThingsBoard Configuration

In case you have specified the PostgreSQL superuser password as “postgres”, you can skip this step.

Open the Notepad or other editor as administrator user (right click on the app icon and select “Run as administrator”).
Open the following file for editing (select “All Files” instead of “Text Documents” in file choosing dialog, the encoding is UTF-8):

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

and locate “# SQL DAO Configuration” block. Don’t forget to replace “postgres” with your real postgres user password:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# SQL DAO Configuration
spring:
  data:
    jpa:
      repositories:
        enabled: "true"
  jpa:
    open-in-view: "false"
    hibernate:
      ddl-auto: "none"
  datasource:
    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.postgresql.Driver}"
    url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/thingsboard}"
    username: "${SPRING_DATASOURCE_USERNAME:postgres}"
    password: "${SPRING_DATASOURCE_PASSWORD:YOUR_POSTGRES_PASSWORD_HERE}"
    hikari:
      maximumPoolSize: "${SPRING_DATASOURCE_MAXIMUM_POOL_SIZE:16}"

locate “SQL_POSTGRES_TS_KV_PARTITIONING” parameter in order to override the default value for timestamp key-value storage partitioning size:

1
2
3
4
    sql:
      postgres:
        # Specify partitioning size for timestamp key-value storage. Example: DAYS, MONTHS, YEARS, INDEFINITE.
        ts_key_value_partitioning: "${SQL_POSTGRES_TS_KV_PARTITIONING:MONTHS}"

In Memory queue is built-in and enabled by default. No additional configuration steps required.

Kafka Installation

Apache Kafka is an open-source stream-processing software platform.

Install Kafka

Use the instructions below for installing Kafka in a Docker container.

1
nano docker-compose-kafka.yml

Add the following lines to the docker-compose-kafka.yml file:

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
version: '3.2'
services:
  kafka:
    restart: always
    image: bitnami/kafka:3.8.1
    ports:
      - 9092:9092 #to localhost:9092 from host machine
      - 9093 #for Kraft
      - 9094 #to kafka:9094 from within Docker network
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "OUTSIDE://:9092,CONTROLLER://:9093,INSIDE://:9094"
      KAFKA_CFG_ADVERTISED_LISTENERS: "OUTSIDE://localhost:9092,INSIDE://kafka:9094"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INSIDE"
      KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "false"
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
      KAFKA_CFG_PROCESS_ROLES: "controller,broker" #KRaft
      KAFKA_CFG_NODE_ID: "0" #KRaft
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER" #KRaft
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "0@kafka:9093" #KRaft
    volumes:
      - kafka-data:/bitnami
volumes:
  kafka-data:
    driver: local

Start the container:

1
docker compose -f docker-compose-kafka.yml up -d

ThingsBoard Configuration

Open the Notepad or other editor as administrator user (right click on the app icon and select “Run as administrator”).
Open the following file for editing (select “All Files” instead of “Text Documents” in file choosing dialog, the encoding is UTF-8):

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

and locate “queue:” block. Make sure the queue type is “kafka”, and don’t forget to replace “localhost:9092” with your real Kafka bootstrap servers:

1
2
3
4
5
6
7
8
9
10
11
queue:
  type: "${TB_QUEUE_TYPE:kafka}"
...
  kafka:
    bootstrap.servers: "${TB_KAFKA_SERVERS:localhost:9092}"
    acks: "${TB_KAFKA_ACKS:all}"
    retries: "${TB_KAFKA_RETRIES:1}"
    batch.size: "${TB_KAFKA_BATCH_SIZE:16384}"
    linger.ms: "${TB_KAFKA_LINGER_MS:1}"
    buffer.memory: "${TB_BUFFER_MEMORY:33554432}"
    replication_factor: "${TB_QUEUE_KAFKA_REPLICATION_FACTOR:1}"

AWS SQS Configuration

To access AWS SQS service, you first need to create an AWS account.

To work with AWS SQS service you will need to create your next credentials using this instruction:

• Access key ID
• Secret access key

ThingsBoard Configuration

Open the Notepad or other editor as administrator user (right click on the app icon and select “Run as administrator”).
Open the following file for editing (select “All Files” instead of “Text Documents” in file choosing dialog, the encoding is UTF-8):

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

and locate “queue:” block. Make sure the queue type is “aws-sqs”, and don’t forget to replace “YOUR_KEY”, “YOUR_SECRET” with your real AWS SQS IAM user credentials and “YOUR_REGION” with your real AWS SQS account region:

1
2
3
4
5
6
7
queue:
  type: "${TB_QUEUE_TYPE:aws-sqs}"
...
  aws_sqs:
    access_key_id: "${TB_QUEUE_AWS_SQS_ACCESS_KEY_ID:YOUR_KEY}"
    secret_access_key: "${TB_QUEUE_AWS_SQS_SECRET_ACCESS_KEY:YOUR_SECRET}"
    region: "${TB_QUEUE_AWS_SQS_REGION:YOUR_REGION}"

These params affect the number of requests per second from each partitions per each queue.

Number of requests to particular Message Queue calculated based on the formula:

((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues) + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS

For example, number of requests based on default parameters is:

Rule Engine queues:

Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30

Core queue 10 partitions

Transport request Queue + response Queue = 2

Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2

Total = 44

Number of requests per second = 44 * 1000 / 25 = 1760 requests

Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.

By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.

Sample parameters to fit into 10 requests per second on a “monolith” deployment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
queue:
...
  transport_api:
    request_poll_interval: "${TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS:1000}"
    response_poll_interval: "${TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  core:
    poll-interval: "${TB_QUEUE_CORE_POLL_INTERVAL_MS:1000}"
    partitions: "${TB_QUEUE_CORE_PARTITIONS:2}"
...    
  vc:
    partitions: "${TB_QUEUE_VC_PARTITIONS:1}"
    poll-interval: "${TB_QUEUE_VC_INTERVAL_MS:1000}"
...
  js:
    response_poll_interval: "${REMOTE_JS_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  rule-engine:
    poll-interval: "${TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS:1000}"
...
  transport:
    poll_interval: "${TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS:1000}"

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.

Google Pub/Sub Configuration

To access Pub/Sub service, you first need to create an Google cloud account.

To work with Pub/Sub service you will need to create a project using this instruction.

Create service account credentials with the role “Editor” or “Admin” using this instruction, and save json file with your service account credentials step 9 here.

ThingsBoard Configuration

Open the Notepad or other editor as administrator user (right click on the app icon and select “Run as administrator”).
Open the following file for editing (select “All Files” instead of “Text Documents” in file choosing dialog, the encoding is UTF-8):

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

and locate “queue:” block. Make sure the queue type is “pubsub”, and don’t forget to replace “YOUR_PROJECT_ID”, “YOUR_SERVICE_ACCOUNT” with your real Pub/Sub project id, and service account (it is whole data from json file):

1
2
3
4
5
6
7
8
queue:
  type: "${TB_QUEUE_TYPE:pubsub}"
...
  pubsub:
    project_id: "${TB_QUEUE_PUBSUB_PROJECT_ID:YOUR_PROJECT_ID}"
    service_account: "${TB_QUEUE_PUBSUB_SERVICE_ACCOUNT:YOUR_SERVICE_ACCOUNT}"
    max_msg_size: "${TB_QUEUE_PUBSUB_MAX_MSG_SIZE:1048576}" #in bytes
    max_messages: "${TB_QUEUE_PUBSUB_MAX_MESSAGES:1000}"

These params affect the number of requests per second from each partitions per each queue.

Number of requests to particular Message Queue calculated based on the formula:

((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues) + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS

For example, number of requests based on default parameters is:

Rule Engine queues:

Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30

Core queue 10 partitions

Transport request Queue + response Queue = 2

Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2

Total = 44

Number of requests per second = 44 * 1000 / 25 = 1760 requests

Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.

By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.

Sample parameters to fit into 10 requests per second on a “monolith” deployment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
queue:
...
  transport_api:
    request_poll_interval: "${TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS:1000}"
    response_poll_interval: "${TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  core:
    poll-interval: "${TB_QUEUE_CORE_POLL_INTERVAL_MS:1000}"
    partitions: "${TB_QUEUE_CORE_PARTITIONS:2}"
...
  vc:
    partitions: "${TB_QUEUE_VC_PARTITIONS:1}"
    poll-interval: "${TB_QUEUE_VC_INTERVAL_MS:1000}"
...
  js:
    response_poll_interval: "${REMOTE_JS_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  rule-engine:
    poll-interval: "${TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS:1000}"
...
  transport:
    poll_interval: "${TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS:1000}"

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.

Azure Service Bus Configuration

To access Azure Service Bus, you first need to create an Azure account.

To work with Service Bus service you will need to create a Service Bus Namespace using this instruction.

Create Shared Access Signature using this instruction.

ThingsBoard Configuration

Open the Notepad or other editor as administrator user (right click on the app icon and select “Run as administrator”).
Open the following file for editing (select “All Files” instead of “Text Documents” in file choosing dialog, the encoding is UTF-8):

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

and locate “queue:” block. Make sure the queue type is “service-bus”, and don’t forget to replace “YOUR_NAMESPACE_NAME” with your real Service Bus namespace name, and “YOUR_SAS_KEY_NAME”, “YOUR_SAS_KEY” with your real Service Bus credentials. Note: “YOUR_SAS_KEY_NAME” it is “SAS Policy”, “YOUR_SAS_KEY” it is “SAS Policy Primary Key”:

1
2
3
4
5
6
7
8
queue:
  type: "${TB_QUEUE_TYPE:service-bus}"
...
  service_bus:
    namespace_name: "${TB_QUEUE_SERVICE_BUS_NAMESPACE_NAME:YOUR_NAMESPACE_NAME}"
    sas_key_name: "${TB_QUEUE_SERVICE_BUS_SAS_KEY_NAME:YOUR_SAS_KEY_NAME}"
    sas_key: "${TB_QUEUE_SERVICE_BUS_SAS_KEY:YOUR_SAS_KEY}"
    max_messages: "${TB_QUEUE_SERVICE_BUS_MAX_MESSAGES:1000}"

These params affect the number of requests per second from each partitions per each queue.

Number of requests to particular Message Queue calculated based on the formula:

((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues) + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS

For example, number of requests based on default parameters is:

Rule Engine queues:

Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30

Core queue 10 partitions

Transport request Queue + response Queue = 2

Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2

Total = 44

Number of requests per second = 44 * 1000 / 25 = 1760 requests

Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.

By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.

Sample parameters to fit into 10 requests per second on a “monolith” deployment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
queue:
...
  transport_api:
    request_poll_interval: "${TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS:1000}"
    response_poll_interval: "${TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  core:
    poll-interval: "${TB_QUEUE_CORE_POLL_INTERVAL_MS:1000}"
    partitions: "${TB_QUEUE_CORE_PARTITIONS:2}"
...
  vc:
    partitions: "${TB_QUEUE_VC_PARTITIONS:1}"
    poll-interval: "${TB_QUEUE_VC_INTERVAL_MS:1000}"
...
  js:
    response_poll_interval: "${REMOTE_JS_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  rule-engine:
    poll-interval: "${TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS:1000}"
...
  transport:
    poll_interval: "${TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS:1000}"

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.

RabbitMQ Installation

For installing RabbitMQ use this instruction.

ThingsBoard Configuration

Open the Notepad or other editor as administrator user (right click on the app icon and select “Run as administrator”).
Open the following file for editing (select “All Files” instead of “Text Documents” in file choosing dialog, the encoding is UTF-8):

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

and locate “queue:” block. Make sure the queue type is “rabbitmq” and don’t forget to replace “YOUR_USERNAME” and “YOUR_PASSWORD” with your real user credentials, “localhost” and “5672” with your real RabbitMQ host and port:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
queue:
  type: "${TB_QUEUE_TYPE:rabbitmq}"
...
  rabbitmq:
    exchange_name: "${TB_QUEUE_RABBIT_MQ_EXCHANGE_NAME:}"
    host: "${TB_QUEUE_RABBIT_MQ_HOST:localhost}"
    port: "${TB_QUEUE_RABBIT_MQ_PORT:5672}"
    virtual_host: "${TB_QUEUE_RABBIT_MQ_VIRTUAL_HOST:/}"
    username: "${TB_QUEUE_RABBIT_MQ_USERNAME:YOUR_USERNAME}"
    password: "${TB_QUEUE_RABBIT_MQ_PASSWORD:YOUR_PASSWORD}"
    automatic_recovery_enabled: "${TB_QUEUE_RABBIT_MQ_AUTOMATIC_RECOVERY_ENABLED:false}"
    connection_timeout: "${TB_QUEUE_RABBIT_MQ_CONNECTION_TIMEOUT:60000}"
    handshake_timeout: "${TB_QUEUE_RABBIT_MQ_HANDSHAKE_TIMEOUT:10000}"
    queue-properties:

Confluent Cloud Configuration

To access Confluent Cloud you should first create an account, then create a Kafka cluster and get your API Key.

ThingsBoard Configuration

Open the Notepad or other editor as administrator user (right click on the app icon and select “Run as administrator”).
Open the following file for editing (select “All Files” instead of “Text Documents” in file choosing dialog, the encoding is UTF-8):

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

and locate “queue:” block. Make sure the queue type is “kafka”, replication factor is “3” and use confluent cloud is “true”.

Don’t forget to replace “CLUSTER_API_KEY”, “CLUSTER_API_SECRET” and “localhost:9092” with your real Confluent Cloud bootstrap servers:

1
2
3
4
5
6
7
8
9
10
11
queue:
  type: "${TB_QUEUE_TYPE:kafka}"
...
  kafka:
    bootstrap.servers: "${TB_KAFKA_SERVERS:localhost:9092}"
...
    replication_factor: "${TB_QUEUE_KAFKA_REPLICATION_FACTOR:3}"
...
    use_confluent_cloud: "${TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD:true}"
...
      sasl.config: "${TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG:org.apache.kafka.common.security.plain.PlainLoginModule required username=\"CLUSTER_API_KEY\" password=\"CLUSTER_API_SECRET\";}"

These params affect the number of requests per second from each partitions per each queue.

Number of requests to particular Message Queue calculated based on the formula:

((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues) + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS

For example, number of requests based on default parameters is:

Rule Engine queues:

Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30

Core queue 10 partitions

Transport request Queue + response Queue = 2

Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2

Total = 44

Number of requests per second = 44 * 1000 / 25 = 1760 requests

Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.

By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.

Sample parameters to fit into 10 requests per second on a “monolith” deployment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
queue:
...
  transport_api:
    request_poll_interval: "${TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS:1000}"
    response_poll_interval: "${TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  core:
    poll-interval: "${TB_QUEUE_CORE_POLL_INTERVAL_MS:1000}"
    partitions: "${TB_QUEUE_CORE_PARTITIONS:2}"
...
  vc:
    partitions: "${TB_QUEUE_VC_PARTITIONS:1}"
    poll-interval: "${TB_QUEUE_VC_INTERVAL_MS:1000}"
...
  js:
    response_poll_interval: "${REMOTE_JS_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  rule-engine:
    poll-interval: "${TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS:1000}"
...
  transport:
    poll_interval: "${TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS:1000}"

You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation.