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 12.17 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:5}"

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

ThingsBoard team recommends using Timescale database only for companies that already use TimescaleDB in production. In this case, ThingsBoard will be storing timeseries data in TimescaleDB Hypertable while continue to use PostgreSQL for main entities (devices/assets/dashboards/customers).

PostgreSQL Installation

Download the installation file (PostgreSQL 12.17 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”.

TimescaleDB Installation

Please refer to the official TimescaleDB installation page on Windows and follow the instructions in accordance with your installed PostgreSQL version.

After package installation, you need to create TimescaleDB extension in your ThingsBoard database:

1. Run PSQL console: Start Menu → PostgreSQL → SQL Shell (psql);
2. Login to your “thingsboard” database;
3. Run the command:

   1
   CREATE EXTENSION IF NOT EXISTS timescaledb;
   

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 “# 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:5}"

locate “DATABASE_TS_TYPE” parameter. Replace “sql” with “timescale”.

1
2
3
4
      ts:
        type: "${DATABASE_TS_TYPE:sql}" # cassandra, sql, or timescale (for hybrid mode, DATABASE_TS_TYPE value should be cassandra, or timescale)
    
    # note: timescale works only with postgreSQL database for DATABASE_ENTITIES_TYPE.

You can optionally tune parameters that refer to the Timescale DB configuration: “timescale” configuration block inside “sql” configuration block.

1
2
3
4
5
# SQL configuration parameters
sql:
    timescale:
      # Specify Interval size for new data chunks storage.
      chunk_time_interval: "${SQL_TIMESCALE_CHUNK_TIME_INTERVAL:604800000}"

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 this instruction for installing Kafka in Docker container.

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.