thingsboard · stitenko · Feb 5, 2026
diff --git 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.
+
+<hr>
 
 ## Required tools
 
 This section contains installation instructions for build tools.
 
-### Java
+<b><font size="4">Java</font></b>   
+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+.
+<b><font size="4">Maven</font></b>   
+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.
+
+<hr>
 
 ## 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
+<hr>
+
+## 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:
+- <span class="code-light">.deb</span> packages for Debian/Ubuntu
+- <span class="code-light">.rpm</span> 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:
+<b><font size="4">Unit and integration tests</font></b>
 
+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).
+<b><font size="4">Black-box tests</font></b>
 
-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
+
+<b><font size="4">Docker runtime error</font></b>
 
-- 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}
+
+This usually indicates incorrect [line endings](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreautocrlf){:target="_blank"}.
+
+<b><font size="3">Solution:</font></b>   
+- 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.