- Prerequisites
- Step 1. Pull ThingsBoard PE Image
- Step 2. Obtain the license key
- Step 3. Choose ThingsBoard queue service
- Step 4. Running
- Detaching, stop and start commands
- Upgrading
- Troubleshooting
- Next steps
This guide will help you to install and start ThingsBoard Professional Edition (PE) using Docker and Docker Compose on Linux or Mac OS. This guide covers standalone ThingsBoard PE installation. If you are looking for a cluster installation instruction, please visit cluster setup page.
Prerequisites
Install Docker:
Step 1. Pull ThingsBoard PE Image
1
docker pull thingsboard/tb-pe:4.0.0PE
Step 2. Obtain the license key
We assume you have already chosen your subscription plan or decided to purchase a perpetual license. If not, please navigate to pricing page to select the best license option for your case and get your license. See How-to get pay-as-you-go subscription or How-to get perpetual license for more details.
Note: We will reference the license key you have obtained during this step as PUT_YOUR_LICENSE_SECRET_HERE later in this guide.
Step 3. Choose ThingsBoard queue service
ThingsBoard platform currently supports two type of messaging brokers for storing the messages and communication between ThingsBoard services: In-memory and Kafka-based brokers.
-
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.
-
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. Don’t forget to replace “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:
|
Apache 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. Don’t forget to replace “PUT_YOUR_LICENSE_SECRET_HERE” with your license secret obtained on the first step:
|
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 “confluent.cloud:9092” with your real Confluent Cloud bootstrap servers:
You can update default Rule Engine queues configuration using UI. More about ThingsBoard Rule Engine queues see in documentation. |
Where:
PUT_YOUR_LICENSE_SECRET_HERE
- placeholder for your license secret obtained on the third step;8080:8080
- connect local port 8080 to exposed internal HTTP port 8080;1883:1883
- connect local port 1883 to exposed internal MQTT port 1883;7070:7070
- connect local port 7070 to exposed internal Edge RPC port 7070;5683-5688:5683-5688/udp
- connect local UDP ports 5683-5688 to exposed internal COAP and LwM2M ports;~/.mytbpe-data:/data
- mounts the host’s dir~/.mytbpe-data
to ThingsBoard data directory;~/.mytbpe-data/db:/var/lib/postgresql/data
- mounts the host’s dir~/.mytbpe-data/db
to Postgres data directory;~/.mytbpe-logs:/var/log/thingsboard
- mounts the host’s dir~/.mytbpe-logs
to ThingsBoard logs directory;mytbpe
- friendly local name of this machine;restart: always
- automatically start ThingsBoard in case of system reboot and restart in case of failure.;thingsboard/tb-pe:4.0.0PE
- docker image.
Step 4. Running
Before starting your Docker containers, execute the following commands to create directories for data storage and logs. These commands will also change the ownership of the newly created directories to the Docker container user.
The chown command is used to change the owner of the directories, and it requires sudo permissions. You may be prompted to enter a password to grant sudo access:
1
2
mkdir -p ~/.mytbpe-data && sudo chown -R 799:799 ~/.mytbpe-data
mkdir -p ~/.mytbpe-logs && sudo chown -R 799:799 ~/.mytbpe-logs
NOTE: replace directory ~/.mytbpe-data
and ~/.mytbpe-logs
with directories you’re planning to used in docker-compose.yml
.
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
docker compose up -d && docker compose logs -f mytbpe
After executing this command you can open http://{your-host-ip}:8080
in your 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 PE container logs execute the following command:
1
docker compose logs -f mytbpe
To stop the container:
1
docker compose stop mytbpe
To start the container:
1
docker compose start mytbpe
Upgrading
In case when database upgrade is needed:
- Stop
mytbpe
container
1
docker compose stop mytbpe
-
Update docker-compose.yml - TB image should be the latest version (see Step 3)
- In case you are upgrading to:
- 3.9.1 or newer - no additional actions required
- 3.9.0 or previous releases - change
upgradeversion
variable to your current ThingsBoard version. For ex., if upgrading from 3.6.4:1
echo '3.6.4' | sudo tee ~/.mytbpe-data/.upgradeversion
- Execute the following commands:
1
docker compose run mytbpe upgrade-tb.sh
- Start ThingsBoard:
1
docker compose up -d
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. See corresponding Linux and Mac OS instructions.
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.