Cluster setup using OpenShift

This guide walks you through setting up ThingsBoard in cluster mode using OpenShift with a 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).

ThingsBoard microservices run on a Kubernetes cluster. To deploy an OpenShift cluster locally you need Docker CE and OpenShift Origin. Follow these instructions to install all required software.

You’ll also need outbound internet access to pull Docker images and to reach the ThingsBoard License Portal during activation.

By default, you can log in as the developer user:

oc login -u developer -p developer

On first start-up, create the thingsboard project:

oc new-project thingsboard

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/openshift

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

To find your ThingsBoard application URL, log in as the developer user (default password: developer), open the thingsboard project, then navigate to Application ⇾ Routes. The root route should look like https://tb-route-node-root-thingsboard.127.0.0.1.nip.io/.

Open that URL 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:

oc get pods -l app=tb-node

Stream logs of a specific pod:

oc logs -f TB_NODE_POD_NAME

Replace TB_NODE_POD_NAME with the pod name from the list above.

Other useful commands:

See the oc 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.