From 9cb6496521b82cc0596975c5f4f72b4653c77c86 Mon Sep 17 00:00:00 2001 From: stitenko Date: Thu, 5 Feb 2026 16:32:05 +0200 Subject: [PATCH] Updated Building from source guide --- .../install/building-from-source.md | 111 +++++++++++++----- 1 file changed, 80 insertions(+), 31 deletions(-) diff --git a/docs/user-guide/install/building-from-source.md b/docs/user-guide/install/building-from-source.md index 4a387c6db2..f7b87f5445 100644 --- a/docs/user-guide/install/building-from-source.md +++ b/docs/user-guide/install/building-from-source.md @@ -10,44 +10,61 @@ description: Building ThingsBoard IoT platform from sources * TOC {:toc} -This guide will help you to download and build ThingsBoard from sources. Instructions listed below are tested on Ubuntu 24.04 LTS -and CentOS 8/9 +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 +Java +ThingsBoard is built using **Java 17**. + +Install Java 17 using these instructions: + +- [Install Java 17 on Ubuntu](/docs/user-guide/install/ubuntu/#step-1-install-java-17-openjdk){:target="_blank"} -ThingsBoard is built using Java 17. You can use [following instructions](/docs/user-guide/install/ubuntu/#step-1-install-java-17-openjdk) to install Java 17. +Verify the installation: -### Maven +```bash +java -version +``` +{: .copy-code} -ThingsBoard build requires Maven 3.1.0+. +Maven +ThingsBoard requires Maven 3.1.0 or newer. {% capture tabspec %}maven-installation A,Ubuntu,shell,resources/maven-ubuntu-installation.sh,/docs/user-guide/install/resources/maven-ubuntu-installation.sh B,CentOS,shell,resources/maven-centos-installation.sh,/docs/user-guide/install/resources/maven-centos-installation.sh{% endcapture %} {% include tabs.html %} -**Please note** that Maven installation may set Java 7 as a default JVM on certain Linux machines. -Use Java installation [instructions](#java) to fix this. +> 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 -{% capture windows_line_endings %} -**NOTE: Building Docker image on Windows machine** +{% capture difference %} +**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. -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](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreautocrlf) configuration option. +So before cloning the repo set to _input_ the Git [core.autocrlf](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreautocrlf){:target="_blank"} configuration option. For example, to set *core.autocrlf* globally: `git config --global core.autocrlf input`{:.language-bash} + +Failing to do so may cause runtime errors when running Docker images. + {% endcapture %} -{% include templates/warn-banner.md content=windows_line_endings %} +{% include templates/info-banner.md content=difference %} -You can clone source code of the project from the official [github repo](https://github.com/thingsboard/thingsboard). +Clone the [ThingsBoard repository](https://github.com/thingsboard/thingsboard){:target="_blank"} from GitHub: ```bash # checkout latest release branch @@ -56,53 +73,76 @@ cd thingsboard ``` {: .copy-code} -## Build +
+ +## Build the Project -Run the following command from the ThingsBoard folder to build the project: +From the project root directory, run: ```bash mvn clean install -DskipTests ``` {: .copy-code} -## Build local Docker images +This command: +- build the project: +- skips unit and integration tests +- produces installation artifacts + +## Build local Docker images (Optional) -{% include templates/warn-banner.md content=windows_line_endings %} +{% include templates/info-banner.md content=difference %} -Make sure that [Docker](https://docs.docker.com/engine/install/) is installed. +To build local Docker images for ThingsBoard services, ensure [Docker](https://docs.docker.com/engine/install/){:target="_blank"} is installed. +Then run: ```bash mvn clean install -DskipTests -Ddockerfile.skip=false ``` {: .copy-code} +Docker images can be listed using: + +```bash +docker images +``` +{: .copy-code} + ## Build artifacts -You can find debian, rpm and windows packages in the target folder: +After a successful build, installation packages are available in: ```bash application/target ``` {: .copy-code} -## Running tests +This directory contains: +- .deb packages for Debian/Ubuntu +- .rpm packages for CentOS/RHEL +- Windows installation packages -We are using [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) to run all kinds of integration and [black-box tests](https://github.com/thingsboard/thingsboard/tree/master/msa/black-box-tests). +## Running tests (Optional) -Please, manage [Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) to run tests properly. +This requires [Docker](https://docs.docker.com/engine/install/){:target="_blank"} and [Docker Compose](https://docs.docker.com/compose/install/){:target="_blank"}. Make sure [Docker is configured to run as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user){:target="_blank"}. -Master and release branches are already tested, so you can skip tests and avoid installing Docker as well. +> **Note:** Master and release branches are already tested, so you can skip tests and avoid installing Docker as well. -Run all unit and integration tests: +Unit and integration tests +Run all unit and integration tests: ```bash mvn clean install ``` {: .copy-code} -To run black-box tests, please refer [black-box tests readme](https://github.com/thingsboard/thingsboard/blob/master/msa/black-box-tests/README.md). +Black-box tests -Estimated time is about 1 hour on AMD Ryzen 5 3600 (6-cores), 32GB DDR4, fancy SSD and shiny weather. Actual time may vary and depends on particular hardware performance. +Black-box tests are located in [https://github.com/thingsboard/thingsboard/tree/master/msa/black-box-tests](https://github.com/thingsboard/thingsboard/tree/master/msa/black-box-tests){:target="_blank"} + +Follow the instructions in the corresponding [README](https://github.com/thingsboard/thingsboard/blob/master/msa/black-box-tests/README.md){:target="_blank"} to execute them. + +> Estimated runtime is approximately 1 hour, depending on hardware performance. ## Tips and tricks @@ -134,12 +174,21 @@ Here are some tips and tricks to boost build experience: ``` {: .copy-code} -## Build and runtime errors +## Common build and runtime errors + +Docker runtime error -- If you see such errors when running locally-built Docker image, re-clone the repo with **LF** [file ending](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreautocrlf) and re-build the image. -To fix this read [Source code](#source-code) section. +If you see the following error when running a locally built Docker image: ```bash Standard_init_linux.go:175 exec user process caused no such file ``` -{: .copy-code} \ No newline at end of file + +This usually indicates incorrect [line endings](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreautocrlf){:target="_blank"}. + +Solution: +- Reconfigure Git to use LF line endings +- Re-clone the repository +- Rebuild the Docker images + +Refer to the [Source code](#source-code) section above for details.