Thanks for your interest in contributing.
Use GitHub Issues for bug reports and feature requests. Search existing issues first to avoid duplicates.
Do not open a public issue for a security vulnerability. Follow the process in security.md instead.
- JDK 25
- Maven (a recent 3.9.x release)
- Docker, for the tests that use Testcontainers
Node.js and Yarn are provisioned automatically by the Maven build (frontend-maven-plugin in
ui-ngx); you don't need to install them yourself unless you're iterating on the UI directly
with yarn.
This is a multi-module Maven reactor. The top-level modules:
| Module | Contents |
|---|---|
common |
Shared server code: data models, messaging, utilities |
dao |
Persistence layer (SQL DAOs, entity services) |
rule-engine |
Rule engine core and built-in rule nodes |
transport |
Device transports (MQTT, HTTP, CoAP, LwM2M, SNMP) |
integration |
Third-party platform integrations and the integration executor |
edqs |
Entity Data Query Service |
application |
The main server application, assembling the modules above |
ui-ngx |
The Angular web UI |
msa |
Microservices packaging: per-service Docker images and the black-box test suite |
rest-client |
Java REST client for the platform API |
netty-mqtt |
Standalone Netty-based MQTT client library |
tools |
Developer and CI tooling |
packaging |
Gradle plugin, run from Maven, backing the deb/rpm/zip package builds |
monitoring |
Standalone monitoring service |
migrator |
Standalone data migration application |
report |
Report generation service |
mvn clean install -DskipTests -Dpkg.skip=true-Dpkg.skip=true skips building the deb/rpm/zip distribution artifacts, which you don't need
for day-to-day development. It's a shorthand for four finer-grained flags:
| Flag | Skips | Safe for the unit and integration tests? |
|---|---|---|
-Dpkg.skip=true |
All of the below (boot jar + deb + rpm + zip) | Yes |
-Dpkg.skip.bootjar=true |
spring-boot:repackage (*-boot.jar) |
Yes — but the boot jar is Gradle buildDeb's input, so this drops the .deb too |
-Dpkg.skip.deb=true |
Gradle buildDeb + Maven attach-artifact |
Yes — the msa/* copy of the DEB is bound to the same phase and is skipped with it |
-Dpkg.skip.rpm=true |
Gradle buildRpm |
Yes — no test depends on the RPM |
-Dpkg.skip.zip=true |
maven-assembly-plugin Windows ZIP |
Yes — no test depends on the ZIP |
None of them are safe when you are going to build the msa/* Docker images or run the black-box
suite: those need the .deb, and a build that skipped it fails on the missing artifact.
Each source file needs the project's license header. Apply it automatically before committing:
mvn license:formatBuilding the UI on its own, from ui-ngx:
yarn install
yarn start # dev server with live reload
yarn build:prod # production build
yarn lintFor a single module, scope the build with -pl/-am instead of rebuilding the whole reactor:
mvn -pl <module> -am -DskipTests -Dpkg.skip=true test-compileTo run the full backend test suite in parallel with bounded memory usage:
export MAVEN_OPTS="-Xmx1024m"
export NODE_OPTIONS="--max_old_space_size=4096"
export SUREFIRE_JAVA_OPTS="-Xmx1200m -Xss256k -XX:+ExitOnOutOfMemoryError"
# Compile and install all modules, skipping packaging artifacts not needed for tests
mvn clean install -T6 -DskipTests -Dpkg.skip=true
mvn test -pl='!application,!dao,!ui-ngx,!msa/js-executor,!msa/web-ui' -T4
mvn test -pl='msa/js-executor'
mvn test -pl dao -Dparallel=packages -DforkCount=4
mvn test -pl application -Dtest='!**/nosql/**,org.thingsboard.server.controller.**' -DforkCount=6 -Dparallel=classes -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5
mvn test -pl application -Dtest='!**/nosql/**,org.thingsboard.server.edge.**' -DforkCount=4 -Dparallel=packages -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5
mvn test -pl application -Dtest='!**/nosql/**,org.thingsboard.server.service.**' -DforkCount=6 -Dparallel=packages -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5
mvn test -pl application -Dtest='!**/nosql/**,org.thingsboard.server.transport.mqtt.**' -DforkCount=6 -Dparallel=classes -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5
mvn test -pl application -Dtest='!**/nosql/**,org.thingsboard.server.transport.coap.**' -DforkCount=6 -Dparallel=classes -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5
mvn test -pl application -Dtest='!**/nosql/**,org.thingsboard.server.transport.lwm2m.**' -DforkCount=6 -Dparallel=packages -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5
mvn test -pl application -Dtest='**/*TestSuite.java' -DforkCount=4 -Dparallel=classes -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5
# the rest of the application tests
mvn test -pl application -Dtest='
!**/nosql/**,
!org.thingsboard.server.controller.**,
!org.thingsboard.server.edge.**,
!org.thingsboard.server.service.**,
!org.thingsboard.server.transport.mqtt.**,
!org.thingsboard.server.transport.coap.**,
!org.thingsboard.server.transport.lwm2m.**,
!**/*TestSuite.java
' -DforkCount=6 -Dparallel=packages -Dsurefire.rerunFailingTestsCount=2 -Dsurefire.failOnFlakeCount=5None of this is required for a small, focused change — scope your mvn test to the module and
package you touched. This is here for running the full suite quickly when you need to.
Several dao and application tests start real databases and brokers via Testcontainers. If
they fail to start with an "unsupported Docker API version" error, your Docker Engine's API is
newer than what the Testcontainers version in this repo expects. Work around it by pinning a
minimum API version in Docker's daemon config (/etc/docker/daemon.json, or via Docker Desktop's
UI on macOS) and restarting Docker:
{
"min-api-version": "1.32"
}If Testcontainers can't find Docker at all, try removing its cached properties file so it gets recreated on the next run:
rm ~/.testcontainers.propertiesOpen a pull request against master. Fill out the pull request template, and make sure:
- New or changed behavior has test coverage.
mvn license:formathas been run, so new files carry the correct license header. Do not add your own copyright or author lines to file headers.- The change builds cleanly:
mvn -pl <module> -am -DskipTests -Dpkg.skip=true test-compileat minimum for the modules you touched. - You have signed the Contributor License Agreement (see below).
The release notes are generated from pull request titles, word for word. Write the title for the people who read them — users and customers, not reviewers:
- Describe the change in behavior, as a user sees it. Name the feature or screen and what now works differently. Leave out class names, exceptions, library versions and other internals a user can't relate to; they belong in the description.
- Use the past tense, starting with a verb such as
Fixed,Added,Updated,Improved,Removed,RenamedorMade. NotFix,AddorUpdate. - Leave out code-scope prefixes and suffixes such as
fix(ui):, ticket keys or branch names ((lts-4.3)). A product-area prefix a user recognizes is fine, followed by the verb:IoT Hub: added filtering of the catalogue by the creator's verification status.
The section an entry appears under (UI, Bug: UI, Edge, …) comes from the pull request's
labels, not its title, so don't repeat the area or the change type in the title. Changes users
don't see — CI, build, a second backport of the same fix — get the Ignore for release label
and stay out of the release notes. For anything else, such as docs or refactoring, decide
whether users would want to read about it in the release notes, and add the label if not.
| Instead of | Write |
|---|---|
fix(ui): update moment-timezone to 0.6.5 (tzdata 2026e) |
Updated UI time zone data to reflect 2026 daylight saving time changes in Canada, Morocco and Moldova |
Warn that updating a solution template recreates everything it installed |
Added a warning that updating a solution template recreates everything it installed |
Fix empty Provisioning step when navigating the device install wizard via the stepper header |
Fixed empty Provisioning step when navigating the device install wizard via the stepper header |
Before we can merge your pull request, you need to sign the ThingsBoard Contributor License Agreement (CLA). On your first pull request a bot posts a link: sign in with GitHub and accept the agreement. You sign once, and it covers all your contributions to this repository, including those made before you signed.
You keep the copyright in your contributions. The CLA grants ThingsBoard, Inc. a license to use and distribute them, including under this project's license (see LICENSE) and under commercial licenses.
If you contribute on behalf of your employer, your employer may need to sign the Corporate CLA instead. Contact info@thingsboard.io.