- Prerequisites
- Running
- Choose ThingsBoard queue service
- Detaching, stop and start commands
- Upgrading
- Troubleshooting
- Next steps
This guide will help you to install and start ThingsBoard using Docker on Windows.
Prerequisites
Running
Depending on the database used there are three type of ThingsBoard single instance docker images:
-
thingsboard/tb-postgres - single instance of ThingsBoard with PostgreSQL database.
Recommended option for small servers with at least 1GB of RAM and minimum load (few messages per second). 2-4GB is recommended.
-
thingsboard/tb-cassandra - single instance of ThingsBoard with Cassandra database.
The most performant and recommended option but requires at least 6GB of RAM. 8GB is recommended.
-
thingsboard/tb - single instance of ThingsBoard with embedded HSQLDB database.
Note: Not recommended for any evaluation or production usage and is used only for development purposes and automatic tests.
In this instruction thingsboard/tb-postgres
image will be used. You can choose any other images with different databases (see above).
Windows users should use docker managed volume for ThingsBoard DataBase.
Create docker volume (for ex. mytb-data
) before executing docker run command:
Open “Docker Quickstart Terminal”. Execute the following command to create docker volume:
1
2
docker volume create mytb-data
docker volume create mytb-logs
Choose ThingsBoard queue service
ThingsBoard is able to use various messaging systems/brokers for storing the messages and communication between ThingsBoard services. How to choose the right queue implementation?
-
In Memory queue implementation is built-in and default. It is useful for development(PoC) environments and is not suitable for production deployments or any sort of cluster deployments.
-
Kafka is recommended for production deployments. This queue is used on the most of ThingsBoard production environments now. It is useful for both on-prem and private cloud deployments. It is also useful if you like to stay independent from your cloud provider. However, some providers also have managed services for Kafka. See AWS MSK for example.
-
RabbitMQ is recommended if you don’t have much load and you already have experience with this messaging system.
-
AWS SQS is a fully managed message queuing service from AWS. Useful if you plan to deploy ThingsBoard on AWS.
-
Google Pub/Sub is a fully managed message queuing service from Google. Useful if you plan to deploy ThingsBoard on Google Cloud.
-
Azure Service Bus is a fully managed message queuing service from Azure. Useful if you plan to deploy ThingsBoard on Azure.
-
Confluent Cloud is a fully managed streaming platform based on Kafka. Useful for a cloud agnostic deployments.
See corresponding architecture page and rule engine page for more details.
ThingsBoard includes In Memory Queue service and use it by default without extra settings. Create docker compose file for ThingsBoard queue service:
Add the following line to the yml file:
|
Kafka InstallationApache Kafka is an open-source stream-processing software platform. Create docker compose file for ThingsBoard queue service:
Add the following line to the yml file.
|
AWS SQS ConfigurationTo 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:
Create docker compose file for ThingsBoard queue service:
Add the following line to the yml file. 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:
You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation. |
Google Pub/Sub ConfigurationTo 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. Create docker compose file for ThingsBoard queue service:
Add the following line to the yml file. 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):
You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation. |
Azure Service Bus ConfigurationTo 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. Create docker compose file for ThingsBoard queue service:
Add the following line to the yml file. 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”:
You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation. |
RabbitMQ InstallationFor installing RabbitMQ use this instruction. Create docker compose file for ThingsBoard queue service:
Add the following line to the yml file. 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:
|
Confluent Cloud ConfigurationTo access Confluent Cloud you should first create an account, then create a Kafka cluster and get your API Key. Create docker compose file for ThingsBoard queue service:
Add the following line to the yml file. Don’t forget to replace “CLUSTER_API_KEY”, “CLUSTER_API_SECRET” and “localhost:9092” with your real Confluent Cloud bootstrap servers:
{: .copy-code}\ You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation. |
Where:
8080:9090
- connect local port 8080 to exposed internal HTTP port 90901883:1883
- connect local port 1883 to exposed internal MQTT port 18837070:7070
- connect local port 7070 to exposed internal Edge RPC port 70705683-5688:5683-5688/udp
- connect local UDP ports 5683-5688 to exposed internal COAP and LwM2M ports~/.mytb-data:/data
- mounts the host’s dir~/.mytb-data
to ThingsBoard DataBase data directory~/.mytb-logs:/var/log/thingsboard
- mounts the host’s dir~/.mytb-logs
to ThingsBoard logs directorymytb
- friendly local name of this machinerestart: always
- automatically start ThingsBoard in case of system reboot and restart in case of failure.image: thingsboard/tb-postgres
- docker image, can be alsothingsboard/tb-cassandra
orthingsboard/tb
Set the terminal in the directory which contains the docker-compose.yml
file and execute the following commands to up this docker compose directly:
1
2
docker compose up -d
docker compose logs -f mytb
In order to get access to necessary resources from external IP/Host on Windows machine, please execute the following commands:
1
2
3
4
5
6
7
8
9
10
set PATH=%PATH%;"C:\Program Files\Oracle\VirtualBox"
VBoxManage controlvm "default" natpf1 "tcp-port8080,tcp,,8080,,9090"
VBoxManage controlvm "default" natpf1 "tcp-port1883,tcp,,1883,,1883"
VBoxManage controlvm "default" natpf1 "tcp-port7070,tcp,,7070,,7070"
VBoxManage controlvm "default" natpf1 "udp-port5683,udp,,5683,,5683"
VBoxManage controlvm "default" natpf1 "udp-port5684,udp,,5684,,5684"
VBoxManage controlvm "default" natpf1 "udp-port5685,udp,,5685,,5685"
VBoxManage controlvm "default" natpf1 "udp-port5686,udp,,5686,,5686"
VBoxManage controlvm "default" natpf1 "udp-port5687,udp,,5687,,5687"
VBoxManage controlvm "default" natpf1 "udp-port5688,udp,,5688,,5688"
Where:
C:\Program Files\Oracle\VirtualBox
- path to your VirtualBox installation directory
After executing this command you can open http://{your-host-ip}:8080
in you browser (for ex. http://localhost:8080
). You should see ThingsBoard login page.
Use the following default credentials:
- System Administrator: sysadmin@thingsboard.org / sysadmin
- Tenant Administrator: tenant@thingsboard.org / tenant
- Customer User: customer@thingsboard.org / customer
You can always change passwords for each account in account profile page.
Detaching, stop and start commands
You can detach from session terminal using Ctrl-p
Ctrl-q
key sequence - the container will keep running in the background.
In case of any issues you can examine service logs for errors. For example to see ThingsBoard container logs execute the following command:
1
docker compose logs -f mytb
To stop the container:
1
docker compose stop mytb
To start the container:
1
docker compose start mytb
Upgrading
In order to update to the latest image, open “Docker Quickstart Terminal” and execute the following commands:
1
2
3
4
5
$ docker pull thingsboard/tb-postgres
$ docker compose stop
$ docker run -it -v mytb-data:/data --rm thingsboard/tb-postgres upgrade-tb.sh
$ docker compose rm mytb
$ docker compose up
NOTE: if you use different database change image name in all commands from thingsboard/tb-postgres
to thingsboard/tb-cassandra
or thingsboard/tb
correspondingly.
NOTE: replace volume mytb-data
with volume used during container creation.
Troubleshooting
DNS issues
NOTE If you observe errors related to DNS issues, for example
1
127.0.1.1:53: cannot unmarshal DNS message
You may configure your system to use Google public DNS servers
Next steps
-
Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.
-
Connect your device - Learn how to connect devices based on your connectivity technology or solution.
-
Data visualization - These guides contain instructions on how to configure complex ThingsBoard dashboards.
-
Data processing & actions - Learn how to use ThingsBoard Rule Engine.
-
IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.
-
Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.
-
Advanced features - Learn about advanced ThingsBoard features.
-
Contribution and Development - Learn about contribution and development in ThingsBoard.