Contribution Guide

ThingsBoard Community Edition is open source and the team is constantly looking for feedback on how to improve the platform. If you have an idea or a new feature in mind, open an issue on the GitHub issue tracker first — and check that a similar ticket does not already exist before submitting.

The ThingsBoard team will review and comment on your issue. Wait for that feedback before starting any implementation so the approach can be agreed on upfront.

Install the following tools before proceeding:

Fork the thingsboard/thingsboard repository on GitHub and clone it locally. The clone path is referred to as TB_WORK_DIR throughout this guide.

Build from the root folder to generate the protobuf files required for IDE compilation:

cd $TB_WORK_DIR
mvn clean install -DskipTests

Import the project into your IDE as a Maven project. See instructions for IntelliJ IDEA and Eclipse.

ThingsBoard uses PostgreSQL by default for both entities and timeseries data. Optionally, you can use Cassandra for timeseries data instead.

Install PostgreSQL using the official installation guide.

Connect to PostgreSQL and create the ThingsBoard database:

psql -U postgres -d postgres -h 127.0.0.1 -W
CREATE DATABASE thingsboard;
\q

Install Apache Cassandra, then set the timeseries database type in application/src/main/resources/thingsboard.yml:

database:
  ts:
    type: "${DATABASE_TS_TYPE:cassandra}"

If Cassandra runs on a remote host or a non-default port, update the connection settings in the same file. See the configuration guide for the full property reference.

Rebuild the application module after updating the config:

cd $TB_WORK_DIR/application
mvn clean install -DskipTests

Run the install script to create database tables and populate demo data. The script is generated during the Maven build.

On Linux:

cd $TB_WORK_DIR/application/target/bin/install
chmod +x install_dev_db.sh
./install_dev_db.sh

On Windows:

cd %TB_WORK_DIR%\application\target\windows
install_dev_db.bat

Skip this step if you are not modifying the UI.

Start the UI dev server on port 4200. REST API and WebSocket requests are forwarded to port 8080:

cd $TB_WORK_DIR/ui-ngx
mvn clean install -P yarn-start

Start the server using one of these two options.

IDE: Run the main method of org.thingsboard.server.ThingsboardServerApplication in the application module.

Command line:

java -jar application/target/thingsboard-4.3.1.1-boot.jar

Open http://localhost:4200 (with UI hot reload) or http://localhost:8080 and log in with the demo credentials:

Before committing, run the full build with tests:

mvn clean install

Also run the black-box tests.

Commit and push your changes to your fork:

git commit -m 'Descriptive commit message'
git push origin master

Create a pull request against the master branch. If conflicts exist, resolve them first.

The GitHub CLA bot prompts you to sign the Contributor License Agreement (CLA) when you open the PR.

Review may take several days.

• Rule Node Development — create custom rule nodes for ThingsBoard.
• Widgets Development — build custom widgets for ThingsBoard dashboards.