- Required tools
- Source code
- Build the Project
- Build local Docker images (Optional)
- Build artifacts
- Running tests (Optional)
- Tips and tricks
- Common build and runtime errors
This guide will help you to download and build ThingsBoard from source code.
Instructions listed below are tested on Ubuntu 24.04 LTS and CentOS 8/9.
Required tools
This section contains installation instructions for build tools.
Java
ThingsBoard is built using Java 17.
Install Java 17 using these instructions:
Verify the installation:
1
java -version
Maven
ThingsBoard requires Maven 3.1.0 or newer.
Note: On certain Linux machines, Maven installation may set Java 7 as the default JVM. If this happens, reconfigure your system to use Java 17.
Source code
Important: Building Docker images on Windows requires LF line endings.
To build Docker image, certain scripts, configuration files and sources that will be a part of the Docker image must have LF line endings.
So before cloning the repo set to input the Git core.autocrlf configuration option.
For example, to set core.autocrlf globally:
git config --global core.autocrlf input
Failing to do so may cause runtime errors when running Docker images.
Clone the ThingsBoard repository from GitHub:
1
2
3
# checkout latest release branch
git clone -b release-4.3 https://github.com/thingsboard/thingsboard.git --depth 1
cd thingsboard
Build the Project
From the project root directory, run:
1
mvn clean install -DskipTests
This command:
- build the project:
- skips unit and integration tests
- produces installation artifacts
Build local Docker images (Optional)
Important: Building Docker images on Windows requires LF line endings.
To build Docker image, certain scripts, configuration files and sources that will be a part of the Docker image must have LF line endings.
So before cloning the repo set to input the Git core.autocrlf configuration option.
For example, to set core.autocrlf globally:
git config --global core.autocrlf input
Failing to do so may cause runtime errors when running Docker images.
To build local Docker images for ThingsBoard services, ensure Docker is installed.
Then run:
1
mvn clean install -DskipTests -Ddockerfile.skip=false
Docker images can be listed using:
1
docker images
Build artifacts
After a successful build, installation packages are available in:
1
application/target
This directory contains:
- .deb packages for Debian/Ubuntu
- .rpm packages for CentOS/RHEL
- Windows installation packages
Running tests (Optional)
This requires Docker and Docker Compose. Make sure Docker is configured to run as a non-root user.
Note: Master and release branches are already tested, so you can skip tests and avoid installing Docker as well.
Unit and integration tests
Run all unit and integration tests:
1
mvn clean install
Black-box tests
Black-box tests are located in https://github.com/thingsboard/thingsboard/tree/master/msa/black-box-tests
Follow the instructions in the corresponding README to execute them.
Estimated runtime is approximately 1 hour, depending on hardware performance.
Tips and tricks
ThingsBoard is quite easy to build from sources on a brand-new clear environment.
Here are some tips and tricks to boost build experience:
- clean maven cache
1
rm -rf ~/.m2/repository
- clean gradle cache
1
rm -rf ~/.gradle/caches/
- clean node modules
1
rm -rf ui-ngx/node_modules
- build in parallel, format headers, build Docker images
1
mvn -T 0.8C license:format clean install -DskipTests -Ddockerfile.skip=false
Common build and runtime errors
Docker runtime error
If you see the following error when running a locally built Docker image:
1
Standard_init_linux.go:175 exec user process caused no such file
This usually indicates incorrect line endings.
Solution:
- Reconfigure Git to use LF line endings
- Re-clone the repository
- Rebuild the Docker images
Refer to the Source code section above for details.