Cluster setup using OpenShift

This guide walks you through setting up ThingsBoard Professional Edition in cluster mode using OpenShift with microservices architecture. Docker container images are available on Docker Hub.

For a simpler single-node installation, see Docker (Linux, macOS).

Prerequisites

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.

Log in to OpenShift cluster

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

oc login -u developer -p developer

Create project

On first start-up, create the thingsboard project:

oc new-project thingsboard

Pull ThingsBoard PE images

Verify that you can pull the images from Docker Hub:

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

Step 1. Clone ThingsBoard PE Kubernetes scripts

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

Step 2. Obtain and configure the license key

We assume you have already chosen your subscription plan or decided to purchase a perpetual license. If not, navigate to the pricing page to select the best license option for your case. See How to get a pay-as-you-go subscription or How to get a perpetual license for details.

Edit the ThingsBoard node configuration:

nano tb-node.yml

Find the TB_LICENSE_SECRET environment variable and replace PUT_YOUR_LICENSE_SECRET_HERE with your actual license secret:

- name: TB_LICENSE_SECRET
  value: "PUT_YOUR_LICENSE_SECRET_HERE"

Step 3. Configure database

Edit the .env file to set the database type:

nano .env

Set the DATABASE variable to one of:

Value	Description
`postgres`	Use PostgreSQL for all data
`hybrid`	Use PostgreSQL for entities and Cassandra for time-series data

Step 4. Configure Trendz Analytics (optional)

You may optionally install Trendz Analytics.

Pull Trendz images

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

Create Trendz database

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

Deploy Trendz

./k8s-deploy-trendz.sh

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

Step 5. Install and start ThingsBoard

Run the installation script:
Terminal window
```
./k8s-install-tb.sh --loadDemo
```
The --loadDemo flag loads sample tenant account, dashboards, and devices for evaluation and testing.
Deploy third-party resources:
Terminal window
```
./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.
Deploy ThingsBoard resources:
Terminal window
```
./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/.

You should see the ThingsBoard login page. Use the following default credentials:

System Administrator: [email protected] / sysadmin
Tenant Administrator: [email protected] / tenant
Customer User: [email protected] / customer

You can change passwords for each account in the account profile page.

See Getting Started for your next steps after login.

Inspect logs and manage resources

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:

Command	Description
`oc get pods`	List all pods
`oc get services`	List all services
`oc get deployments`	List all deployments

See the oc Cheat Sheet for more commands.

Cleanup

Delete ThingsBoard microservices:

./k8s-delete-resources.sh

Delete third-party services:

./k8s-delete-thirdparty.sh

Delete all resources including database:

./k8s-delete-all.sh

Upgrading

Upgrading ThingsBoard

Pull the latest changes from the repository:

git pull origin master

Then run the upgrade:

./k8s-delete-resources.sh
./k8s-upgrade-tb.sh
./k8s-deploy-resources.sh

Upgrading Trendz

Pull the latest changes and run the upgrade:

git pull origin master
./k8s-upgrade-trendz.sh