Cluster setup using Minikube

This guide walks you through setting up ThingsBoard in cluster mode using Kubernetes and Minikube with microservices architecture. Licensing is free and requires no credit card. Docker container images are available on Docker Hub.

For a simpler single-node installation, see Docker (Linux, macOS). For production cluster deployments, see Docker Compose (Cluster).

ThingsBoard microservices run on a Kubernetes cluster. You need:

• Minikube installed
• kubectl command-line tool configured to communicate with your cluster
• Outbound internet access to pull Docker images and to reach the ThingsBoard License Portal during activation

By default the ingress addon is disabled in Minikube. Enable it:

minikube addons enable ingress

Verify that you can pull the images from Docker Hub:

docker pull thingsboard/tb-node:4.4.0
docker pull thingsboard/tb-web-report:4.4.0
docker pull thingsboard/tb-web-ui:4.4.0
docker pull thingsboard/tb-js-executor:4.4.0
docker pull thingsboard/tb-http-transport:4.4.0
docker pull thingsboard/tb-mqtt-transport:4.4.0
docker pull thingsboard/tb-coap-transport:4.4.0
docker pull thingsboard/tb-lwm2m-transport:4.4.0
docker pull thingsboard/tb-snmp-transport:4.4.0

git clone -b release-4.4.0 https://github.com/thingsboard/thingsboard-pe-k8s.git --depth 1
cd thingsboard-pe-k8s/minikube

Edit the .env file to set the database type:

nano .env

Set the DATABASE variable to one of:

You may optionally install Trendz Analytics.

docker pull thingsboard/trendz:1.16.0
docker pull thingsboard/trendz-python-executor:1.16.0

Edit trendz/trendz-secret.yml and replace YOUR_RDS_ENDPOINT_URL and YOUR_RDS_PASSWORD, then apply:

kubectl apply -f ./trendz/trendz-secret.yml
kubectl apply -f ./trendz/trendz-create-db.yml

Check the logs:

kubectl logs job/trendz-create-db -n thingsboard

./k8s-deploy-trendz.sh

You should see Trendz installed successfully! in the console output.

1. Run the installation script:

   ./k8s-install-tb.sh

2. Deploy third-party resources:

   ./k8s-deploy-thirdparty.sh

   Type yes when prompted if you are running ThingsBoard in high-availability deployment type for the first time or don’t have a configured Redis cluster.

3. Deploy ThingsBoard resources:

   ./k8s-deploy-resources.sh

After all resources start, get the cluster IP:

minikube ip

Open http://{your-cluster-ip} in your browser. On first launch you are greeted with the activation screen:

Welcome to ThingsBoard 4.4.0
Get your free license and start building

Continue with the next step to license and activate your instance.

Opening ThingsBoard in your browser for the first time shows an activation welcome screen.

Once activated, ThingsBoard prompts you to create your System Administrator account — the account that manages the platform itself (tenants, system settings, platform-wide resources).

1. Enter Email, Password, and Confirm password.
2. The Set up a demo tenant option is selected by default: it creates a ready-made tenant with dashboards, devices, and rule chains for exploring the platform before building your own solution. Clear it if you want to start with an empty platform.
3. Click Create account. You are signed in as the system administrator.

Your ThingsBoard instance is now installed and running.

List running ThingsBoard node pods:

kubectl get pods -l app=tb-node

Stream logs of a specific pod:

kubectl logs -f TB_NODE_POD_NAME

Replace TB_NODE_POD_NAME with the pod name from the list above.

Other useful commands:

See the kubectl Cheat Sheet for more commands.

For log-inspection commands, see Inspect Logs and Manage Resources above.

For more troubleshooting tips, see the Troubleshooting guide.

Delete ThingsBoard microservices:

./k8s-delete-resources.sh

Delete third-party services:

./k8s-delete-thirdparty.sh

Delete all resources including database:

./k8s-delete-all.sh

With ThingsBoard running, these concept guides help you build your first solution:

• Getting Started — a guided walkthrough of the platform after installation.
• Multi-Tenancy & Hierarchy — how tenants, customers, and users are organized.
• Digital Twin Model — how devices and assets are modeled in the platform.
• Data Processing — how the Rule Engine transforms and routes incoming data.
• Alarms & Notifications — how to detect conditions and notify users.
• Data Visualization — how to build dashboards and widgets.